test_runner: support glob matching coverage files

PR-URL: #53553
Reviewed-By: Moshe Atlow <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Benjamin Gruenbaum <[email protected]>

Author: avivkeller

doc/api/cli.md

@@ -490,6 +490,40 @@ For example, to run a module with "development" resolutions:
 node -C development app.js
 ```
 
+### `--test-coverage-exclude`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Excludes specific files from code coverage using a glob pattern, which can match
+both absolute and relative file paths.
+
+This option may be specified multiple times to exclude multiple glob patterns.
+
+If both `--test-coverage-exclude` and `--test-coverage-include` are provided,
+files must meet **both** criteria to be included in the coverage report.
+
+### `--test-coverage-include`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Includes specific files in code coverage using a glob pattern, which can match
+both absolute and relative file paths.
+
+This option may be specified multiple times to include multiple glob patterns.
+
+If both `--test-coverage-exclude` and `--test-coverage-include` are provided,
+files must meet **both** criteria to be included in the coverage report.
+
 ### `--cpu-prof`
 
 <!-- YAML
@@ -2961,6 +2995,8 @@ one is included in the list below.
 * `--secure-heap-min`
 * `--secure-heap`
 * `--snapshot-blob`
+* `--test-coverage-exclude`
+* `--test-coverage-include`
 * `--test-only`
 * `--test-reporter-destination`
 * `--test-reporter`

doc/api/test.md

@@ -511,11 +511,6 @@ node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-de
 * No test results are reported by this reporter.
 * This reporter should ideally be used alongside another reporter.
 
-### Limitations
-
-The test runner's code coverage functionality does not support excluding
-specific files or directories from the coverage report.
-
 ## Mocking
 
 The `node:test` module supports mocking during testing via a top-level `mock`

doc/node.1

@@ -444,6 +444,12 @@ Starts the Node.js command line test runner.
 The maximum number of test files that the test runner CLI will execute
 concurrently.
 .
+.It Fl -test-coverage-exclude
+A glob pattern that excludes matching files from the coverage report
+.
+.It Fl -test-coverage-include
+A glob pattern that only includes matching files in the coverage report
+.
 .It Fl -test-force-exit
 Configures the test runner to exit the process once all known tests have
 finished executing even if the event loop would otherwise remain active.

lib/internal/test_runner/coverage.js

@@ -25,15 +25,18 @@ const {
   readFileSync,
 } = require('fs');
 const { setupCoverageHooks } = require('internal/util');
+const { getOptionValue } = require('internal/options');
 const { tmpdir } = require('os');
-const { join, resolve } = require('path');
+const { join, resolve, relative, matchesGlob } = require('path');
 const { fileURLToPath } = require('internal/url');
 const { kMappings, SourceMap } = require('internal/source_map/source_map');
 const kCoverageFileRegex = /^coverage-(\d+)-(\d{13})-(\d+)\.json$/;
 const kIgnoreRegex = /\/\* node:coverage ignore next (?<count>\d+ )?\*\//;
 const kLineEndingRegex = /\r?\n$/u;
 const kLineSplitRegex = /(?<=\r?\n)/u;
 const kStatusRegex = /\/\* node:coverage (?<status>enable|disable) \*\//;
+const excludeFileGlobs = getOptionValue('--test-coverage-exclude');
+const includeFileGlobs = getOptionValue('--test-coverage-include');
 
 class CoverageLine {
   constructor(line, startOffset, src, length = src?.length) {
@@ -308,7 +311,7 @@ class TestCoverage {
 
         const coverageFile = join(this.coverageDirectory, entry.name);
         const coverage = JSONParse(readFileSync(coverageFile, 'utf8'));
-        mergeCoverage(result, this.mapCoverageWithSourceMap(coverage));
+        mergeCoverage(result, this.mapCoverageWithSourceMap(coverage), this.workingDirectory);
       }
 
       return ArrayFrom(result.values());
@@ -331,7 +334,7 @@ class TestCoverage {
       const script = result[i];
       const { url, functions } = script;
 
-      if (shouldSkipFileCoverage(url) || sourceMapCache[url] == null) {
+      if (shouldSkipFileCoverage(url, this.workingDirectory) || sourceMapCache[url] == null) {
         newResult.set(url, script);
         continue;
       }
@@ -485,22 +488,42 @@ function mapRangeToLines(range, lines) {
   return { __proto__: null, lines: mappedLines, ignoredLines };
 }
 
-function shouldSkipFileCoverage(url) {
-  // The first part of this check filters out the node_modules/ directory
-  // from the results. This filter is applied first because most real world
-  // applications will be dominated by third party dependencies. The second
-  // part of the check filters out core modules, which start with 'node:' in
+function shouldSkipFileCoverage(url, workingDirectory) {
+  // This check filters out core modules, which start with 'node:' in
   // coverage reports, as well as any invalid coverages which have been
   // observed on Windows.
-  return StringPrototypeIncludes(url, '/node_modules/') || !StringPrototypeStartsWith(url, 'file:');
+  if (!StringPrototypeStartsWith(url, 'file:')) return true;
+
+  const absolutePath = fileURLToPath(url);
+  const relativePath = relative(workingDirectory, absolutePath);
+
+  // This check filters out files that match the exclude globs.
+  if (excludeFileGlobs?.length > 0) {
+    for (let i = 0; i < excludeFileGlobs.length; ++i) {
+      if (matchesGlob(relativePath, excludeFileGlobs[i]) ||
+          matchesGlob(absolutePath, excludeFileGlobs[i])) return true;
+    }
+  }
+
+  // This check filters out files that do not match the include globs.
+  if (includeFileGlobs?.length > 0) {
+    for (let i = 0; i < includeFileGlobs.length; ++i) {
+      if (matchesGlob(relativePath, includeFileGlobs[i]) ||
+          matchesGlob(absolutePath, includeFileGlobs[i])) return false;
+    }
+    return true;
+  }
+
+  // This check filters out the node_modules/ directory, unless it is explicitly included.
+  return StringPrototypeIncludes(url, '/node_modules/');
 }
 
-function mergeCoverage(merged, coverage) {
+function mergeCoverage(merged, coverage, workingDirectory) {
   for (let i = 0; i < coverage.length; ++i) {
     const newScript = coverage[i];
     const { url } = newScript;
 
-    if (shouldSkipFileCoverage(url)) {
+    if (shouldSkipFileCoverage(url, workingDirectory)) {
       continue;
     }
 

src/node_options.cc

@@ -686,6 +686,14 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddOption("--test-skip-pattern",
             "run tests whose name do not match this regular expression",
             &EnvironmentOptions::test_skip_pattern);
+  AddOption("--test-coverage-include",
+            "include files in coverage report that match this glob pattern",
+            &EnvironmentOptions::coverage_include_pattern,
+            kAllowedInEnvvar);
+  AddOption("--test-coverage-exclude",
+            "exclude files from coverage report that match this glob pattern",
+            &EnvironmentOptions::coverage_exclude_pattern,
+            kAllowedInEnvvar);
   AddOption("--test-udp-no-try-send", "",  // For testing only.
             &EnvironmentOptions::test_udp_no_try_send);
   AddOption("--throw-deprecation",

src/node_options.h

@@ -188,6 +188,8 @@ class EnvironmentOptions : public Options {
   bool test_udp_no_try_send = false;
   std::string test_shard;
   std::vector<std::string> test_skip_pattern;
+  std::vector<std::string> coverage_include_pattern;
+  std::vector<std::string> coverage_exclude_pattern;
   bool throw_deprecation = false;
   bool trace_atomics_wait = false;
   bool trace_deprecation = false;

test/parallel/test-runner-coverage.js

@@ -335,3 +335,96 @@ test('coverage with ESM hook - source transpiled', skipIfNoInspector, () => {
   assert(result.stdout.toString().includes(report));
   assert.strictEqual(result.status, 0);
 });
+
+test('coverage with excluded files', skipIfNoInspector, () => {
+  const fixture = fixtures.path('test-runner', 'coverage.js');
+  const args = [
+    '--experimental-test-coverage', '--test-reporter', 'tap',
+    '--test-coverage-exclude=test/*/test-runner/invalid-tap.js',
+    fixture];
+  const result = spawnSync(process.execPath, args);
+  const report = [
+    '# start of coverage report',
+    '# ' + '-'.repeat(112),
+    '# file                                  | line % | branch % | funcs % | uncovered lines',
+    '# ' + '-'.repeat(112),
+    '# test/fixtures/test-runner/coverage.js |  78.65 |    38.46 |   60.00 | 12-13 16-22 27 39 43-44 61-62 66-67 71-72',
+    '# test/fixtures/v8-coverage/throw.js    |  71.43 |    50.00 |  100.00 | 5-6',
+    '# ' + '-'.repeat(112),
+    '# all files                             |  78.13 |    40.00 |   60.00 |',
+    '# ' + '-'.repeat(112),
+    '# end of coverage report',
+  ].join('\n');
+
+
+  if (common.isWindows) {
+    return report.replaceAll('/', '\\');
+  }
+
+  assert(result.stdout.toString().includes(report));
+  assert.strictEqual(result.status, 0);
+  assert(!findCoverageFileForPid(result.pid));
+});
+
+test('coverage with included files', skipIfNoInspector, () => {
+  const fixture = fixtures.path('test-runner', 'coverage.js');
+  const args = [
+    '--experimental-test-coverage', '--test-reporter', 'tap',
+    '--test-coverage-include=test/fixtures/test-runner/coverage.js',
+    '--test-coverage-include=test/fixtures/v8-coverage/throw.js',
+    fixture,
+  ];
+  const result = spawnSync(process.execPath, args);
+  const report = [
+    '# start of coverage report',
+    '# ' + '-'.repeat(112),
+    '# file                                  | line % | branch % | funcs % | uncovered lines',
+    '# ' + '-'.repeat(112),
+    '# test/fixtures/test-runner/coverage.js |  78.65 |    38.46 |   60.00 | 12-13 16-22 27 39 43-44 61-62 66-67 71-72',
+    '# test/fixtures/v8-coverage/throw.js    |  71.43 |    50.00 |  100.00 | 5-6',
+    '# ' + '-'.repeat(112),
+    '# all files                             |  78.13 |    40.00 |   60.00 |',
+    '# ' + '-'.repeat(112),
+    '# end of coverage report',
+  ].join('\n');
+
+
+  if (common.isWindows) {
+    return report.replaceAll('/', '\\');
+  }
+
+  assert(result.stdout.toString().includes(report));
+  assert.strictEqual(result.status, 0);
+  assert(!findCoverageFileForPid(result.pid));
+});
+
+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-include=test/fixtures/test-runner/*.js',
+    '--test-coverage-exclude=test/fixtures/test-runner/*-tap.js',
+    fixture,
+  ];
+  const result = spawnSync(process.execPath, args);
+  const report = [
+    '# start of coverage report',
+    '# ' + '-'.repeat(112),
+    '# file                                  | line % | branch % | funcs % | uncovered lines',
+    '# ' + '-'.repeat(112),
+    '# test/fixtures/test-runner/coverage.js |  78.65 |    38.46 |   60.00 | 12-13 16-22 27 39 43-44 61-62 66-67 71-72',
+    '# ' + '-'.repeat(112),
+    '# all files                             |  78.65 |    38.46 |   60.00 |',
+    '# ' + '-'.repeat(112),
+    '# end of coverage report',
+  ].join('\n');
+
+
+  if (common.isWindows) {
+    return report.replaceAll('/', '\\');
+  }
+
+  assert(result.stdout.toString().includes(report));
+  assert.strictEqual(result.status, 0);
+  assert(!findCoverageFileForPid(result.pid));
+});