fix(browser): support quitting watch mode from the terminal (#1026)

Author: fi3ework

e2e/browser-mode/watch.test.ts

@@ -114,14 +114,8 @@ describe('browser mode - watch', () => {
     // Initial run outputs full summary with Duration
     await cli.waitForStdout('Duration');
     expect(cli.stdout).toMatch('Test Files 2 passed');
-    if (
-      !cli.stdout.includes(
-        'Watch mode enabled - will re-run tests on file changes',
-      )
-    ) {
-      await cli.waitForStdout(
-        'Watch mode enabled - will re-run tests on file changes',
-      );
+    if (!cli.stdout.includes('Waiting for file changes...')) {
+      await cli.waitForStdout('Waiting for file changes...');
     }
 
     const newTestPath = path.join(fixturesTargetPath, 'tests/new.test.ts');

e2e/browser-mode/watchReporter.test.ts

@@ -69,14 +69,8 @@ describe('browser mode - watch reporter lifecycle', () => {
 
       await waitForHookCounts(1, 1);
 
-      if (
-        !cli.stdout.includes(
-          'Watch mode enabled - will re-run tests on file changes',
-        )
-      ) {
-        await cli.waitForStdout(
-          'Watch mode enabled - will re-run tests on file changes',
-        );
+      if (!cli.stdout.includes('Waiting for file changes...')) {
+        await cli.waitForStdout('Waiting for file changes...');
       }
 
       const testFilePath = path.join(fixturesTargetPath, 'tests/index.test.ts');

packages/browser/src/hostController.ts

@@ -78,6 +78,11 @@ import {
   type SourceMapPayload,
 } from './sourceMap/sourceMapLoader';
 import { resolveBrowserViewportPreset } from './viewportPresets';
+import {
+  isBrowserWatchCliShortcutsEnabled,
+  logBrowserWatchReadyMessage,
+  setupBrowserWatchCliShortcuts,
+} from './watchCliShortcuts';
 import { collectWatchTestFiles, planWatchRerun } from './watchRerunPlanner';
 
 const { createRsbuild, rspack } = rsbuild;
@@ -317,6 +322,8 @@ type WatchContext = {
   lastTestFiles: TestFileInfo[];
   hooksEnabled: boolean;
   cleanupRegistered: boolean;
+  cleanupPromise: Promise<void> | null;
+  closeCliShortcuts: (() => void) | null;
   chunkHashes: Map<string, string>;
   affectedTestFiles: string[];
 };
@@ -326,6 +333,8 @@ const watchContext: WatchContext = {
   lastTestFiles: [],
   hooksEnabled: false,
   cleanupRegistered: false,
+  cleanupPromise: null,
+  closeCliShortcuts: null,
   chunkHashes: new Map(),
   affectedTestFiles: [],
 };
@@ -998,27 +1007,39 @@ const destroyBrowserRuntime = async (
     .catch(() => {});
 };
 
-const registerWatchCleanup = (): void => {
-  if (watchContext.cleanupRegistered) {
-    return;
+const cleanupWatchRuntime = (): Promise<void> => {
+  if (watchContext.cleanupPromise) {
+    return watchContext.cleanupPromise;
   }
 
-  const cleanup = async () => {
+  watchContext.cleanupPromise = (async () => {
+    watchContext.closeCliShortcuts?.();
+    watchContext.closeCliShortcuts = null;
+
     if (!watchContext.runtime) {
       return;
     }
+
     await destroyBrowserRuntime(watchContext.runtime);
     watchContext.runtime = null;
-  };
+  })();
+
+  return watchContext.cleanupPromise;
+};
+
+const registerWatchCleanup = (): void => {
+  if (watchContext.cleanupRegistered) {
+    return;
+  }
 
   for (const signal of ['SIGINT', 'SIGTERM', 'SIGTSTP'] as const) {
     process.once(signal, () => {
-      void cleanup();
+      void cleanupWatchRuntime();
     });
   }
 
   process.once('exit', () => {
-    void cleanup();
+    void cleanupWatchRuntime();
   });
 
   watchContext.cleanupRegistered = true;
@@ -1718,6 +1739,7 @@ export const runBrowserController = async (
   await notifyTestRunStart();
 
   const isWatchMode = context.command === 'watch';
+  const enableCliShortcuts = isWatchMode && isBrowserWatchCliShortcutsEnabled();
   const tempDir =
     isWatchMode && watchContext.runtime
       ? watchContext.runtime.tempDir
@@ -1771,6 +1793,12 @@ export const runBrowserController = async (
     if (isWatchMode) {
       watchContext.runtime = runtime;
       registerWatchCleanup();
+
+      if (enableCliShortcuts && !watchContext.closeCliShortcuts) {
+        watchContext.closeCliShortcuts = await setupBrowserWatchCliShortcuts({
+          close: cleanupWatchRuntime,
+        });
+      }
     }
   }
 
@@ -2411,6 +2439,7 @@ export const runBrowserController = async (
                 ? [rerunFatalError]
                 : undefined,
           });
+          logBrowserWatchReadyMessage(enableCliShortcuts);
         }
       },
       onError: async (error) => {
@@ -2455,6 +2484,7 @@ export const runBrowserController = async (
             logger.log(
               color.cyan('No browser test files remain after update.\n'),
             );
+            logBrowserWatchReadyMessage(enableCliShortcuts);
             return;
           }
 
@@ -2473,6 +2503,7 @@ export const runBrowserController = async (
               'No affected browser test files detected, skipping re-run.\n',
             ),
           );
+          logBrowserWatchReadyMessage(enableCliShortcuts);
           return;
         }
 
@@ -2531,11 +2562,7 @@ export const runBrowserController = async (
 
     if (isWatchMode && triggerRerun) {
       watchContext.hooksEnabled = true;
-      logger.log(
-        color.cyan(
-          '\nWatch mode enabled - will re-run tests on file changes\n',
-        ),
-      );
+      logBrowserWatchReadyMessage(enableCliShortcuts);
     }
 
     return result;
@@ -2883,9 +2910,13 @@ export const runBrowserController = async (
                 ? [rerunFatalError]
                 : undefined,
           });
+          logBrowserWatchReadyMessage(enableCliShortcuts);
         }
       } else if (!rerunPlan.filesChanged) {
         logger.log(color.cyan('Tests will be re-executed automatically\n'));
+        logBrowserWatchReadyMessage(enableCliShortcuts);
+      } else {
+        logBrowserWatchReadyMessage(enableCliShortcuts);
       }
     };
   }
@@ -2946,9 +2977,7 @@ export const runBrowserController = async (
   // Enable watch hooks AFTER initial test run to avoid duplicate runs
   if (isWatchMode && triggerRerun) {
     watchContext.hooksEnabled = true;
-    logger.log(
-      color.cyan('\nWatch mode enabled - will re-run tests on file changes\n'),
-    );
+    logBrowserWatchReadyMessage(enableCliShortcuts);
   }
 
   return result;

packages/browser/src/watchCliShortcuts.ts

@@ -0,0 +1,77 @@
+import { color, logger } from '@rstest/core/browser';
+
+const isTTY = (): boolean => Boolean(process.stdin.isTTY && !process.env.CI);
+
+export const isBrowserWatchCliShortcutsEnabled = (): boolean => isTTY();
+
+export const getBrowserWatchCliShortcutsHintMessage = (): string => {
+  return `  ${color.dim('press')} ${color.bold('q')} ${color.dim('to quit')}\n`;
+};
+
+export const logBrowserWatchReadyMessage = (
+  enableCliShortcuts: boolean,
+): void => {
+  logger.log(color.green('  Waiting for file changes...'));
+
+  if (enableCliShortcuts) {
+    logger.log(getBrowserWatchCliShortcutsHintMessage());
+  }
+};
+
+export async function setupBrowserWatchCliShortcuts({
+  close,
+}: {
+  close: () => Promise<void>;
+}): Promise<() => void> {
+  const { emitKeypressEvents } = await import('node:readline');
+
+  emitKeypressEvents(process.stdin);
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+
+  let isClosing = false;
+
+  const handleKeypress = (
+    str: string,
+    key: { name: string; ctrl: boolean },
+  ) => {
+    if (key.ctrl && key.name === 'c') {
+      process.kill(process.pid, 'SIGINT');
+      return;
+    }
+
+    if (key.ctrl && key.name === 'z') {
+      if (process.platform !== 'win32') {
+        process.kill(process.pid, 'SIGTSTP');
+      }
+      return;
+    }
+
+    if (str !== 'q' || isClosing) {
+      return;
+    }
+
+    // TODO: Support more browser watch shortcuts only after this path is
+    // refactored to share the same shortcut model as node mode.
+    isClosing = true;
+    void (async () => {
+      try {
+        await close();
+      } finally {
+        process.exit(0);
+      }
+    })();
+  };
+
+  process.stdin.on('keypress', handleKeypress);
+
+  return () => {
+    try {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+    } catch {}
+
+    process.stdin.off('keypress', handleKeypress);
+  };
+}

packages/browser/tests/watchCliShortcuts.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from '@rstest/core';
+import { getBrowserWatchCliShortcutsHintMessage } from '../src/watchCliShortcuts';
+
+const stripAnsi = (value: string): string => {
+  let result = '';
+  let index = 0;
+
+  while (index < value.length) {
+    if (value[index] === String.fromCharCode(27) && value[index + 1] === '[') {
+      index += 2;
+      while (index < value.length && value[index] !== 'm') {
+        index += 1;
+      }
+      index += 1;
+      continue;
+    }
+
+    result += value[index];
+    index += 1;
+  }
+
+  return result;
+};
+
+describe('browser watch cli shortcuts', () => {
+  it('should render the watch hint message', () => {
+    const message = stripAnsi(getBrowserWatchCliShortcutsHintMessage());
+
+    expect(message).toContain('press q to quit');
+    expect(message).not.toContain('press h to show help');
+  });
+});