test: add --test-files-glob flag

p-mcgowan · p-mcgowan · commit 00192a63b277 · 2025-06-27T19:17:53.000+02:00
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
diff --git a/doc/api/cli.md b/doc/api/cli.md
@@ -2508,6 +2508,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
@@ -3435,6 +3449,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`
diff --git a/doc/api/test.md b/doc/api/test.md
@@ -465,7 +465,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}`
@@ -3925,6 +3926,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
diff --git a/doc/node-config-schema.json b/doc/node-config-schema.json
@@ -395,6 +395,9 @@
         "test-coverage-lines": {
           "type": "number"
         },
+        "test-files-glob": {
+          "type": "string"
+        },
         "test-global-setup": {
           "type": "string"
         },
@@ -638,6 +641,9 @@
         "test-coverage-lines": {
           "type": "number"
         },
+        "test-files-glob": {
+          "type": "string"
+        },
         "test-force-exit": {
           "type": "boolean"
         },
diff --git a/lib/internal/test_runner/runner.js b/lib/internal/test_runner/runner.js
@@ -113,10 +113,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,
@@ -499,7 +499,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));
 
@@ -577,6 +577,7 @@ function run(options = kEmptyObject) {
     globalSetupPath,
     only,
     globPatterns,
+    testFilesGlob,
     coverage = false,
     lineCoverage = 0,
     branchCoverage = 0,
@@ -607,6 +608,9 @@ function run(options = kEmptyObject) {
   if (globPatterns != null) {
     validateArray(globPatterns, 'options.globPatterns');
   }
+  if (testFilesGlob != null) {
+    validateString(testFilesGlob, 'options.testFilesGlob');
+  }
 
   validateString(cwd, 'options.cwd');
 
@@ -705,7 +709,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) {
@@ -723,6 +727,7 @@ function run(options = kEmptyObject) {
     inspectPort,
     testNamePatterns,
     testSkipPatterns,
+    testFilesGlob,
     hasFiles: files != null,
     globPatterns,
     only,
diff --git a/lib/internal/test_runner/utils.js b/lib/internal/test_runner/utils.js
@@ -202,6 +202,7 @@ function parseCommandLine() {
   const updateSnapshots = getOptionValue('--test-update-snapshots');
   const watch = getOptionValue('--watch');
   const timeout = getOptionValue('--test-timeout') || Infinity;
+  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;
@@ -295,7 +296,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');
 
@@ -338,6 +339,7 @@ function parseCommandLine() {
     globalSetupPath,
     shard,
     sourceMaps,
+    testFilesGlob,
     testNamePatterns,
     testSkipPatterns,
     timeout,
diff --git a/src/node_options.cc b/src/node_options.cc
@@ -828,6 +828,14 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             &EnvironmentOptions::test_name_pattern,
             kAllowedInEnvvar,
             OptionNamespaces::kTestRunnerNamespace);
+  AddOption("--test-files-glob",
+            "set the default glob pattern for matching test files (default: "
+            "'**/{test,test/**/*,test-*,*[._-]test}.{<extensions>}' where "
+            "<extensions> is 'js,mjs,cjs' or 'js,mjs,cjs,ts,mts,cts' when using"
+            " --experimental-strip-types)",
+            &EnvironmentOptions::test_files_glob,
+            kAllowedInEnvvar,
+            OptionNamespaces::kTestRunnerNamespace);
   AddOption("--test-reporter",
             "report test output using the given reporter",
             &EnvironmentOptions::test_reporter,
diff --git a/src/node_options.h b/src/node_options.h
@@ -197,6 +197,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::vector<std::string> test_reporter_destination;
   std::string test_global_setup_path;
diff --git a/test/fixtures/test-runner/custom-files-glob/index-test.cjs b/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');
diff --git a/test/fixtures/test-runner/custom-files-glob/index-test.js b/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');
diff --git a/test/fixtures/test-runner/custom-files-glob/index-test.mjs b/test/fixtures/test-runner/custom-files-glob/index-test.mjs
@@ -0,0 +1,4 @@
+'use strict';
+import test from 'node:test';
+
+test('index-test.mjs should not run');
diff --git a/test/fixtures/test-runner/custom-files-glob/index-test.spec.cjs b/test/fixtures/test-runner/custom-files-glob/index-test.spec.cjs
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('index-test.spec.cjs this should pass');
diff --git a/test/fixtures/test-runner/custom-files-glob/index-test.spec.js b/test/fixtures/test-runner/custom-files-glob/index-test.spec.js
@@ -0,0 +1,4 @@
+'use strict';
+const test = require('node:test');
+
+test('index-test.spec.js this should pass');
diff --git a/test/fixtures/test-runner/custom-files-glob/index-test.spec.mjs b/test/fixtures/test-runner/custom-files-glob/index-test.spec.mjs
@@ -0,0 +1,4 @@
+'use strict';
+import test from 'node:test';
+
+test('index-test.spec.mjs this should pass');
diff --git a/test/fixtures/test-runner/custom-files-glob/typescript-test.cts b/test/fixtures/test-runner/custom-files-glob/typescript-test.cts
@@ -0,0 +1,4 @@
+const test = require('node:test');
+
+// 'as string' ensures that type stripping actually occurs
+test('typescript-test.cts should not run' as string);
diff --git a/test/fixtures/test-runner/custom-files-glob/typescript-test.mts b/test/fixtures/test-runner/custom-files-glob/typescript-test.mts
@@ -0,0 +1,4 @@
+import { test } from 'node:test';
+
+// 'as string' ensures that type stripping actually occurs
+test('typescript-test.mts should not run' as string);
diff --git a/test/fixtures/test-runner/custom-files-glob/typescript-test.spec.cts b/test/fixtures/test-runner/custom-files-glob/typescript-test.spec.cts
@@ -0,0 +1,4 @@
+const test = require('node:test');
+
+// 'as string' ensures that type stripping actually occurs
+test('typescript-test.spec.cts this should pass' as string);
diff --git a/test/fixtures/test-runner/custom-files-glob/typescript-test.spec.mts b/test/fixtures/test-runner/custom-files-glob/typescript-test.spec.mts
@@ -0,0 +1,4 @@
+import { test } from 'node:test';
+
+// 'as string' ensures that type stripping actually occurs
+test('typescript-test.spec.mts this should pass' as string);
diff --git a/test/fixtures/test-runner/custom-files-glob/typescript-test.spec.ts b/test/fixtures/test-runner/custom-files-glob/typescript-test.spec.ts
@@ -0,0 +1,4 @@
+const test = require('node:test');
+
+// 'as string' ensures that type stripping actually occurs
+test('typescript-test.spec.ts this should pass' as string);
diff --git a/test/fixtures/test-runner/custom-files-glob/typescript-test.ts b/test/fixtures/test-runner/custom-files-glob/typescript-test.ts
@@ -0,0 +1,4 @@
+const test = require('node:test');
+
+// 'as string' ensures that type stripping actually occurs
+test('typescript-test.ts this should pass' as string);
diff --git a/test/parallel/test-runner-cli.js b/test/parallel/test-runner-cli.js
@@ -23,6 +23,21 @@ for (const isolation of ['none', 'process']) {
     assert.match(child.stderr.toString(), /^Could not find/);
   }
 
+  {
+    // File not found (--test-files-glob).
+    const args = [
+      '--test',
+      `--test-isolation=${isolation}`,
+      '--test-files-glob=a-random-file-that-does-not-exist.js',
+    ];
+    const child = spawnSync(process.execPath, args);
+
+    assert.strictEqual(child.status, 1);
+    assert.strictEqual(child.signal, null);
+    assert.strictEqual(child.stdout.toString(), '');
+    assert.match(child.stderr.toString(), /^Could not find/);
+  }
+
   {
     // Default behavior. node_modules is ignored. Files that don't match the
     // pattern are ignored except in test/ directories.
@@ -62,27 +77,100 @@ for (const isolation of ['none', 'process']) {
     assert.doesNotMatch(stdout, /ok 4 - this should pass/);
   }
 
+  {
+    // Should override default file matching (**/{test,test/**/*,test-*,*[._-]test}.{js,mjs,cjs})
+    const args = [
+      '--test',
+      '--test-reporter=tap',
+      '--test-files-glob=**/*.spec.{js,mjs,cjs}',
+      `--test-isolation=${isolation}`,
+    ];
+    const child = spawnSync(process.execPath, args, { cwd: join(testFixtures, 'custom-files-glob') });
+
+    assert.strictEqual(child.status, 0);
+    assert.strictEqual(child.signal, null);
+    assert.strictEqual(child.stderr.toString(), '');
+    const stdout = child.stdout.toString();
+    process.stderr.write(stdout);
+
+    assert.match(stdout, /ok 1 - index-test\.spec\.cjs this should pass/);
+    assert.match(stdout, /ok 2 - index-test\.spec\.js this should pass/);
+    assert.match(stdout, /ok 3 - index-test\.spec\.mjs this should pass/);
+    assert.doesNotMatch(stdout, /ok 4 - /);
+  }
+
+  {
+    // Should ignore glob override when targeted file passed in
+    const args = [
+      '--test',
+      '--test-reporter=tap',
+      '--test-files-glob=**/*.spec.{js,mjs,cjs}',
+      `--test-isolation=${isolation}`,
+      'index-test.js',
+    ];
+    const child = spawnSync(process.execPath, args, { cwd: join(testFixtures, 'custom-files-glob') });
+
+    assert.strictEqual(child.status, 0);
+    assert.strictEqual(child.signal, null);
+    assert.strictEqual(child.stderr.toString(), '');
+    const stdout = child.stdout.toString();
+    process.stderr.write(stdout);
+
+    assert.match(stdout, /ok 1 - index-test\.js should not run/);
+    assert.doesNotMatch(stdout, /ok 2 - /);
+  }
+
   for (const type of ['strip', 'transform']) {
-    // Should match files with "-test.(c|m)(t|j)s" suffix when typescript support is enabled
-    const args = ['--test', '--test-reporter=tap', '--no-warnings',
-                  `--experimental-${type}-types`, `--test-isolation=${isolation}`];
-    const child = spawnSync(process.execPath, args, { cwd: join(testFixtures, 'matching-patterns') });
+    {
+      // Should match files with "-test.(c|m)(t|j)s" suffix when typescript support is enabled
+      const args = ['--test', '--test-reporter=tap', '--no-warnings',
+                    `--experimental-${type}-types`, `--test-isolation=${isolation}`];
+      const child = spawnSync(process.execPath, args, { cwd: join(testFixtures, 'matching-patterns') });
+
+      if (!process.config.variables.node_use_amaro) {
+        // e.g. Compiled with `--without-amaro`.
+        assert.strictEqual(child.status, 1);
+      } else {
+        assert.strictEqual(child.stderr.toString(), '');
+        const stdout = child.stdout.toString();
+
+        assert.match(stdout, /ok 1 - this should pass/);
+        assert.match(stdout, /ok 2 - this should pass/);
+        assert.match(stdout, /ok 3 - this should pass/);
+        assert.match(stdout, /ok 4 - this should pass/);
+        assert.match(stdout, /ok 5 - this should pass/);
+        assert.match(stdout, /ok 6 - this should pass/);
+        assert.strictEqual(child.status, 0);
+        assert.strictEqual(child.signal, null);
+      }
+    }
 
-    if (!process.config.variables.node_use_amaro) {
-      // e.g. Compiled with `--without-amaro`.
-      assert.strictEqual(child.status, 1);
-    } else {
-      assert.strictEqual(child.stderr.toString(), '');
-      const stdout = child.stdout.toString();
-
-      assert.match(stdout, /ok 1 - this should pass/);
-      assert.match(stdout, /ok 2 - this should pass/);
-      assert.match(stdout, /ok 3 - this should pass/);
-      assert.match(stdout, /ok 4 - this should pass/);
-      assert.match(stdout, /ok 5 - this should pass/);
-      assert.match(stdout, /ok 6 - this should pass/);
-      assert.strictEqual(child.status, 0);
-      assert.strictEqual(child.signal, null);
+    {
+      // Should override default file matching (**/{test,test/**/*,test-*,*[._-]test}.{js,mjs,cjs,ts,mts,cts})
+      const args = [
+        '--test',
+        '--test-reporter=tap',
+        '--no-warnings',
+        '--test-files-glob=*.spec.{ts,mts,cts}',
+        `--experimental-${type}-types`,
+        `--test-isolation=${isolation}`,
+      ];
+      const child = spawnSync(process.execPath, args, { cwd: join(testFixtures, 'custom-files-glob') });
+
+      if (!process.config.variables.node_use_amaro) {
+        // e.g. Compiled with `--without-amaro`.
+        assert.strictEqual(child.status, 1);
+      } else {
+        assert.strictEqual(child.status, 0);
+        assert.strictEqual(child.signal, null);
+        assert.strictEqual(child.stderr.toString(), '');
+        const stdout = child.stdout.toString();
+
+        assert.match(stdout, /ok 1 - typescript-test\.spec\.cts this should pass/);
+        assert.match(stdout, /ok 2 - typescript-test\.spec\.mts this should pass/);
+        assert.match(stdout, /ok 3 - typescript-test\.spec\.ts this should pass/);
+        assert.doesNotMatch(stdout, /ok 4 - /);
+      }
     }
   }
 
@@ -125,6 +213,24 @@ for (const isolation of ['none', 'process']) {
     assert.strictEqual(child.signal, null);
   }
 
+  {
+    // User specified files that don't match the --test-files-glob are still run.
+    const args = [
+      '--test',
+      '--test-reporter=tap',
+      `--test-isolation=${isolation}`,
+      '--test-files-glob=**/{test,test/**/*,test-*,*[._-]test}.{js,mjs,cjs}',
+      join(testFixtures, 'index.js'),
+    ];
+    const child = spawnSync(process.execPath, args, { cwd: testFixtures });
+
+    assert.strictEqual(child.stderr.toString(), '');
+    const stdout = child.stdout.toString();
+    assert.match(stdout, /not ok 1 - .+index\.js/);
+    assert.strictEqual(child.status, 1);
+    assert.strictEqual(child.signal, null);
+  }
+
   {
     // Searches node_modules if specified.
     const args = [
diff --git a/test/parallel/test-runner-coverage.js b/test/parallel/test-runner-coverage.js
