From 88f237ccd7e39a40ac4fea5fc362fb9d4436ada3 Mon Sep 17 00:00:00 2001
From: Matteo Collina <hello@matteocollina.com>
Date: Sat, 23 May 2026 13:59:13 +0200
Subject: [PATCH] test_runner: add --test-coverage flag

Signed-off-by: Matteo Collina <matteo.collina@gmail.com>
---
 doc/api/cli.md                                |  9 +++---
 doc/api/test.md                               | 10 +++---
 doc/node-config-schema.json                   |  8 +++++
 doc/node.1                                    | 10 +++---
 lib/internal/process/pre_execution.js         |  5 ++-
 lib/internal/test_runner/runner.js            |  3 +-
 lib/internal/test_runner/utils.js             |  2 +-
 src/node_options.cc                           |  4 ++-
 .../rc/namespace-with-disallowed-envvar.json  |  2 +-
 .../options-propagation/node.config.json      |  2 +-
 test/parallel/test-runner-cli.js              |  2 +-
 ...test-runner-coverage-default-exclusion.mjs |  6 ++--
 .../test-runner-coverage-source-map.js        |  2 +-
 .../test-runner-coverage-thresholds.js        | 14 ++++----
 test/parallel/test-runner-coverage.js         | 32 +++++++++----------
 test/parallel/test-runner-flag-propagation.js |  6 ++--
 16 files changed, 65 insertions(+), 52 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index bc1f69483f3f7f..f994d8eead79bd 100644
--- 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
index 2d38f136f28332..b5960862e22bf2 100644
--- 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
index a78031061dca87..275db7ff3bae5f 100644
--- 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
index 2f847f91bd08ea..1250c3ee67298f 100644
--- 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
index 394c18887f72ce..e753dff3aae6d5 100644
--- 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
index d6cb6438d2b52a..c6ceaa2a97291e 100644
--- 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
index 5a29673279311b..0b56bd05dd2d9e 100644
--- 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
index bcb3819a643ede..32079dcdc0ac97 100644
--- 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
index f545f0ff62781f..445b059639e543 100644
--- 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
index 7bb3d5c80fe0e5..6ed9dc5600ce38 100644
--- 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
index f563d67d1a9a41..f7e228004bbd81 100644
--- 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
index 44e5f7600d3270..e44a85e8d33b2c 100644
--- 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
index e3b0676a557a9f..1e5c67eeac337c 100644
--- 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
index e45e1191299ca7..68cb330d4da126 100644
--- 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
index 5a8f3d743538cb..8b773dc5c8265f 100644
--- a/test/parallel/test-runner-coverage.js
+++ b/test/parallel/test-runner-coverage.js
@@ -85,7 +85,7 @@ test('test coverage report', async (t) => {
 
     const fixture = fixtures.path('test-runner', 'coverage.js');
     const args = [
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       fixture,
     ];
@@ -102,7 +102,7 @@ test('test tap coverage reporter', skipIfNoInspector, async (t) => {
   await t.test('coverage is reported and dumped to NODE_V8_COVERAGE if present', (t) => {
     const fixture = fixtures.path('test-runner', 'coverage.js');
     const args = [
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       '--test-reporter',
       'tap',
@@ -120,7 +120,7 @@ test('test tap coverage reporter', skipIfNoInspector, async (t) => {
   await t.test('coverage is reported without NODE_V8_COVERAGE present', (t) => {
     const fixture = fixtures.path('test-runner', 'coverage.js');
     const args = [
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       '--test-reporter',
       'tap',
@@ -140,7 +140,7 @@ test('test spec coverage reporter', skipIfNoInspector, async (t) => {
   await t.test('coverage is reported and dumped to NODE_V8_COVERAGE if present', (t) => {
     const fixture = fixtures.path('test-runner', 'coverage.js');
     const args = [
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       '--test-reporter',
       'spec',
@@ -158,7 +158,7 @@ test('test spec coverage reporter', skipIfNoInspector, async (t) => {
   await t.test('coverage is reported without NODE_V8_COVERAGE present', (t) => {
     const fixture = fixtures.path('test-runner', 'coverage.js');
     const args = [
-      '--experimental-test-coverage',
+      '--test-coverage',
       '--test-coverage-exclude=!test/**',
       '--test-reporter',
       'spec',
@@ -177,7 +177,7 @@ test('single process coverage is the same with --test', skipIfNoInspector, () =>
   const fixture = fixtures.path('test-runner', 'coverage.js');
   const args = [
     '--test',
-    '--experimental-test-coverage',
+    '--test-coverage',
     '--test-coverage-exclude=!test/**',
     '--test-reporter',
     'tap',
@@ -215,7 +215,7 @@ test('coverage is combined for multiple processes', skipIfNoInspector, () => {
   const fixture = fixtures.path('v8-coverage', 'combined_coverage');
   const args = [
     '--test',
-    '--experimental-test-coverage',
+    '--test-coverage',
     '--test-coverage-exclude=!test/**',
     '--test-reporter',
     'tap',
@@ -257,7 +257,7 @@ test.skip('coverage works with isolation=none', skipIfNoInspector, common.mustCa
   const fixture = fixtures.path('v8-coverage', 'combined_coverage');
   const args = [
     '--test',
-    '--experimental-test-coverage',
+    '--test-coverage',
     '--test-reporter',
     'tap',
     '--test-isolation=none',
@@ -277,7 +277,7 @@ test('coverage reports on lines, functions, and branches', skipIfNoInspector, as
   const child = spawnSync(process.execPath,
                           [
                             '--test',
-                            '--experimental-test-coverage',
+                            '--test-coverage',
                             '--test-coverage-exclude=!test/**',
                             '--test-reporter',
                             fixtures.fileURL('test-runner/custom_reporters/coverage.mjs'),
@@ -357,7 +357,7 @@ test('coverage with ESM hook - source irrelevant', skipIfNoInspector, () => {
     '--import',
     './register-hooks.js',
     '--test',
-    '--experimental-test-coverage',
+    '--test-coverage',
     '--test-coverage-exclude=!test/**',
     '--test-reporter',
     'tap',
@@ -394,7 +394,7 @@ test('coverage with ESM hook - source transpiled', skipIfNoInspector, () => {
   const args = [
     '--import', './register-hooks.js',
     '--test',
-    '--experimental-test-coverage',
+    '--test-coverage',
     '--test-coverage-exclude=!test/**',
     '--test-reporter', 'tap', 'sum.test.ts',
   ];
@@ -408,7 +408,7 @@ test('coverage with ESM hook - source transpiled', skipIfNoInspector, () => {
 test('coverage with excluded files', skipIfNoInspector, () => {
   const fixture = fixtures.path('test-runner', 'coverage.js');
   const args = [
-    '--experimental-test-coverage', '--test-reporter', 'tap',
+    '--test-coverage', '--test-reporter', 'tap',
     '--test-coverage-exclude=test/*/test-runner/invalid-tap.js',
     '--test-coverage-exclude=!test/**',
     fixture];
@@ -443,7 +443,7 @@ test('coverage with excluded files', skipIfNoInspector, () => {
 test('coverage with included files', skipIfNoInspector, () => {
   const fixture = fixtures.path('test-runner', 'coverage.js');
   const args = [
-    '--experimental-test-coverage', '--test-reporter', 'tap',
+    '--test-coverage', '--test-reporter', 'tap',
     '--test-coverage-include=test/fixtures/test-runner/coverage.js',
     '--test-coverage-include=test/fixtures/v8-coverage/throw.js',
     '--test-coverage-exclude=!test/**',
@@ -480,7 +480,7 @@ test('coverage with included files', skipIfNoInspector, () => {
 test('coverage with included and excluded files', skipIfNoInspector, () => {
   const fixture = fixtures.path('test-runner', 'coverage.js');
   const args = [
-    '--experimental-test-coverage', '--test-reporter', 'tap',
+    '--test-coverage', '--test-reporter', 'tap',
     '--test-coverage-include=test/fixtures/test-runner/*.js',
     '--test-coverage-exclude=test/fixtures/test-runner/*-tap.js',
     fixture,
@@ -535,7 +535,7 @@ test('correctly prints the coverage report of files contained in parent director
   const fixture = fixtures.path('test-runner', 'coverage.js');
   const args = [
     '--test',
-    '--experimental-test-coverage',
+    '--test-coverage',
     '--test-coverage-exclude=!test/**',
     '--test-reporter',
     'tap',
@@ -555,7 +555,7 @@ test('correctly prints the coverage report of files contained in parent director
 test('coverage with directory and file named "file"', skipIfNoInspector, () => {
   const fixture = fixtures.path('test-runner', 'coverage-file-name', 'test.js');
   const args = [
-    '--experimental-test-coverage',
+    '--test-coverage',
     '--test-reporter',
     'tap',
     fixture,
diff --git a/test/parallel/test-runner-flag-propagation.js b/test/parallel/test-runner-flag-propagation.js
index 055d8b6d67c9b5..e122ae7dee8e9d 100644
--- a/test/parallel/test-runner-flag-propagation.js
+++ b/test/parallel/test-runner-flag-propagation.js
@@ -26,7 +26,9 @@ describe('test runner flag propagation', () => {
       ['--test-coverage-branches', '100', '100'],
       ['--test-coverage-functions', '100', '100'],
       ['--test-coverage-lines', '100', '100'],
-      ['--experimental-test-coverage', '', false],
+      ['--test-coverage', '', false],
+      ['--experimental-test-coverage', '', false, '--test-coverage',
+       'should not propagate --experimental-test-coverage to child tests'],
       ['--test-coverage-exclude', 'test/**', 'test/**'],
       ['--test-coverage-include', 'src/**', 'src/**'],
       ['--test-update-snapshots', '', true],
@@ -78,7 +80,7 @@ describe('test runner flag propagation', () => {
       ['--test-coverage-branches', 100, 100, 'test'],
       ['--test-coverage-functions', 100, 100, 'test'],
       ['--test-coverage-lines', 100, 100, 'test'],
-      ['--experimental-test-coverage', true, false, 'test'],
+      ['--test-coverage', true, false, 'test'],
       ['--test-coverage-exclude', 'test/**', 'test/**', 'test'],
       ['--test-coverage-include', 'src/**', 'src/**', 'test'],
       ['--test-update-snapshots', true, true, 'test'],