test_runner: add --test-coverage flag

mcollina · mcollina · commit 88f237ccd7e3 · 2026-05-23T14:05:45.000+02:00
Signed-off-by: Matteo Collina &lt;matteo.collina@gmail.com&gt;
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -1386,7 +1386,7 @@ added:
 
 Enable the experimental [`node:stream/iter`][] module.
 
-### `--experimental-test-coverage`
+### `--test-coverage`
 
 <!-- YAML
 added:
@@ -1400,11 +1400,12 @@ changes:
     description: This option can be used with `--test`.
 -->
 
-When used in conjunction with the `node:test` module, a code coverage report is
-generated as part of the test runner output. If no tests are run, a coverage
-report is not generated. See the documentation on
+Enable code coverage collection in the test runner. If no tests are run, a
+coverage report is not generated. See the documentation on
 [collecting code coverage from tests][] for more details.
 
+The legacy `--experimental-test-coverage` flag is supported as an alias.
+
 ### `--experimental-test-module-mocks`
 
 <!-- YAML
diff --git a/doc/api/test.md b/doc/api/test.md
@@ -827,7 +827,7 @@ inherit Node.js options from the parent process, including those specified in
 test runner functionality:
 
 * `--test` - Prevented to avoid recursive test execution
-* `--experimental-test-coverage` - Managed by the test runner
+* `--test-coverage` - Managed by the test runner
 * `--experimental-test-tag-filter` - Filter values are validated by the parent
   process and re-emitted to child processes
 * `--watch` - Watch mode is handled at the parent level
@@ -847,7 +847,7 @@ and configuration files are inherited by the child processes.
 
 > Stability: 1 - Experimental
 
-When Node.js is started with the [`--experimental-test-coverage`][]
+When Node.js is started with the [`--test-coverage`][]
 command-line flag, code coverage is collected and statistics are reported once
 all tests have completed. If the [`NODE_V8_COVERAGE`][] environment variable is
 used to specify a code coverage directory, the generated V8 coverage files are
@@ -894,7 +894,7 @@ There is also an lcov reporter that will generate an lcov file which can be
 used as an in depth coverage report.
 
 ```bash
-node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info
+node --test --test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info
 ```
 
 * No test results are reported by this reporter.
@@ -1408,7 +1408,7 @@ The following built-reporters are supported:
 
 * `lcov`
   The `lcov` reporter outputs test coverage when used with the
-  [`--experimental-test-coverage`][] flag.
+  [`--test-coverage`][] flag.
 
 The exact output of these reporters is subject to change between versions of
 Node.js, and should not be relied on programmatically. If programmatic access
@@ -4679,7 +4679,7 @@ test.describe('my suite', (suite) => {
 
 [TAP]: https://testanything.org/
 [Test tags]: #test-tags
-[`--experimental-test-coverage`]: cli.md#--experimental-test-coverage
+[`--test-coverage`]: cli.md#--test-coverage
 [`--experimental-test-module-mocks`]: cli.md#--experimental-test-module-mocks
 [`--experimental-test-tag-filter`]: cli.md#--experimental-test-tag-filterexpr
 [`--import`]: cli.md#--importmodule
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
@@ -510,6 +510,10 @@
               "type": "boolean",
               "description": "Type-stripping for TypeScript files."
             },
+            "test-coverage": {
+              "type": "boolean",
+              "description": "enable code coverage in the test runner"
+            },
             "test-coverage-branches": {
               "type": "number",
               "description": "the branch coverage minimum threshold"
@@ -887,6 +891,10 @@
           "additionalProperties": false,
           "required": [],
           "properties": {
+            "test-coverage": {
+              "type": "boolean",
+              "description": "enable code coverage in the test runner"
+            },
             "experimental-test-coverage": {
               "type": "boolean",
               "description": "enable code coverage in the test runner"
diff --git a/doc/node.1 b/doc/node.1
@@ -769,11 +769,11 @@ Use this flag to enable ShadowRealm support.
 .It Fl -experimental-storage-inspection
 Enable experimental support for storage inspection
 .
-.It Fl -experimental-test-coverage
-When used in conjunction with the \fBnode:test\fR module, a code coverage report is
-generated as part of the test runner output. If no tests are run, a coverage
-report is not generated. See the documentation on
-collecting code coverage from tests for more details.
+.It Fl -test-coverage
+Enable code coverage collection in the test runner. If no tests are run, a
+coverage report is not generated. See the documentation on collecting code
+coverage from tests for more details.
+The legacy \fB--experimental-test-coverage\fR flag is supported as an alias.
 .
 .It Fl -experimental-test-module-mocks
 Enable module mocking in the test runner.
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
@@ -466,10 +466,9 @@ function setupCodeCoverage() {
   // Resolve the coverage directory to an absolute path, and
   // overwrite process.env so that the original path gets passed
   // to child processes even when they switch cwd. Don't do anything if the
-  // --experimental-test-coverage flag is present, as the test runner will
-  // handle coverage.
+  // --test-coverage flag is present, as the test runner will handle coverage.
   if (process.env.NODE_V8_COVERAGE &&
-      !getOptionValue('--experimental-test-coverage')) {
+      !getOptionValue('--test-coverage')) {
     process.env.NODE_V8_COVERAGE =
       setupCoverageHooks(process.env.NODE_V8_COVERAGE);
   }
diff --git a/lib/internal/test_runner/runner.js b/lib/internal/test_runner/runner.js
@@ -111,6 +111,7 @@ let debug = require('internal/util/debuglog').debuglog('test_runner', (fn) => {
 const kIsolatedProcessName = Symbol('kIsolatedProcessName');
 const kFilterArgs = [
   '--test',
+  '--test-coverage',
   '--experimental-test-coverage',
   '--test-randomize',
   '--watch',
@@ -201,7 +202,7 @@ function getRunArgs(path, { forceExit,
   const nodeOptionsSet = new SafeSet(processNodeOptions);
   const unknownProcessExecArgv = ArrayPrototypeFilter(
     process.execArgv,
-    (arg) => !nodeOptionsSet.has(arg),
+    (arg, i, arr) => !nodeOptionsSet.has(arg) && filterExecArgv(arg, i, arr),
   );
   ArrayPrototypePushApply(runArgs, unknownProcessExecArgv);
 
diff --git a/lib/internal/test_runner/utils.js b/lib/internal/test_runner/utils.js
@@ -270,7 +270,7 @@ function parseCommandLine() {
   }
 
   const isTestRunner = getOptionValue('--test');
-  const coverage = getOptionValue('--experimental-test-coverage');
+  const coverage = getOptionValue('--test-coverage');
   const forceExit = getOptionValue('--test-force-exit');
   const sourceMaps = getOptionValue('--enable-source-maps');
   const updateSnapshots = getOptionValue('--test-update-snapshots');
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -941,12 +941,14 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             kDisallowedInEnvvar,
             false,
             OptionNamespaces::kTestRunnerNamespace);
-  AddOption("--experimental-test-coverage",
+  AddOption("--test-coverage",
             "enable code coverage in the test runner",
             &EnvironmentOptions::test_runner_coverage,
             kDisallowedInEnvvar,
             false,
             OptionNamespaces::kTestRunnerNamespace);
+  // TODO(cjihrig): Remove this alias in a semver major.
+  AddAlias("--experimental-test-coverage", "--test-coverage");
   AddOption("--test-coverage-branches",
             "the branch coverage minimum threshold",
             &EnvironmentOptions::test_coverage_branches,
diff --git a/test/fixtures/rc/namespace-with-disallowed-envvar.json b/test/fixtures/rc/namespace-with-disallowed-envvar.json
@@ -1,6 +1,6 @@
 {
     "test": {
        "test-concurrency": 1,
-       "experimental-test-coverage": true
+       "test-coverage": true
     }
 }
diff --git a/test/fixtures/test-runner/options-propagation/node.config.json b/test/fixtures/test-runner/options-propagation/node.config.json
@@ -1,5 +1,5 @@
 {
     "test": {
-        "experimental-test-coverage": true
+        "test-coverage": true
     }
 }
diff --git a/test/parallel/test-runner-cli.js b/test/parallel/test-runner-cli.js
@@ -467,7 +467,7 @@ for (const isolation of ['none', 'process']) {
 {
   if (process.features.inspector) {
     // https://github.com/nodejs/node/issues/58828
-    // Should not print report twice when --experimental-test-coverage is set via config file
+    // Should not print report twice when --test-coverage is set via config file
     const fixturePath = join(testFixtures, 'options-propagation');
     const args = [
       '--test-reporter=tap',
diff --git a/test/parallel/test-runner-coverage-default-exclusion.mjs b/test/parallel/test-runner-coverage-default-exclusion.mjs
@@ -42,7 +42,7 @@ describe('test runner coverage default exclusion', skipIfNoInspector, () => {
 
     const args = [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       '--test-reporter=tap',
       '--no-experimental-strip-types',
@@ -73,7 +73,7 @@ describe('test runner coverage default exclusion', skipIfNoInspector, () => {
     const args = [
       '--no-experimental-strip-types',
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-reporter=tap',
     ];
     const result = spawnSync(process.execPath, args, {
@@ -101,7 +101,7 @@ describe('test runner coverage default exclusion', skipIfNoInspector, () => {
 
     const args = [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--disable-warning=ExperimentalWarning',
       '--test-reporter=tap',
     ];
diff --git a/test/parallel/test-runner-coverage-source-map.js b/test/parallel/test-runner-coverage-source-map.js
@@ -21,7 +21,7 @@ function generateReport(report) {
 const flags = [
   '--enable-source-maps',
   '--test',
-  '--experimental-test-coverage',
+  '--test-coverage',
   '--test-coverage-exclude=!test/**',
   '--test-reporter',
   'tap',
diff --git a/test/parallel/test-runner-coverage-thresholds.js b/test/parallel/test-runner-coverage-thresholds.js
@@ -60,7 +60,7 @@ for (const coverage of coverages) {
   test(`test passing ${coverage.flag}`, () => {
     const result = spawnSync(process.execPath, [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       `${coverage.flag}=25`,
       '--test-reporter', 'tap',
@@ -77,7 +77,7 @@ for (const coverage of coverages) {
   test(`test passing ${coverage.flag} with custom reporter`, () => {
     const result = spawnSync(process.execPath, [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       `${coverage.flag}=25`,
       '--test-reporter', reporter,
@@ -93,7 +93,7 @@ for (const coverage of coverages) {
   test(`test failing ${coverage.flag} with red color`, () => {
     const result = spawnSync(process.execPath, [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       `${coverage.flag}=99`,
       '--test-reporter', 'spec',
@@ -113,7 +113,7 @@ for (const coverage of coverages) {
   test(`test failing ${coverage.flag}`, () => {
     const result = spawnSync(process.execPath, [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       `${coverage.flag}=99`,
       '--test-reporter', 'tap',
@@ -130,7 +130,7 @@ for (const coverage of coverages) {
   test(`test failing ${coverage.flag} with custom reporter`, () => {
     const result = spawnSync(process.execPath, [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       `${coverage.flag}=99`,
       '--test-reporter', reporter,
@@ -146,7 +146,7 @@ for (const coverage of coverages) {
   test(`test out-of-range ${coverage.flag} (too high)`, () => {
     const result = spawnSync(process.execPath, [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       `${coverage.flag}=101`,
       fixture,
@@ -160,7 +160,7 @@ for (const coverage of coverages) {
   test(`test out-of-range ${coverage.flag} (too low)`, () => {
     const result = spawnSync(process.execPath, [
       '--test',
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       `${coverage.flag}=-1`,
       fixture,
diff --git a/test/parallel/test-runner-coverage.js b/test/parallel/test-runner-coverage.js
diff --git a/test/parallel/test-runner-flag-propagation.js b/test/parallel/test-runner-flag-propagation.js

Original file line number	Diff line number	Diff line change
`@@ -270,7 +270,7 @@ function parseCommandLine() {`
`270`	`270`	`}`
`271`	`271`
`272`	`272`	`const isTestRunner = getOptionValue('--test');`
`273`		`- const coverage = getOptionValue('--experimental-test-coverage');`
	`273`	`+ const coverage = getOptionValue('--test-coverage');`
`274`	`274`	`const forceExit = getOptionValue('--test-force-exit');`
`275`	`275`	`const sourceMaps = getOptionValue('--enable-source-maps');`
`276`	`276`	`const updateSnapshots = getOptionValue('--test-update-snapshots');`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"test": {`
`3`	`3`	`"test-concurrency": 1,`
`4`		`- "experimental-test-coverage": true`
	`4`	`+ "test-coverage": true`
`5`	`5`	`}`
`6`	`6`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`{`
`2`	`2`	`"test": {`
`3`		`- "experimental-test-coverage": true`
	`3`	`+ "test-coverage": true`
`4`	`4`	`}`
`5`	`5`	`}`