test_runner: watch mode improvments

doc/api/test.md

@@ -1539,6 +1539,10 @@ This event is only emitted if `--test` flag is passed.
 Emitted when a running test writes to `stdout`.
 This event is only emitted if `--test` flag is passed.
 
+### Event: `'test:watch:drained'`
+
+Emitted when no more tests are queued for execution in watch mode.
+
 ## Class: `TestContext`
 
 <!-- YAML

lib/internal/test_runner/runner.js

@@ -335,15 +335,13 @@ class FileTest extends Test {
   }
 }
 
-const runningProcesses = new SafeMap();
-const runningSubtests = new SafeMap();
-
 function runTestFile(path, root, inspectPort, filesWatcher, testNamePatterns) {
+  const watchMode = filesWatcher != null;
   const subtest = root.createSubtest(FileTest, path, async (t) => {
     const args = getRunArgs({ path, inspectPort, testNamePatterns });
     const stdio = ['pipe', 'pipe', 'pipe'];
     const env = { ...process.env, NODE_TEST_CONTEXT: 'child-v8' };
-    if (filesWatcher) {
+    if (watchMode) {
       stdio.push('ipc');
       env.WATCH_REPORT_DEPENDENCIES = '1';
     }
@@ -352,11 +350,13 @@ function runTestFile(path, root, inspectPort, filesWatcher, testNamePatterns) {
     }
 
     const child = spawn(process.execPath, args, { signal: t.signal, encoding: 'utf8', env, stdio });
-    runningProcesses.set(path, child);
+    if (watchMode) {
+      filesWatcher.runningProcesses.set(path, child);
+      filesWatcher.watcher.watchChildProcessModules(child, path);
+    }
 
     let err;
 
-    filesWatcher?.watchChildProcessModules(child, path);
 
     child.on('error', (error) => {
       err = error;
@@ -388,8 +388,14 @@ function runTestFile(path, root, inspectPort, filesWatcher, testNamePatterns) {
       finished(child.stdout, { signal: t.signal }),
     ]);
 
-    runningProcesses.delete(path);
-    runningSubtests.delete(path);
+    if (watchMode) {
+      filesWatcher.runningProcesses.delete(path);
+      filesWatcher.runningSubtests.delete(path);
+      if (filesWatcher.runningSubtests.size === 0) {
+        root.reporter[kEmitMessage]('test:watch:drained');
+      }
+    }
+
     if (code !== 0 || signal !== null) {
       if (!err) {
         const failureType = subtest.failedSubtests ? kSubtestsFailed : kTestCodeFailure;
@@ -409,10 +415,14 @@ function runTestFile(path, root, inspectPort, filesWatcher, testNamePatterns) {
   return subtest.start();
 }
 
-function watchFiles(testFiles, root, inspectPort, testNamePatterns) {
-  const filesWatcher = new FilesWatcher({ throttle: 500, mode: 'filter' });
-  filesWatcher.on('changed', ({ owners }) => {
-    filesWatcher.unfilterFilesOwnedBy(owners);
+function watchFiles(testFiles, root, inspectPort, signal, testNamePatterns) {
+  const runningProcesses = new SafeMap();
+  const runningSubtests = new SafeMap();
+  const watcher = new FilesWatcher({ throttle: 500, mode: 'filter', signal });
+  const filesWatcher = { __proto__: null, watcher, runningProcesses, runningSubtests };
+
+  watcher.on('changed', ({ owners }) => {
+    watcher.unfilterFilesOwnedBy(owners);
     PromisePrototypeThen(SafePromiseAllReturnVoid(testFiles, async (file) => {
       if (!owners.has(file)) {
         return;
@@ -432,6 +442,8 @@ function watchFiles(testFiles, root, inspectPort, testNamePatterns) {
       triggerUncaughtException(error, true /* fromPromise */);
     }));
   });
+  signal?.addEventListener('abort', () => root.postRun(), { __proto__: null, once: true });
+
   return filesWatcher;
 }
 
@@ -474,14 +486,14 @@ function run(options) {
   let postRun = () => root.postRun();
   let filesWatcher;
   if (watch) {
-    filesWatcher = watchFiles(testFiles, root, inspectPort, testNamePatterns);
+    filesWatcher = watchFiles(testFiles, root, inspectPort, signal, testNamePatterns);
     postRun = undefined;
   }
   const runFiles = () => {
     root.harness.bootstrapComplete = true;
     return SafePromiseAllSettledReturnVoid(testFiles, (path) => {
       const subtest = runTestFile(path, root, inspectPort, filesWatcher, testNamePatterns);
-      runningSubtests.set(path, subtest);
+      filesWatcher?.runningSubtests.set(path, subtest);
       return subtest;
     });
   };

lib/internal/watch_mode/files_watcher.js

@@ -30,14 +30,18 @@ class FilesWatcher extends EventEmitter {
   #ownerDependencies = new SafeMap();
   #throttle;
   #mode;
+  #signal;
 
-  constructor({ throttle = 500, mode = 'filter' } = kEmptyObject) {
+  constructor({ throttle = 500, mode = 'filter', signal } = kEmptyObject) {
     super();
 
     validateNumber(throttle, 'options.throttle', 0, TIMEOUT_MAX);
     validateOneOf(mode, 'options.mode', ['filter', 'all']);
     this.#throttle = throttle;
     this.#mode = mode;
+    this.#signal = signal;
+
+    signal?.addEventListener('abort', () => this.clear(), { __proto__: null, once: true });
   }
 
   #isPathWatched(path) {
@@ -89,7 +93,7 @@ class FilesWatcher extends EventEmitter {
     if (this.#isPathWatched(path)) {
       return;
     }
-    const watcher = watch(path, { recursive });
+    const watcher = watch(path, { recursive, signal: this.#signal });
     watcher.on('change', (eventType, fileName) => this
       .#onChange(recursive ? resolve(path, fileName) : path));
     this.#watchers.set(path, { handle: watcher, recursive });

test/parallel/test-runner-run.mjs

@@ -117,4 +117,29 @@ describe('require(\'node:test\').run', { concurrency: true }, () => {
     assert.strictEqual(result[2], 'ok 1 - this should be skipped # SKIP test name does not match pattern\n');
     assert.strictEqual(result[5], 'ok 2 - this should be executed\n');
   });
+
+  it('should stop watch mode when abortSignal aborts', async () => {
+    const controller = new AbortController();
+    const result = await run({ files: [join(testFixtures, 'test/random.cjs')], watch: true, signal: controller.signal })
+      .compose(async function* (source) {
+        for await (const chunk of source) {
+          if (chunk.type === 'test:pass') {
+            controller.abort();
+            yield chunk.data.name;
+          }
+        }
+      })
+      .toArray();
+    assert.deepStrictEqual(result, ['this should pass']);
+  });
+
+  it('should emit "test:watch:drained" event on watch mode', async () => {
+    const controller = new AbortController();
+    await run({ files: [join(testFixtures, 'test/random.cjs')], watch: true, signal: controller.signal })
+      .on('data', function({ type }) {
+        if (type === 'test:watch:drained') {
+          controller.abort();
+        }
+      });
+  });
 });