[API Refactor] Update documentation

...to reflect new manner in which tests are run.

README.md

@@ -43,29 +43,24 @@ that Open MCT Web (and its build and tests) execute correctly.
 
 ## Tests
 
-The repository for Open MCT Web includes a test suite that can be run
-directly from the web browser, `test.html`. This page will:
+Tests are written for [Jasmine 1.3](http://jasmine.github.io/1.3/introduction.html)
+and run by [Karma](http://karma-runner.github.io). To run:
 
-* Load `bundles.json` to determine which bundles are in the application.
-* Load `test/suite.json` to determine which source files are to be tested.
-  This should contain an array of strings, where each is the name of an
-  AMD module in the bundle's source directory. For each source file:
-  * Code coverage instrumentation will be added, via Blanket.
-  * The associated test file will be loaded, via RequireJS. These will
-    be located in the bundle's test folder; the test runner will presume
-    these follow a naming convention where each module to be tested has a
-    corresponding test module with the suffix `Spec` in that folder.
-* Jasmine will then be invoked to run all tests defined in the loaded
-  test modules. Code coverage reporting will be displayed at the bottom
-  of the test page.
+`npm test`
 
-At present, the test runner presumes that bundle conventions are followed
-as above; that is, sources are contained in `src`, and tests are contained
-in `test`. Additionally, individual test files must use the `Spec` suffix
-as described above.
+The test suite is configured to load any scripts ending with `Spec.js` found
+in the `src` hierarchy. Full configuration details are found in
+`karma.conf.js`. By convention, unit test scripts should be located
+alongside the units that they test; for example, `src/foo/Bar.js` would be
+tested by `src/foo/BarSpec.js`. (For legacy reasons, some existing tests may
+be located in separate `test` folders near the units they test, but the
+naming convention is otherwise the same.)
+
+### Test Reporting
+
+When `npm test` is run, test results will be written as HTML to
+`target/tests`. Code coverage information is written to `target/coverage`.
 
-An example of this is expressed in `platform/framework`, which follows
-bundle conventions.
 
 ### Functional Testing
 
@@ -84,8 +79,7 @@ To run:
 
 Open MCT Web includes a Maven command line build. Although Open MCT Web
 can be run as-is using the repository contents (that is, by viewing
-`index.html` in a web browser), and its tests can be run in-place
-similarly (that is, by viewing `test.html` in a browser), the command
+`index.html` in a web browser), the command
 line build allows machine-driven verification and packaging.
 
 This build will:
@@ -93,8 +87,7 @@ This build will:
 * Check all sources (excluding those in directories named `lib`) with
   JSLint for code style compliance. The build will fail if any sources
   do not satisfy JSLint.
-* Run unit tests. This is done by running `test.html` in a PhantomJS
-  browser-like environment. The build will fail if any tests fail.
+* Run the [unit test suite](#tests).
 * Package the application as a `war` (web archive) file. This is
   convenient for deployment on Tomcat or similar. This archive will
   include sources, resources, and libraries for bundles, as well

docs/src/guide/index.md

@@ -407,7 +407,7 @@ In addition to the directories defined in the bundle definition, a bundle will
 typically contain other directories not used at run-time. Additionally, some 
 useful development scripts (such as the command line build and the test suite) 
 expect this directory structure to be in use, and may ignore options chosen by 
-`b undle.json`. It is recommended that the directory structure described below be 
+`bundle.json`. It is recommended that the directory structure described below be
 used for new bundles.
 
 * `src`: Contains JavaScript sources for this bundle. May contain additional 
@@ -2263,50 +2263,31 @@ download build dependencies.
 
 ## Test Suite
 
-Open MCT Web uses Jasmine http://jasmine.github.io/ for automated testing. 
-The file `test.html` included at the top level of the source repository, can be 
-run from the browser to perform tests for all active bundles, as defined in 
-`bundle.json`.
+Open MCT Web uses [Jasmine 1.3](http://jasmine.github.io/) and
+[Karma](http://karma-runner.github.io) for automated testing.
 
-To define tests for a bundle:
+The test suite is configured to load any scripts ending with `Spec.js` found
+in the `src` hierarchy. Full configuration details are found in
+`karma.conf.js`. By convention, unit test scripts should be located
+alongside the units that they test; for example, `src/foo/Bar.js` would be
+tested by `src/foo/BarSpec.js`. (For legacy reasons, some existing tests may
+be located in separate `test` folders near the units they test, but the
+naming convention is otherwise the same.)
 
-* Include a directory named `test` within that bundle.
-* In the `test` directory, include a file named `suite.json`. This will identify 
-which scripts will be tested.
-* The file `suite.json` must contain a JSON array of strings, where each string 
-is the name of a script to be tested. These names should include any directory 
-paths to the script after (but not including) the `src` folder, and should not 
-include the file's `.js` extension. (Note that while Open MCT Web's framework 
-allows a different name to be chosen for the src directory, the test runner 
-does not: This directory must be named `src` for the test runner to find it.)
-* For each script to be tested, a corresponding test script should be located in 
-the bundle's `test` directory. This should include the suffix Spec at the end of 
-the filename (but before the `.js` extension.) This test script should be an AMD 
-module which uses the Jasmine API to declare its test behavior. It should 
-declare an AMD dependency on the script to be tested, using a relative path.
-
-For example, if writing tests for a bundle at example/foo with two scripts:
-* `example/foo/src/controllers/FooController.js`
-* `example/foo/src/directives/FooDirective.js`
-
-First, these scripts should be identified in `example/foo/test/suite.json` e.g. 
-with contents:`[ "controllers/FooController", "directives/FooDirective" ]`
-
-Then, scripts which describe these tests should be written. For example, test 
-`example/foo/test/controllers/FooControllerSpec.js` could look like:
+Tests are written as AMD modules which depend (at minimum) upon the
+unit under test. For example, `src/foo/BarSpec.js` could look like:
 
     /*global define,Promise,describe,it,expect,beforeEach*/
 
     define(
-        ["../../src/controllers/FooController"],
-        function (FooController) {
+        ["./Bar"],
+        function (Bar) {
             "use strict";
-    
-    
-            describe("The foo controller", function () {
+
+            describe("Bar", function () {
                 it("does something", function () {
-                    var controller = new FooController();
-                    expect(controller.foo()).toEqual("foo");
+                    var bar = new Bar();
+                    expect(controller.baz()).toEqual("foo");
                 });
             });
         }