feat: add node test reporter

.github/workflows/ci.yml

@@ -128,6 +128,18 @@ jobs:
           path: d2l-test-report-mocha.json
           archive: false
           if-no-files-found: ignore
+      - name: Upload test report (node)
+        if: >
+          !cancelled() && (
+            steps.tests.conclusion == 'failure' ||
+            steps.tests.outcome == 'success'
+          )
+        id: upload-node
+        uses: Brightspace/third-party-actions@actions/upload-artifact
+        with:
+          path: d2l-test-report-node.json
+          archive: false
+          if-no-files-found: ignore
       - name: Upload test report (playwright)
         if: >
           !cancelled() && (
@@ -226,6 +238,7 @@ jobs:
           REPORT_ARTIFACT_URLS: >
             {
               "mocha": "${{steps.upload-mocha.outputs.artifact-url}}",
+              "node": "${{steps.upload-node.outputs.artifact-url}}",
               "playwright": "${{steps.upload-playwright.outputs.artifact-url}}",
               "@web/test-runner": "${{steps.upload-web-test-runner.outputs.artifact-url}}",
               "webdriverio": "${{steps.upload-webdriverio.outputs.artifact-url}}"

README.md

@@ -46,6 +46,7 @@ Each reporter wraps your test framework and emits a D2L test report JSON file
 when the test run completes. The following frameworks are supported.
 
 * [Mocha]
+* [Node.js Test Runner]
 * [Playwright]
 * [Web Test Runner]
 * [WebdriverIO]
@@ -131,6 +132,7 @@ refer to the [semantic-release GitHub Action] documentation.
 [#test-reporting]: https://d2l.slack.com/archives/C05MMC7H7EK
 [semantic-release GitHub Action]: https://github.com/BrightspaceUI/actions/tree/main/semantic-release
 [Mocha]: ./docs/reporters/mocha.md
+[Node.js Test Runner]: ./docs/reporters/node.md
 [Playwright]: ./docs/reporters/playwright.md
 [Web Test Runner]: ./docs/reporters/web-test-runner.md
 [WebdriverIO]: ./docs/reporters/webdriverio.md

docs/report-builder.md

@@ -3,8 +3,8 @@
 ## When to Use
 
 Use the `ReportBuilder` class when your test framework isn't supported by one of
-the existing reporters ([Mocha Reporter], [Playwright Reporter], [Web Test
-Runner Reporter], [WebdriverIO Reporter]).
+the existing reporters ([Mocha Reporter], [Node.js Test Runner Reporter],
+[Playwright Reporter], [Web Test Runner Reporter], [WebdriverIO Reporter]).
 
 ## Quick Start
 
@@ -239,6 +239,7 @@ report.finalize().save();
 
 <!-- links -->
 [Mocha Reporter]: ./reporters/mocha.md
+[Node.js Test Runner Reporter]: ./reporters/node.md
 [Playwright Reporter]: ./reporters/playwright.md
 [Web Test Runner Reporter]: ./reporters/web-test-runner.md
 [WebdriverIO Reporter]: ./reporters/webdriverio.md

docs/reporters/node.md

@@ -0,0 +1,104 @@
+# Node.js Test Runner Reporter
+
+Please consult the [official documentation for the Node.js test runner] to see
+how to use [custom reporters].
+
+> [!NOTE]
+> This is a simplified example. Update values and options to match your
+> specific project setup.
+
+## CLI Usage
+
+The reporter has a default export that works directly with the
+`--test-reporter` flag. Pair it with another reporter (such as `spec`) to keep
+human readable output on the console.
+
+```console
+node --test \
+  --test-reporter=spec --test-reporter-destination=stdout \
+  --test-reporter=d2l-test-reporting/reporters/node.js --test-reporter-destination=stdout
+```
+
+> [!NOTE]
+> Node.js requires a `--test-reporter-destination` for every `--test-reporter`
+> when more than one reporter is used. The reporter writes the report file
+> itself (see `reportPath` under [Inputs]), so its destination receives no
+> output and `stdout` acts as a harmless placeholder.
+
+Options are read from environment variables since the Node.js test runner does
+not forward options to custom reporters. See [Inputs] for the available
+variables.
+
+## Programmatic Usage
+
+For finer control, use the named `reporter` factory with the [`run()`] API and
+compose it onto the test stream.
+
+```js
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { reporter } from 'd2l-test-reporting/reporters/node.js';
+import { run } from 'node:test';
+
+const testDirectory = 'test';
+const files = readdirSync(testDirectory)
+  .filter(name => name.endsWith('.test.js'))
+  .map(name => join(testDirectory, name));
+
+const stream = run({ files }).compose(reporter());
+
+stream.on('data', () => {});
+stream.on('error', () => {});
+```
+
+## Inputs
+
+The `reporter` factory accepts the following options. When running through the
+CLI, the corresponding environment variable is used instead.
+
+* `reportPath` / `D2L_TEST_REPORTING_REPORT_PATH` (default:
+  `./d2l-test-report.json`): Path to output the report to, relative to current
+  working directory.
+* `reportConfigurationPath` / `D2L_TEST_REPORTING_REPORT_CONFIGURATION_PATH`
+  (default: `./d2l-test-reporting.config.json`): Path to the D2L test reporting
+  configuration file for mapping test type and tool to test code.
+* `verbose` / `D2L_TEST_REPORTING_VERBOSE` (default: `false`): Enable verbose
+  logging for debugging purposes.
+
+## Full Example
+
+The defaults for all optional inputs work well for most setups. The example
+below shows every available option explicitly set, and is intended as a
+reference if any values need to be customized.
+
+```js
+import { readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { reporter } from 'd2l-test-reporting/reporters/node.js';
+import { run } from 'node:test';
+
+const testDirectory = 'test';
+const files = readdirSync(testDirectory)
+  .filter(name => name.endsWith('.test.js'))
+  .map(name => join(testDirectory, name));
+const stream = run({ files }).compose(reporter({
+  reportPath: './d2l-test-report.json',
+  reportConfigurationPath: './d2l-test-reporting.config.json',
+  verbose: true
+}));
+
+stream.on('data', () => {});
+stream.on('error', () => {});
+```
+
+> [!NOTE]
+> The Node.js test runner does not expose the configured timeout for a test, so
+> each test detail omits the `timeout` value under `configuration`. It also has
+> no built-in retry mechanism, so each test detail always reports `retries` as
+> `0` and no test is ever counted as `flaky`.
+
+<!-- links -->
+[official documentation for the Node.js test runner]: https://nodejs.org/api/test.html
+[custom reporters]: https://nodejs.org/api/test.html#custom-reporters
+[Inputs]: #inputs
+[`run()`]: https://nodejs.org/api/test.html#runoptions

package.json

@@ -17,6 +17,7 @@
     "./helpers/report.js": "./src/helpers/report.cjs",
     "./helpers/report-configuration.js": "./src/helpers/report-configuration.cjs",
     "./reporters/mocha.js": "./src/reporters/mocha.cjs",
+    "./reporters/node.js": "./src/reporters/node.js",
     "./reporters/playwright.js": "./src/reporters/playwright.js",
     "./reporters/web-test-runner.js": "./src/reporters/web-test-runner.js",
     "./reporters/webdriverio.js": "./src/reporters/webdriverio.cjs"
@@ -37,6 +38,7 @@
     "test:all": "c8 run-s test:unit test:integration",
     "test:integration": "run-s test:integration:* test:integration:validate-reports",
     "test:integration:mocha": "mocha --config test/integration/data/configs/mocha.cjs || exit 0",
+    "test:integration:node": "node test/integration/data/configs/node.js || exit 0",
     "test:integration:playwright": "playwright test --config test/integration/data/configs/playwright.js || exit 0",
     "test:integration:web-test-runner": "wtr --config test/integration/data/configs/web-test-runner.js || exit 0",
     "test:integration:webdriverio": "wdio run test/integration/data/configs/webdriverio.cjs || exit 0",