test_runner: emit test:watch:drained event

PR-URL: #48259
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

doc/api/test.md

@@ -1473,6 +1473,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

@@ -341,25 +341,25 @@ 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';
     }
 
     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;
@@ -391,8 +391,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;
@@ -413,9 +419,13 @@ function runTestFile(path, root, inspectPort, filesWatcher, testNamePatterns) {
 }
 
 function watchFiles(testFiles, root, inspectPort, signal, testNamePatterns) {
-  const filesWatcher = new FilesWatcher({ throttle: 500, mode: 'filter', signal });
-  filesWatcher.on('changed', ({ owners }) => {
-    filesWatcher.unfilterFilesOwnedBy(owners);
+  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;
@@ -436,6 +446,7 @@ function watchFiles(testFiles, root, inspectPort, signal, testNamePatterns) {
     }));
   });
   signal?.addEventListener('abort', () => root.postRun(), { __proto__: null, once: true });
+
   return filesWatcher;
 }
 
@@ -485,7 +496,7 @@ function run(options) {
     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;
     });
   };

test/parallel/test-runner-run.mjs

@@ -132,4 +132,14 @@ describe('require(\'node:test\').run', { concurrency: true }, () => {
       .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();
+        }
+      });
+  });
 });