test: add --test-files-glob flag

Overrides the default `kDefaultPattern` for test file globs to allow for
default file pattern matching, while still allowing other options or
single, targeted file names for testing.

This also might resolve issues with the defaults when using strip-types
since the defaults can, currently, only be overridden using the
positional `arguments` (see #56546).

Fixes: #51384
Ref: #56546

Author: p-mcgowan

doc/api/cli.md

@@ -2591,6 +2591,20 @@ added: v22.8.0
 Require a minimum percent of covered lines. If code coverage does not reach
 the threshold specified, the process will exit with code `1`.
 
+### `--test-files-glob=glob`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+Override the default test file glob patterns. This option is ignored if
+positional `arguments` are provided as well.
+
+See [running tests from the command line][] for more information on the
+default patterns.
+
 ### `--test-force-exit`
 
 <!-- YAML
@@ -3571,6 +3585,7 @@ one is included in the list below.
 * `--test-coverage-functions`
 * `--test-coverage-include`
 * `--test-coverage-lines`
+* `--test-files-glob`
 * `--test-global-setup`
 * `--test-isolation`
 * `--test-name-pattern`

doc/api/test.md

@@ -505,7 +505,8 @@ The Node.js test runner can be invoked from the command line by passing the
 node --test
 ```
 
-By default, Node.js will run all files matching these patterns:
+Unless overridden with the [`--test-files-glob`][] flag, by default Node.js will
+run all files matching these patterns:
 
 * `**/*.test.{cjs,mjs,js}`
 * `**/*-test.{cjs,mjs,js}`
@@ -4000,6 +4001,7 @@ Can be used to abort test subtasks when the test has been aborted.
 [`--test-concurrency`]: cli.md#--test-concurrency
 [`--test-coverage-exclude`]: cli.md#--test-coverage-exclude
 [`--test-coverage-include`]: cli.md#--test-coverage-include
+[`--test-files-glob`]: cli.md#--test-files-globglob
 [`--test-name-pattern`]: cli.md#--test-name-pattern
 [`--test-only`]: cli.md#--test-only
 [`--test-reporter-destination`]: cli.md#--test-reporter-destination

doc/node-config-schema.json

@@ -398,6 +398,9 @@
         "test-coverage-lines": {
           "type": "number"
         },
+        "test-files-glob": {
+          "type": "string"
+        },
         "test-global-setup": {
           "type": "string"
         },
@@ -653,6 +656,9 @@
         "test-coverage-lines": {
           "type": "number"
         },
+        "test-files-glob": {
+          "type": "string"
+        },
         "test-force-exit": {
           "type": "boolean"
         },

doc/node.1

@@ -476,6 +476,10 @@ A glob pattern that only includes matching files in the coverage report
 .It Fl -test-coverage-lines Ns = Ns Ar threshold
 Require a minimum threshold for line coverage (0 - 100).
 .
+.It Fl -test-files-glob
+A glob pattern that configures the test runner to only run tests whose filename
+matches the provided glob.
+.
 .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/runner.js

@@ -116,10 +116,10 @@ const kCanceledTests = new SafeSet()
 
 let kResistStopPropagation;
 
-function createTestFileList(patterns, cwd) {
+function createTestFileList(patterns, cwd, defaultPattern) {
   const hasUserSuppliedPattern = patterns != null;
   if (!patterns || patterns.length === 0) {
-    patterns = [kDefaultPattern];
+    patterns = [defaultPattern || kDefaultPattern];
   }
   const glob = new Glob(patterns, {
     __proto__: null,
@@ -507,7 +507,7 @@ function watchFiles(testFiles, opts) {
   // Watch for changes in current filtered files
   watcher.on('changed', ({ owners, eventType }) => {
     if (!opts.hasFiles && (eventType === 'rename' || eventType === 'change')) {
-      const updatedTestFiles = createTestFileList(opts.globPatterns, opts.cwd);
+      const updatedTestFiles = createTestFileList(opts.globPatterns, opts.cwd, opts.testFilesGlob);
       const newFileName = ArrayPrototypeFind(updatedTestFiles, (x) => !ArrayPrototypeIncludes(testFiles, x));
       const previousFileName = ArrayPrototypeFind(testFiles, (x) => !ArrayPrototypeIncludes(updatedTestFiles, x));
 
@@ -585,6 +585,7 @@ function run(options = kEmptyObject) {
     globalSetupPath,
     only,
     globPatterns,
+    testFilesGlob,
     coverage = false,
     lineCoverage = 0,
     branchCoverage = 0,
@@ -616,6 +617,9 @@ function run(options = kEmptyObject) {
   if (globPatterns != null) {
     validateArray(globPatterns, 'options.globPatterns');
   }
+  if (testFilesGlob != null) {
+    validateString(testFilesGlob, 'options.testFilesGlob');
+  }
 
   validateString(cwd, 'options.cwd');
 
@@ -719,7 +723,7 @@ function run(options = kEmptyObject) {
     globalSetupPath,
   };
   const root = createTestTree(rootTestOptions, globalOptions);
-  let testFiles = files ?? createTestFileList(globPatterns, cwd);
+  let testFiles = files ?? createTestFileList(globPatterns, cwd, testFilesGlob);
   const { isTestRunner } = globalOptions;
 
   if (shard) {
@@ -737,6 +741,7 @@ function run(options = kEmptyObject) {
     inspectPort,
     testNamePatterns,
     testSkipPatterns,
+    testFilesGlob,
     hasFiles: files != null,
     globPatterns,
     only,

lib/internal/test_runner/utils.js

@@ -218,6 +218,7 @@ function parseCommandLine() {
   const watch = getOptionValue('--watch');
   const timeout = getOptionValue('--test-timeout') || Infinity;
   const rerunFailuresFilePath = getOptionValue('--test-rerun-failures');
+  const testFilesGlob = getOptionValue('--test-files-glob') || null;
   const isChildProcess = process.env.NODE_TEST_CONTEXT === 'child';
   const isChildProcessV8 = process.env.NODE_TEST_CONTEXT === 'child-v8';
   let globalSetupPath;
@@ -311,7 +312,7 @@ function parseCommandLine() {
     if (!coverageExcludeGlobs || coverageExcludeGlobs.length === 0) {
       // TODO(pmarchini): this default should follow something similar to c8 defaults
       // Default exclusions should be also exported to be used by other tools / users
-      coverageExcludeGlobs = [kDefaultPattern];
+      coverageExcludeGlobs = [testFilesGlob || kDefaultPattern];
     }
     coverageIncludeGlobs = getOptionValue('--test-coverage-include');
 
@@ -357,6 +358,7 @@ function parseCommandLine() {
     globalSetupPath,
     shard,
     sourceMaps,
+    testFilesGlob,
     testNamePatterns,
     testSkipPatterns,
     timeout,

src/node_options.cc

@@ -884,6 +884,11 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             &EnvironmentOptions::test_name_pattern,
             kAllowedInEnvvar,
             OptionNamespaces::kTestRunnerNamespace);
+  AddOption("--test-files-glob",
+            "set the default glob pattern for matching test files",
+            &EnvironmentOptions::test_files_glob,
+            kAllowedInEnvvar,
+            OptionNamespaces::kTestRunnerNamespace);
   AddOption("--test-reporter",
             "report test output using the given reporter",
             &EnvironmentOptions::test_reporter,

src/node_options.h

@@ -199,6 +199,7 @@ class EnvironmentOptions : public Options {
   bool test_runner_module_mocks = false;
   bool test_runner_update_snapshots = false;
   std::vector<std::string> test_name_pattern;
+  std::string test_files_glob;
   std::vector<std::string> test_reporter;
   std::string test_rerun_failures_path;
   std::vector<std::string> test_reporter_destination;

test/fixtures/test-runner/custom-files-glob/index-test.cjs

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('index-test.cjs should not run');

test/fixtures/test-runner/custom-files-glob/index-test.js

@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('index-test.js should not run');