doc,lib,src,test: rename --test-coverage

Add experimental to the name as requested during review.

PR-URL: #46017
Backport-PR-URL: #46839
Reviewed-By: Moshe Atlow <[email protected]>
Reviewed-By: Geoffrey Booth <[email protected]>

Author: cjihrig

doc/api/cli.md

@@ -440,6 +440,17 @@ the ability to import a directory that has an index file.
 
 See [customizing ESM specifier resolution][] for example usage.
 
+### `--experimental-test-coverage`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+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
+[collecting code coverage from tests][] for more details.
+
 ### `--experimental-vm-modules`
 
 <!-- YAML
@@ -1209,17 +1220,6 @@ Starts the Node.js command line test runner. This flag cannot be combined with
 See the documentation on [running tests from the command line][]
 for more details.
 
-### `--test-coverage`
-
-<!-- YAML
-added: REPLACEME
--->
-
-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
-[collecting code coverage from tests][] for more details.
-
 ### `--test-name-pattern`
 
 <!-- YAML

doc/api/test.md

@@ -370,13 +370,14 @@ internally.
 
 ## Collecting code 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 written to that
-directory. Node.js core modules and files within `node_modules/` directories
-are not included in the coverage report. If coverage is enabled, the coverage
-report is sent to any [test reporters][] via the `'test:coverage'` event.
+When Node.js is started with the [`--experimental-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
+written to that directory. Node.js core modules and files within
+`node_modules/` directories are not included in the coverage report. If
+coverage is enabled, the coverage report is sent to any [test reporters][] via
+the `'test:coverage'` event.
 
 Coverage can be disabled on a series of lines using the following
 comment syntax:
@@ -411,7 +412,8 @@ which will be addressed in a future Node.js release:
 
 * Although coverage data is collected for child processes, this information is
   not included in the coverage report. Because the command line test runner uses
-  child processes to execute test files, it cannot be used with `--test-coverage`.
+  child processes to execute test files, it cannot be used with
+  `--experimental-test-coverage`.
 * Source maps are not supported.
 * Excluding specific files or directories from the coverage report is not
   supported.
@@ -1634,7 +1636,7 @@ added: v18.7.0
   aborted.
 
 [TAP]: https://testanything.org/
-[`--test-coverage`]: cli.md#--test-coverage
+[`--experimental-test-coverage`]: cli.md#--experimental-test-coverage
 [`--test-name-pattern`]: cli.md#--test-name-pattern
 [`--test-only`]: cli.md#--test-only
 [`--test-reporter-destination`]: cli.md#--test-reporter-destination

doc/node.1

@@ -163,6 +163,9 @@ Use the specified file as a security policy.
 .It Fl -experimental-shadow-realm
 Use this flag to enable ShadowRealm support.
 .
+.It Fl -experimental-test-coverage
+Enable code coverage in the test runner.
+.
 .It Fl -no-experimental-fetch
 Disable experimental support for the Fetch API.
 .
@@ -391,9 +394,6 @@ Specify the minimum allocation from the OpenSSL secure heap. The default is 2. T
 .It Fl -test
 Starts the Node.js command line test runner.
 .
-.It Fl -test-coverage
-Enable code coverage in the test runner.
-.
 .It Fl -test-name-pattern
 A regular expression that configures the test runner to only execute tests
 whose name matches the provided pattern.

lib/internal/process/pre_execution.js

@@ -285,8 +285,10 @@ 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
-  // --test-coverage flag is present, as the test runner will handle coverage.
-  if (process.env.NODE_V8_COVERAGE && !getOptionValue('--test-coverage')) {
+  // --experimental-test-coverage flag is present, as the test runner will
+  // handle coverage.
+  if (process.env.NODE_V8_COVERAGE &&
+      !getOptionValue('--experimental-test-coverage')) {
     process.env.NODE_V8_COVERAGE =
       setupCoverageHooks(process.env.NODE_V8_COVERAGE);
   }

lib/internal/test_runner/harness.js

@@ -55,7 +55,7 @@ function createProcessEventHandler(eventName, rootTest) {
 }
 
 function configureCoverage(rootTest) {
-  if (!getOptionValue('--test-coverage')) {
+  if (!getOptionValue('--experimental-test-coverage')) {
     return null;
   }
 

lib/internal/test_runner/runner.js

@@ -48,7 +48,7 @@ const {
   triggerUncaughtException,
 } = internalBinding('errors');
 
-const kFilterArgs = ['--test', '--test-coverage', '--watch'];
+const kFilterArgs = ['--test', '--experimental-test-coverage', '--watch'];
 const kFilterArgValues = ['--test-reporter', '--test-reporter-destination'];
 
 // TODO(cjihrig): Replace this with recursive readdir once it lands.

src/node_options.cc

@@ -151,7 +151,8 @@ void EnvironmentOptions::CheckOptions(std::vector<std::string>* errors,
     if (test_runner_coverage) {
       // TODO(cjihrig): This restriction can be removed once multi-process
       // code coverage is supported.
-      errors->push_back("--test-coverage cannot be used with --test");
+      errors->push_back(
+          "--experimental-test-coverage cannot be used with --test");
     }
 
     if (syntax_check_only) {
@@ -561,7 +562,7 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddOption("--test",
             "launch test runner on startup",
             &EnvironmentOptions::test_runner);
-  AddOption("--test-coverage",
+  AddOption("--experimental-test-coverage",
             "enable code coverage in the test runner",
             &EnvironmentOptions::test_runner_coverage);
   AddOption("--test-name-pattern",

test/parallel/test-runner-coverage.js

@@ -37,15 +37,17 @@ function getCoverageFixtureReport() {
   return report;
 }
 
-test('--test-coverage and --test cannot be combined', () => {
+test('--experimental-test-coverage and --test cannot be combined', () => {
   // TODO(cjihrig): This test can be removed once multi-process code coverage
   // is supported.
-  const result = spawnSync(process.execPath, ['--test', '--test-coverage']);
+  const args = ['--test', '--experimental-test-coverage'];
+  const result = spawnSync(process.execPath, args);
 
   // 9 is the documented exit code for an invalid CLI argument.
   assert.strictEqual(result.status, 9);
   assert.match(
-    result.stderr.toString(), /--test-coverage cannot be used with --test/
+    result.stderr.toString(),
+    /--experimental-test-coverage cannot be used with --test/
   );
 });
 
@@ -55,7 +57,7 @@ test('handles the inspector not being available', (t) => {
   }
 
   const fixture = fixtures.path('test-runner', 'coverage.js');
-  const args = ['--test-coverage', fixture];
+  const args = ['--experimental-test-coverage', fixture];
   const result = spawnSync(process.execPath, args);
 
   assert(!result.stdout.toString().includes('# start of coverage report'));
@@ -70,7 +72,7 @@ test('coverage is reported and dumped to NODE_V8_COVERAGE if present', (t) => {
   }
 
   const fixture = fixtures.path('test-runner', 'coverage.js');
-  const args = ['--test-coverage', fixture];
+  const args = ['--experimental-test-coverage', fixture];
   const options = { env: { ...process.env, NODE_V8_COVERAGE: tmpdir.path } };
   const result = spawnSync(process.execPath, args, options);
   const report = getCoverageFixtureReport();
@@ -87,7 +89,7 @@ test('coverage is reported without NODE_V8_COVERAGE present', (t) => {
   }
 
   const fixture = fixtures.path('test-runner', 'coverage.js');
-  const args = ['--test-coverage', fixture];
+  const args = ['--experimental-test-coverage', fixture];
   const result = spawnSync(process.execPath, args);
   const report = getCoverageFixtureReport();