test_runner: emit test:watch:restarted event on watched file changes

doc/api/test.md

@@ -1114,6 +1114,9 @@ const customReporter = new Transform({
       case 'test:watch:drained':
         callback(null, 'test watch queue drained');
         break;
+      case 'test:watch:restarted':
+        callback(null, 'test watch restarted due to file change');
+        break;
       case 'test:start':
         callback(null, `test ${event.data.name} started`);
         break;
@@ -1159,6 +1162,9 @@ const customReporter = new Transform({
       case 'test:watch:drained':
         callback(null, 'test watch queue drained');
         break;
+      case 'test:watch:restarted':
+        callback(null, 'test watch restarted due to file change');
+        break;
       case 'test:start':
         callback(null, `test ${event.data.name} started`);
         break;
@@ -1203,6 +1209,9 @@ export default async function * customReporter(source) {
       case 'test:watch:drained':
         yield 'test watch queue drained\n';
         break;
+      case 'test:watch:restarted':
+        yield 'test watch restarted due to file change\n';
+        break;
       case 'test:start':
         yield `test ${event.data.name} started\n`;
         break;
@@ -1243,6 +1252,9 @@ module.exports = async function * customReporter(source) {
       case 'test:watch:drained':
         yield 'test watch queue drained\n';
         break;
+      case 'test:watch:restarted':
+        yield 'test watch restarted due to file change\n';
+        break;
       case 'test:start':
         yield `test ${event.data.name} started\n`;
         break;
@@ -3158,6 +3170,10 @@ generated for each test file in addition to a final cumulative summary.
 
 Emitted when no more tests are queued for execution in watch mode.
 
+### Event: `'test:watch:restarted'`
+
+Emitted when one or more tests are restarted due to a file change in watch mode.
+
 ## Class: `TestContext`
 
 <!-- YAML

lib/internal/test_runner/runner.js

@@ -480,6 +480,7 @@ function watchFiles(testFiles, opts) {
       // Reset the topLevel counter
       opts.root.harness.counters.topLevel = 0;
     }
+
     await runningSubtests.get(file);
     runningSubtests.set(file, runTestFile(file, filesWatcher, opts));
   }
@@ -507,6 +508,8 @@ function watchFiles(testFiles, opts) {
     // Reset the root start time to recalculate the duration
     // of the run
     opts.root.clearExecutionTime();
+    opts.root.reporter[kEmitMessage]('test:watch:restarted');
+
     // Restart test files
     if (opts.isolation === 'none') {
       PromisePrototypeThen(restartTestFile(kIsolatedProcessName), undefined, (error) => {

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

@@ -257,6 +257,56 @@ describe('test runner watch mode', () => {
     assert.notDeepStrictEqual(durations[0][1], durations[1][1]);
   });
 
+  it('should emit test:watch:restarted when file is updated', async () => {
+    let alreadyDrained = false;
+    const events = [];
+    const testWatchRestarted = common.mustCall(1);
+
+    const controller = new AbortController();
+    const stream = run({
+      cwd: tmpdir.path,
+      watch: true,
+      signal: controller.signal,
+    }).on('data', function({ type }) {
+      events.push(type);
+      if (type === 'test:watch:restarted') {
+        testWatchRestarted();
+      }
+      if (type === 'test:watch:drained') {
+        if (alreadyDrained) {
+          controller.abort();
+        }
+        alreadyDrained = true;
+      }
+    });
+
+    await once(stream, 'test:watch:drained');
+
+    writeFileSync(join(tmpdir.path, 'test.js'), fixtureContent['test.js']);
+
+    // eslint-disable-next-line no-unused-vars
+    for await (const _ of stream);
+
+    assert.partialDeepStrictEqual(events, [
+      'test:watch:drained',
+      'test:watch:restarted',
+      'test:watch:drained',
+    ]);
+  });
+
+  it('should not emit test:watch:restarted since watch mode is disabled', async () => {
+    const stream = run({
+      cwd: tmpdir.path,
+      watch: false,
+    });
+
+    stream.on('test:watch:restarted', common.mustNotCall());
+    writeFileSync(join(tmpdir.path, 'test.js'), fixtureContent['test.js']);
+
+    // eslint-disable-next-line no-unused-vars
+    for await (const _ of stream);
+  });
+
   describe('test runner watch mode with different cwd', () => {
     it(
       'should execute run using a different cwd for the runner than the process cwd',