test_runner: fix support watch with run(), add globPatterns option

doc/api/test.md

@@ -1239,6 +1239,9 @@ added:
   - v18.9.0
   - v16.19.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/53866
+    description: Added the `globPatterns` option.
   - version:
     - v22.0.0
     - v20.14.0
@@ -1260,11 +1263,16 @@ changes:
     parallel.
     If `false`, it would only run one test file at a time.
     **Default:** `false`.
+  * `cwd` {string} The current working directory for the test runner.
+    **Default:** `process.cwd()`.
   * `files`: {Array} An array containing the list of files to run.
     **Default** matching files from [test runner execution model][].
   * `forceExit`: {boolean} Configures the test runner to exit the process once
     all known tests have finished executing even if the event loop would
     otherwise remain active. **Default:** `false`.
+  * `globPatterns`: {Array} An array containing the list of glob patterns to
+    match test files. **Default:** matching files from
+    [test runner execution model][].
   * `inspectPort` {number|Function} Sets inspector port of test child process.
     This can be a number, or a function that takes no arguments and returns a
     number. If a nullish value is provided, each process gets its own port,

lib/internal/main/test_runner.js

@@ -1,5 +1,9 @@
 'use strict';
 
+const {
+  ArrayPrototypeSlice,
+} = primordials;
+
 const {
   prepareMainThreadExecution,
   markBootstrapComplete,
@@ -42,6 +46,7 @@ const options = {
   setup: setupTestReporters,
   timeout: perFileTimeout,
   shard,
+  globPatterns: ArrayPrototypeSlice(process.argv, 1),
 };
 debug('test runner configuration:', options);
 run(options).on('test:fail', (data) => {

lib/internal/test_runner/runner.js

@@ -1,4 +1,5 @@
 'use strict';
+
 const {
   ArrayIsArray,
   ArrayPrototypeEvery,
@@ -10,7 +11,6 @@ const {
   ArrayPrototypeMap,
   ArrayPrototypePush,
   ArrayPrototypeShift,
-  ArrayPrototypeSlice,
   ArrayPrototypeSome,
   ArrayPrototypeSort,
   ObjectAssign,
@@ -51,6 +51,7 @@ const {
   validateFunction,
   validateObject,
   validateInteger,
+  validateString,
 } = require('internal/validators');
 const { getInspectPort, isUsingInspector, isInspectorMessage } = require('internal/util/inspector');
 const { isRegExp } = require('internal/util/types');
@@ -88,10 +89,11 @@ const kCanceledTests = new SafeSet()
 
 let kResistStopPropagation;
 
-function createTestFileList() {
-  const cwd = process.cwd();
-  const hasUserSuppliedPattern = process.argv.length > 1;
-  const patterns = hasUserSuppliedPattern ? ArrayPrototypeSlice(process.argv, 1) : [kDefaultPattern];
+function createTestFileList(cwd, patterns) {
+  const hasUserSuppliedPattern = patterns != null;
+  if (!patterns || patterns.length === 0) {
+    patterns = [kDefaultPattern];
+  }
   const glob = new Glob(patterns, {
     __proto__: null,
     cwd,
@@ -345,7 +347,6 @@ function runTestFile(path, filesWatcher, opts) {
 
     let err;
 
-
     child.on('error', (error) => {
       err = error;
     });
@@ -419,8 +420,8 @@ function watchFiles(testFiles, opts) {
   opts.root.harness.watching = true;
 
   watcher.on('changed', ({ owners, eventType }) => {
-    if (eventType === 'rename') {
-      const updatedTestFiles = createTestFileList();
+    if (!opts.hasFiles && eventType === 'rename') {
+      const updatedTestFiles = createTestFileList(opts.cwd, opts.globPatterns);
 
       const newFileName = ArrayPrototypeFind(updatedTestFiles, (x) => !ArrayPrototypeIncludes(testFiles, x));
       const previousFileName = ArrayPrototypeFind(testFiles, (x) => !ArrayPrototypeIncludes(updatedTestFiles, x));
@@ -483,6 +484,8 @@ function run(options = kEmptyObject) {
     watch,
     setup,
     only,
+    cwd,
+    globPatterns,
   } = options;
 
   if (files != null) {
@@ -503,6 +506,16 @@ function run(options = kEmptyObject) {
   if (only != null) {
     validateBoolean(only, 'options.only');
   }
+  if (globPatterns != null) {
+    validateArray(globPatterns, 'options.globPatterns');
+  }
+
+  if (globPatterns?.length > 0 && files?.length > 0) {
+    throw new ERR_INVALID_ARG_VALUE(
+      'options.globPatterns', globPatterns, 'is not supported when specifying \'options.files\'',
+    );
+  }
+
   if (shard != null) {
     validateObject(shard, 'options.shard');
     // Avoid re-evaluating the shard object in case it's a getter
@@ -518,6 +531,11 @@ function run(options = kEmptyObject) {
   if (setup != null) {
     validateFunction(setup, 'options.setup');
   }
+
+  if (cwd != null) {
+    validateString(cwd, 'options.cwd');
+  }
+
   if (testNamePatterns != null) {
     if (!ArrayIsArray(testNamePatterns)) {
       testNamePatterns = [testNamePatterns];
@@ -559,7 +577,7 @@ function run(options = kEmptyObject) {
     root.postRun();
     return root.reporter;
   }
-  let testFiles = files ?? createTestFileList();
+  let testFiles = files ?? createTestFileList(cwd, globPatterns);
 
   if (shard) {
     testFiles = ArrayPrototypeFilter(testFiles, (_, index) => index % shard.total === shard.index - 1);
@@ -574,8 +592,11 @@ function run(options = kEmptyObject) {
     inspectPort,
     testNamePatterns,
     testSkipPatterns,
+    hasFiles: files != null,
+    globPatterns,
     only,
     forceExit,
+    cwd,
   };
   if (watch) {
     filesWatcher = watchFiles(testFiles, opts);

test/fixtures/test-runner-watch.mjs

@@ -0,0 +1,24 @@
+import { run } from 'node:test';
+import { tap } from 'node:test/reporters';
+import { parseArgs } from 'node:util';
+
+const options = {
+  file: {
+    type: 'string',
+  },
+};
+const {
+  values,
+  positionals,
+} = parseArgs({ args: process.argv.slice(2), options });
+
+let files;
+
+if (values.file) {
+  files = [values.file];
+}
+
+run({
+  files,
+  watch: true
+}).compose(tap).pipe(process.stdout);

test/parallel/test-runner-run-watch.mjs

@@ -0,0 +1,171 @@
+// Flags: --expose-internals
+import * as common from '../common/index.mjs';
+import { describe, it, beforeEach } from 'node:test';
+import assert from 'node:assert';
+import { spawn } from 'node:child_process';
+import { writeFileSync, renameSync, unlinkSync, existsSync } from 'node:fs';
+import util from 'internal/util';
+import tmpdir from '../common/tmpdir.js';
+import { join } from 'node:path';
+
+if (common.isIBMi)
+  common.skip('IBMi does not support `fs.watch()`');
+
+// This test updates these files repeatedly,
+// Reading them from disk is unreliable due to race conditions.
+const fixtureContent = {
+  'dependency.js': 'module.exports = {};',
+  'dependency.mjs': 'export const a = 1;',
+  'test.js': `
+const test = require('node:test');
+require('./dependency.js');
+import('./dependency.mjs');
+import('data:text/javascript,');
+test('test has ran');`,
+};
+
+let fixturePaths;
+
+function refresh() {
+  tmpdir.refresh();
+
+  fixturePaths = Object.keys(fixtureContent)
+    .reduce((acc, file) => ({ ...acc, [file]: tmpdir.resolve(file) }), {});
+  Object.entries(fixtureContent)
+    .forEach(([file, content]) => writeFileSync(fixturePaths[file], content));
+}
+
+const runner = join(import.meta.dirname, '..', 'fixtures', 'test-runner-watch.mjs');
+
+async function testWatch({ fileToUpdate, file, action = 'update', cwd = tmpdir.path }) {
+  const ran1 = util.createDeferredPromise();
+  const ran2 = util.createDeferredPromise();
+  const args = [runner];
+  if (file) args.push('--file', file);
+  const child = spawn(process.execPath,
+                      args,
+                      { encoding: 'utf8', stdio: 'pipe', cwd });
+  let stdout = '';
+  let currentRun = '';
+  const runs = [];
+
+  child.stdout.on('data', (data) => {
+    stdout += data.toString();
+    currentRun += data.toString();
+    const testRuns = stdout.match(/# duration_ms\s\d+/g);
+    if (testRuns?.length >= 1) ran1.resolve();
+    if (testRuns?.length >= 2) ran2.resolve();
+  });
+
+  const testUpdate = async () => {
+    await ran1.promise;
+    const content = fixtureContent[fileToUpdate];
+    const path = fixturePaths[fileToUpdate];
+    const interval = setInterval(() => writeFileSync(path, content), common.platformTimeout(1000));
+    await ran2.promise;
+    runs.push(currentRun);
+    clearInterval(interval);
+    child.kill();
+    for (const run of runs) {
+      assert.doesNotMatch(run, /run\(\) is being called recursively/);
+      assert.match(run, /# tests 1/);
+      assert.match(run, /# pass 1/);
+      assert.match(run, /# fail 0/);
+      assert.match(run, /# cancelled 0/);
+    }
+  };
+
+  const testRename = async () => {
+    await ran1.promise;
+    const fileToRenamePath = tmpdir.resolve(fileToUpdate);
+    const newFileNamePath = tmpdir.resolve(`test-renamed-${fileToUpdate}`);
+    const interval = setInterval(() => renameSync(fileToRenamePath, newFileNamePath), common.platformTimeout(1000));
+    await ran2.promise;
+    runs.push(currentRun);
+    clearInterval(interval);
+    child.kill();
+
+    for (const run of runs) {
+      assert.doesNotMatch(run, /run\(\) is being called recursively/);
+      if (action === 'rename2') {
+        assert.match(run, /MODULE_NOT_FOUND/);
+      } else {
+        assert.doesNotMatch(run, /MODULE_NOT_FOUND/);
+      }
+      assert.match(run, /# tests 1/);
+      assert.match(run, /# pass 1/);
+      assert.match(run, /# fail 0/);
+      assert.match(run, /# cancelled 0/);
+    }
+  };
+
+  const testDelete = async () => {
+    await ran1.promise;
+    const fileToDeletePath = tmpdir.resolve(fileToUpdate);
+    const interval = setInterval(() => {
+      if (existsSync(fileToDeletePath)) {
+        unlinkSync(fileToDeletePath);
+      } else {
+        ran2.resolve();
+      }
+    }, common.platformTimeout(1000));
+    await ran2.promise;
+    runs.push(currentRun);
+    clearInterval(interval);
+    child.kill();
+
+    for (const run of runs) {
+      assert.doesNotMatch(run, /MODULE_NOT_FOUND/);
+    }
+  };
+
+  action === 'update' && await testUpdate();
+  action === 'rename' && await testRename();
+  action === 'rename2' && await testRename();
+  action === 'delete' && await testDelete();
+}
+
+describe('test runner watch mode', () => {
+  beforeEach(refresh);
+  it('should run tests repeatedly', async () => {
+    await testWatch({ file: 'test.js', fileToUpdate: 'test.js' });
+  });
+
+  it('should run tests with dependency repeatedly', async () => {
+    await testWatch({ file: 'test.js', fileToUpdate: 'dependency.js' });
+  });
+
+  it('should run tests with ESM dependency', async () => {
+    await testWatch({ file: 'test.js', fileToUpdate: 'dependency.mjs' });
+  });
+
+  it('should support running tests without a file', async () => {
+    await testWatch({ fileToUpdate: 'test.js' });
+  });
+
+  it('should support a watched test file rename', async () => {
+    await testWatch({ fileToUpdate: 'test.js', action: 'rename' });
+  });
+
+  it('should not throw when deleting a watched test file', async () => {
+    await testWatch({ fileToUpdate: 'test.js', action: 'delete' });
+  });
+
+  it('should run tests with dependency repeatedly in a different cwd', async () => {
+    await testWatch({
+      file: join(tmpdir.path, 'test.js'),
+      fileToUpdate: 'dependency.js',
+      cwd: import.meta.dirname,
+      action: 'rename2'
+    });
+  });
+
+  it('should handle renames in a different cwd', async () => {
+    await testWatch({
+      file: join(tmpdir.path, 'test.js'),
+      fileToUpdate: 'test.js',
+      cwd: import.meta.dirname,
+      action: 'rename2'
+    });
+  });
+});