Merge remote-tracking branch 'tony/GPII-2307'

* tony/GPII-2307:
  GPII-2307:  Removed original `cwd` workaround and the workaround for the problems that caused.
  GPII-2307: Disabled non-passing IE tests for now.
  GPII-2307: Committed fix for Windows "403" errors when running browser tests.
  NOJIRA: Added `.idea` directory to `.gitignore`.
  GPII-2307:  Updated to gpii-pouchdb 1.0.2.  Refactored to avoid double-instrumentation.
  GPII-2307: Removed unneeded coverage client dependencies per PR feedback.
  GPII-2307: Removed `yarn.lock` for the time being.
  GPII-2307:  Removed duplicated, commented includes, and simplified all includes to omit the `type`.
  GPII-2307:  Added `posttest` to the list of "scripts you should not need to run manually".
  GPII-2307: Added `.nyc_output` to pretest cleanup.
  GPII-2307:  Added a section on code covfefe to the README.
  GPII-2307:  Added information about the need for the browser to be "in focus" when running browser tests locally.
  GPII-2307: Removed "skip" options for Safari and Opera.
  GPII-2307:  Added instrumentation steps to individual npm scripts.  Skipped PhantomJS and Opera in browser tests.
  Added a warning about 404 console errors when hosting the tests in python, MAMP, et cetera.
  Cleaned up absolute path to QUnit CSS and removed duplicate include of canopy matchmaker tests.
  GPII-2307: Relativised remaining paths in all-tests.html.
  GPII-2307: Removed cruft from (now unneeded) "testDefs" approach.
  GPII-2307: Updated to latest testem and gpii-testem.
  GPII-2307: Relativised all paths to dependencies to support local browser testing outside of Testem.
  NOJIRA: Removed 'skip' rules, all available browser launchers will be used by default...
  GPII-2307:  Standardized gpii-testem work to include only minimum fixes required to avoid "browser disconnect" errors.
  Committed work in progress on "testDefs" branch.  All tests working consistently.
  GPII-2307: Updated to use `testDef` pattern per PR feedback.
  GPII-2307: Removed working notes in checking browser code coverage completeness.
  GPII-2307: Updated `testem.js` to bypass QUnit composite, which resolves "browser disconnect" errors.
  GPII-2307: Added combined code coverage and reporting.

.gitignore

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

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,133 @@ 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`
+
+Please note, when running the browser tests locally using this command, the tests will fail on some browsers 
+(notably Firefox, Safari, and Opera) unless the browser has focus.  You can manually click the browser when it launches
+to give it focus.  You should not give another window focus until the tests complete.  This is not a problem when
+running the browser tests in Vagrant (see below).  It's also not a problem when running the tests in Chrome, which you
+can do using a command like:
+
+`npm run test:browser -- --launch Chrome`
+
+You can also run (and debug) the tests manually from the root of the repository using a command like:
+
+`node node_modules/testem/testem.js --file tests/testem.js` 
+
+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`.
+
+Please note, when hosting the tests yourself, you may see multiple 404 errors related to the `/testem.js` and
+`/coverage/client/coverageSender.js` files which are provided by Testem and the `gpii.testem` harness respectively.
+These 404 errors will not cause any tests to fail and can be safely ignored.
 
 #### 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`
+
+#### Coverage Reporting
+
+The preferred way to consistentely generate a code coverage report is to use Vagrant as described above.  When you 
+start a VM using `vagrant up` and run `npm run test:vagrant`, the full test suite will run in the VM,  and a coverage 
+report will be saved to the `reports` directory.  You can also run the `npm test` command on your local machine, but 
+you will need to ensure that browsers receive focus when they are launched (see above).
 
+The `npm test` command has [two additional associated scripts](https://docs.npmjs.com/misc/scripts).  The `pretest`
+script runs before the command defined for the `test` script.  The `posttest` script runs after.  In our case
+we use a `pretest` script to clean up previous coverage data before we run the tests, and a `posttest` script to 
+compile the actual report.  You should not need to run the `pretest` scripts manually before running either the node or
+browser tests, or to run the `posttest` scripts afterward.
 
 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`