Merge remote-tracking branch 'upstream/main'

.github/workflows/main.yml

@@ -13,27 +13,34 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [12.x, 14.x]
+        node-version: [16.x, 18.x]
 
     env:
       HEADLESS: true
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
 
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v3
         with:
           node-version: ${{ matrix.node-version }}
 
       - name: Install Node.js dependencies
         run: npm install
 
-      - name: Lint Code
-        run: npm run lint
-
       - name: Node Tests
         run: xvfb-run --auto-servernum npm test
 
+      - name: Archive Code Coverage Report
+        continue-on-error: true
+        uses: actions/upload-artifact@v3
+        with:
+          name: Code Coverage Report
+          path: reports/
+
       - name: Cleanup after xvfb
         uses: bcomnes/cleanup-xvfb@v1
+
+      - name: Lint Code
+        run: npm run lint

README.md

@@ -69,13 +69,13 @@ For more information, check out the documentation links below:
 You can run the tests using the command `npm test`.  You are not required to have Testem installed globally to run the
 tests.
 
-## A Warning about Internet Explorer 11
+## Running the tests in "Headless" Mode
 
-There is currently [a bug in Testem](https://github.com/testem/testem/issues/1184) that results in IE11 windows opened
-by Testem not being closed when the tests finish.  Until that bug is resolved, if you are running tests from Windows,
-you will need to close any open IE11 windows before launching the tests.
+The default testem component provided by this package supports an environment variable that can be used to only run
+tests in a subset of available browsers. (See [the component documentation](docs/testem-component.md) for more details).
+Setting the `TESTEM_ENVIRONMENT` environment variable to `"headless"` will run tests using only headless Chrome and
+Firefox.
 
-## Running (Chrome) in "Headless" Mode
-
-If your system has [a new enough version of Chrome](https://developers.google.com/web/updates/2017/04/headless-chrome),
-you can optionally run the tests in "headless" mode by setting the `HEADLESS` environment variable to a non-empty value.
+Note: because of [a bug in Testem](https://github.com/testem/testem/issues/1377), tests that use Firefox require manual
+input to complete on Windows.  Setting the `TESTEM_ENVIRONMENT` environment variable to `"headless"` will allow tests to
+run unattended on Windows.

docs/testem-component.md

@@ -1,18 +1,63 @@
 # `fluid.testem`
 
-The `fluid.testem` component is designed to:
+The `fluid.testem` component is designed to launch browser-based tests in one or more browsers.  By default, this
+component:
 
-1. Instrument the code under test.
-2. Start test fixtures.
-3. Run Testem tests.
-4. Prepare a coverage report.
-5. Clean up temporary files (instrumented source, browser data, coverage data).
+1. Instruments the code under test.
+2. Starts test fixtures.
+3. Runs Testem tests.
+4. Prepares a coverage report.
+5. Cleans up temporary files (instrumented source, browser data, coverage data).
 
-For basic usage instructions and requirements, see the [README file](../README.md).  For detailed configuration options,
-see below.
+## Environment Variables
+
+The default grade `fluid.testem` supports a handful of environment variables that modify its behaviour.  If you need
+more control than these switches, you should consider extending one of the underlying grades instead (see below).
+
+### `DISABLE_COVERAGE`
+
+If this option is set, code will not be instrumented.  This intended to support things like launching a configuration
+file and debugging test problems locally, as in this example command on a system that supports a unix-like shell:
+
+```shell
+DISABLE_COVERAGE=true node node_modules/testem/testem.js --file tests/testem.js
+```
+
+If you want to permanently disable instrumentation, you should look at the `fluid.testem.coverage` grade described
+below.
+
+### `TESTEM_ENVIRONMENT`
+
+To help streamline local testing, two predefined "environments" are supported.  These override the default testem
+options to launch a minimal subset of browsers (only Firefox and Chrome).  This is intended for cases in which you want
+to be able to test for maximum compatibility by default, and to more quickly test incremental changes by only running
+a subset of the available browsers.  On a system that supports a unix-like shell, you might use this functionality with
+commands like the following:
+
+```shell
+TESTEM_ENVIRONMENT=headless npm test
+
+TESTEM_ENVIRONMENT=headed node node_modules/testem/testem.js --file tests/testem.js
+```
+
+The supported values are `"headed"` and `"headless"`, each of which is described below.
+
+#### "headed"
+
+The "minimal headed" environment launches only Firefox and Chrome.  Note that if you do not have either of these
+installed, runs launched with this environment will fail.  Note also that because of
+[a bug in testem](https://github.com/testem/testem/issues/1377), Firefox will not close itself when it is launched
+"headed" on Windows.
+
+#### "headless"
+
+The "minimal headless" environment launches only Headless Firefox and Headless Chrome.  Note that if you do not have
+either of these installed, runs launched with this environment will fail.
 
 ## Component Options
 
+These are the options supported by the default `fluid.testem` component when it is run with no environmental variables:
+
 | Option                    | Type        | Description                           |
 | ------------------------- | ----------- | ------------------------------------- |
 | `cwd`                     | `{String}`  | Defaults to `process.cwd()`, i.e. the directory from which the script was called. |
@@ -138,11 +183,9 @@ so that combined reports can be prepared.
 
 #### Additional Components
 
-##### `fluid.testem.instrumentation`
+##### `fluid.testem.base`
 
-This grade instruments source itself and collects coverage data, but does not prepare a report at the end or remove the
-coverage data during its cleanup phase.  It is provided for use in combining reports from different test runs, such
-as when running node tests and browser tests in the same package.  See below for a detailed example.
+The underlying base grade, without any instrumentation, coverage collection, or coverage reporting.
 
 ##### `fluid.testem.coverage`
 
@@ -152,6 +195,18 @@ your instrumented code to use this grade.  This grade only removes the temporary
 not any pre-instrumented code or coverage data.  This grade is mainly provided for legacy setups, in almost all cases
 you should use the`fluid.testem.instrumentation` grade instead.
 
+##### `fluid.testem.instrumentation`
+
+This grade instruments source itself and collects coverage data, but does not prepare a report at the end or remove the
+coverage data during its cleanup phase.  It is provided for use in combining reports from different test runs, such
+as when running node tests and browser tests in the same package.  See below for a detailed example.
+
+##### `fluid.testem.coverageReporting`
+
+This grade instruments code, collects coverage data, and generates a coverage report.  If you are testing non-browser
+code such as node scripts, if you save the coverage reporting data to the same directory, you can run this grade after
+your node tests to produce a combined report.
+
 #### Example: Combining Node Coverage with Browser Coverage.
 
 The key to preparing a combined report is to ensure that:

package.json

@@ -11,7 +11,7 @@
     },
     "scripts": {
         "lint": "fluid-lint-all",
-        "pretest": "rimraf coverage/* reports/* instrumented/*",
+        "pretest": "rimraf coverage reports instrumented",
         "test": "nyc node tests/all-tests.js"
     },
     "repository": {
@@ -25,23 +25,23 @@
     },
     "homepage": "https://github.com/fluid-project/fluid-testem/",
     "dependencies": {
-        "glob": "7.1.6",
-        "fluid-express": "1.0.16",
-        "infusion": "3.0.0-dev.20201113T153152Z.32176dcbe.FLUID-6145",
-        "istanbul-lib-instrument": "4.0.3",
-        "mkdirp": "1.0.4",
-        "node-jqunit": "1.1.8",
+        "glob": "8.1.0",
+        "fluid-express": "1.0.19",
+        "infusion": "4.6.0",
+        "istanbul-lib-instrument": "5.2.1",
+        "mkdirp": "2.1.3",
+        "node-jqunit": "1.1.9",
         "nyc": "15.1.0",
-        "rimraf": "3.0.2",
-        "testem": "3.2.0"
+        "rimraf": "4.1.2",
+        "testem": "3.10.1"
     },
     "devDependencies": {
-        "eslint": "7.17.0",
-        "eslint-config-fluid": "2.0.0",
-        "form-data": "3.0.0",
-        "fluid-lint-all": "1.0.0",
+        "eslint": "8.34.0",
+        "eslint-config-fluid": "2.1.1",
+        "form-data": "4.0.0",
+        "fluid-lint-all": "1.2.6",
         "fluid-webdriver": "1.1.2",
-        "kettle": "2.0.0",
+        "kettle": "2.3.0",
         "qunitjs": "2.4.1"
     }
 }

src/js/lib/pathUtils.js

@@ -20,6 +20,7 @@ fluid.testem.extractLastPathSegment = function (rawPath, leader) {
     return fluid.testem.forceLeadingSlash(path.basename(resolvedPath), leader);
 };
 
+/* eslint-disable jsdoc/require-returns-check */
 /**
  *
  * Ensure that the path segment is preceded by a leader (defaults to a leading slash).
@@ -29,6 +30,7 @@ fluid.testem.extractLastPathSegment = function (rawPath, leader) {
  * @return {String} - The path, updated as needed to ensure that it begins with `leader`.
  *
  */
+/* eslint-enable jsdoc/require-returns-check */
 fluid.testem.forceLeadingSlash = function (rawPath, leader) {
     leader = (leader || leader === "") ? leader : "/";
     if (typeof rawPath === "string") {

src/js/lib/resolveSafely.js

@@ -18,13 +18,15 @@ fluid.testem.resolvePathSafely = function (basePath, subPath) {
     }
 };
 
+/* eslint-disable jsdoc/require-returns-check */
 /**
  *
  * Another wrapper to ensure that invalid or missing paths do not break the overall lifecycle of a testem component.
  *
  * @param {String} path - The path to resolve.
  * @return {String} - The resolved path.
  */
+/* eslint-enable jsdoc/require-returns-check */
 fluid.testem.resolveFluidModulePathSafely = function (path) {
     try {
         var resolvedPath = fluid.module.resolvePath(path);