GPII-2307: Add combined code coverage reports.

.gitignore

@@ -13,3 +13,7 @@ Vagrantfile.local
 .vagrant/
 
 report.tap
+coverage
+.nyc_output
+instrumented
+reports

Gruntfile.js

@@ -29,49 +29,12 @@ module.exports = function (grunt) {
                 enableJSON5: true
             },
             src: ["gpii/**/*.json5", "tests/**/*.json5", "testData/**/*.json5", "*.json5"]
-        },
-        shell: {
-            options: {
-                stdout: true,
-                stderr: true,
-                failOnError: true,
-                execOptions: {
-                    maxBuffer: Infinity
-                }
-            },
-            runBrowserTests: {
-                command: "vagrant ssh -c 'cd /home/vagrant/sync/node_modules/universal; DISPLAY=:0 testem ci --file tests/web/testem_qi.json'"
-            },
-            runNodeTests: {
-                command: "vagrant ssh -c 'cd /home/vagrant/sync/node_modules/universal; npm test'"
-            },
-            runNodeProductionTests: {
-                command: "vagrant ssh -c 'cd /home/vagrant/sync/node_modules/universal; node tests/ProductionConfigTests.js'"
-            }
         }
     });
 
     grunt.loadNpmTasks("fluid-grunt-eslint");
     grunt.loadNpmTasks("grunt-jsonlint");
     grunt.loadNpmTasks("fluid-grunt-json5lint");
-    grunt.loadNpmTasks("grunt-shell");
-
-    grunt.registerTask("browser-tests", "Run browser tests in a VM", function () {
-        grunt.task.run("shell:runBrowserTests");
-    });
-
-    grunt.registerTask("node-tests", "Run Node tests in a VM", function () {
-        grunt.task.run("shell:runNodeTests");
-    });
-
-    grunt.registerTask("node-production-tests", "Run Node production tests in a VM", function () {
-        grunt.task.run("shell:runNodeProductionTests");
-    });
-
-    grunt.registerTask("tests", "Run browser and node tests in a VM", function () {
-        grunt.task.run("shell:runBrowserTests");
-        grunt.task.run("shell:runNodeTests");
-    });
 
     grunt.registerTask("lint", "Apply jshint, jsonlint and json5lint", ["eslint", "jsonlint", "json5lint"]);
 };

README.md

@@ -1,26 +1,27 @@
 GPII Universal
 ==============
 
-Cross platform, core components of the GPII personalization infrastructure. This repository should not be used directly,
-but in conjunction with one of the top-level GPII architecture-specific repositories. Documentation for this project is
-housed beneath http://wiki.gpii.net/w/Architecture .
+The package contains cross-platform core components of the GPII personalization infrastructure. This repository should
+not be used directly, but in conjunction with one of the top-level GPII architecture-specific repositories.
+Additional documentation is available [on our wiki](http://wiki.gpii.net/w/Architecture).
 
 Installation
 ------------
 
-In production, this repository should be installed using one of the top-level GPII architecture-specific repositories -
-  * windows - https://github.com/GPII/windows
-  * linux - https://github.com/GPII/linux
-  * android - https://github.com/GPII/android
+In production, this repository should be installed using one of the top-level GPII architecture-specific repositories:
 
-For development purposes this repository could be cloned directly.
+  * [windows](https://github.com/GPII/windows)
+  * [linux](https://github.com/GPII/linux)
+  * [android](https://github.com/GPII/android)
+
+For development purposes this repository can also be cloned directly.
 
 Quick Start
 -----------
 
 To verify the basic installation of GPII universal, you can start the core framework with
 
-    npm start
+`npm start`
 
 If all is well, you will see a message like
 
@@ -44,70 +45,107 @@ Testing
 -------
 
 There are currently 3 different sets of tests:
-* the ones that run in the browser
-* the ones run in node.js
-* production tests, running in node.js but having external requirements
+
+* Tests that run in the browser
+* Tests that run in node.js
+* Production tests, that run in node.js, but which interact with external services.
+
+The `npm test` command will run the browser and Node based tests.  Please note, the node tests may behave oddly if you
+have set the `NODE_ENV` variable.
 
 #### Running browser tests:
-open `{universal}/tests/web/html/all-tests.html` in your preferred browser
+
+You can run the browser tests in this package with a range of browsers using [Testem](https://github.com/testem/testem),
+and the configuration file `tests/testem.js`, which will ensure that code coverage information is collected.  From the
+root of the `universal` folder, run the following command:
+
+`npm run test:browser`
+
+You can also run (and debug) the tests manually by running `testem --file tests/testem.js` from the root of the
+repository.  The required test fixtures and testem will start, and Testem will provide a URL you can open in a browser.
+
+If you would like to debug individual tests or view the test summary in a browser without using Testem, you can:
+
+1. Host the working directory, for example, using a command like the following from the root of the repository: `python -m SimpleHTTPServer 4103`
+2. Open the "rollup" file `tests/all-tests.html` that runs all tests in a browser.  Continuing the above example, you would load the URL `http://localhost:4103/tests/web/html/all-tests.html`.
+
 
 #### Running node-based tests
+
 From the root of the `universal` folder, run the following command:
 
-    npm test
+`npm run test:node`
+
+Please note, the node tests may behave oddly if you have set the `NODE_ENV` variable.
 
 #### Running tests using a VM
-A VM can be automatically created using tools provided by the [Prosperity4All Quality Infrastructure](https://github.com/GPII/qi-development-environments/). Please ensure the [requirements](https://github.com/GPII/qi-development-environments/#requirements) have been met. The ``vagrant up`` command can then be used to provision a new VM.
 
-Within the VM, the application will be installed in the directory specified by the nodejs_app_install_dir variable, which is defined in the provisioning/vagrant-vars.yml configuration file in this repository. By default it is set to "/home/vagrant/sync/node_modules/universal".
+A VM can be automatically created using tools provided by the
+[Prosperity4All Quality Infrastructure](https://github.com/GPII/qi-development-environments/). Please ensure the
+[requirements](https://github.com/GPII/qi-development-environments/#requirements) have been met. The `vagrant up`
+command can then be used to provision a new VM.
+
+Within the VM, the application will be installed in the directory specified by the `nodejs_app_install_dir` variable,
+which is defined in `provisioning/vagrant-vars.yml` configuration file in this repository. By default the installation
+ directory is set to `/home/vagrant/sync/node_modules/universal`.
 
-Following the provisioning phase, tests can be run in the VM directly from the host system, without the need to log into the VM or interact with its console. 
+Following the provisioning phase, tests can be run in the VM directly from the host system, without the need to log
+into the VM or interact with its console.
 
-From your project's top-level directory (where the Vagrantfile and Gruntfile.js files reside), run:
+From your project's top-level directory (where the `Vagrantfile` and `package.json` files reside), run:
 
-- node-based tests: `grunt node-tests`
-- browser-based tests: `grunt browser-tests`
-- production tests: `grunt node-production-tests`
+- Node and browser tests: `npm run test:vagrant`
+- Node tests only: `npm run test:vagrantNode`
+- browser tests only: `npm run test:vagrantBrowser`
+- production tests: `npm run test:vagrantProduction`
 
-The ``grunt tests`` command will run the browser and Node based tests.
 
-These Grunt tasks will run the correct Vagrant commands to connect to the VM and run the tests within the isolated environment. You can also run `vagrant ssh` to connect to the VM (or open the VirtualBox console and interface with the desktop environment) and run the tests manually if you wish.
+You can also run `vagrant ssh` to connect to the VM (or open the VirtualBox console and interface with the desktop
+environment) and run the tests manually if you wish.
 
 Usage
 -----
 
-To use any of the gpii components or functionality in node.js, use the
+To use any of the gpii components or functionality in Node.js, use the
 following statements to get access to fluid and/or gpii objects.
 
-    var fluid = require("universal"),
-        gpii = fluid.registerNamespace("gpii");
-    // Now you will have access to both fluid and gpii namespaces.
+```
+var fluid = require("universal"),
+    gpii = fluid.registerNamespace("gpii");
+// Now you will have access to both fluid and gpii namespaces.
+```
 
 
 #### Running node-based production tests
-The purpose of these tests are to test production config setups of the system. This involves using the online preferences server when fetching preferences sets, so there are extended requirements for these tests.
+The purpose of these tests are to test production config setups of the system. This involves using the online
+preferences server when fetching preferences sets, so there are extended requirements for these tests.
 
-These tests are a supplement to the `all-tests.js` (and hence not part of that test suite) and should be run separately when testing the system and having the below requirements available.
+These tests are a supplement to the `all-tests.js` (and hence not part of that test suite) and should be run separately
+when testing the system and having the below requirements available.
 
 Requirements:
 * an internet connection
 * a preferences server running at `http://preferences.gpii.net` containing at least the following (unmodified) NP set: `MikelVargas`
 
 The tests are run using the following command:
 
-    node tests/ProductionConfigTests.js
+`node tests/ProductionConfigTests.js`
 
 
 Building Docker Images
 ----------------------
 
-The Dockerfile can be used to build a containerized version of GPII Universal, at this time primarily for use by downstream containers running components such the Preferences Server and Flow Manager in standalone cloud configuration.
+The Dockerfile can be used to build a containerized version of GPII Universal, at this time primarily for use by
+downstream containers running components such the Preferences Server and Flow Manager in standalone cloud configuration.
 
-The following command can be used to build an image locally as long as it is run relative to the repository's Dockerfile:
+The following command can be used to build an image locally as long as it is run relative to the repository's
+`Dockerfile`:
 
 `docker build --rm -t gpii/universal:$(git rev-parse --short HEAD) .`
 
-That will use the Git repository's current abbreviated commit hash as a [Docker tag](https://docs.docker.com/reference/commandline/cli/#tag). If you would like to download the latest public Universal image you can use this command:    
+That will use the Git repository's current abbreviated commit hash as a
+[Docker tag](https://docs.docker.com/reference/commandline/cli/#tag). If you would like to download the latest public
+Universal image you can use this command:
 
 `docker pull gpii/universal`