@rstest/browser 0.11.5 → 0.11.6

package/dist/schedulerSeam.d.ts

@@ -0,0 +1,37 @@
+import type { ExecutorCycleOutcome } from '@rstest/core/internal/browser';
+import type { BrowserDispatchRequest } from './protocol.js';
+import type { BrowserProviderPage } from './providers/index.js';
+/**
+ * The contract between the controller and whichever run branch executes a run.
+ * It lives outside both so the schedulers never reach back into the controller
+ * for a type: the controller owns the run's shape, the schedulers own the run.
+ */ /**
+ * The watch-session control surface a watch-mode controller run hands back with
+ * its initial cycle. Every rerun trigger the host owns (dev rebuild, HMR, the
+ * in-page rerun button) resolves its own scope and then signals core's
+ * invalidation subscriber; core resets the cycle state and calls back into
+ * {@link BrowserWatchSession.runCycle} to execute it. A trigger that resolves to
+ * no work never signals, so a scope matching none of this host's files produces
+ * no cycle and no cycle output.
+ */ export type BrowserWatchSession = {
+    /** Execute the scope the last trigger resolved, as one cycle outcome. */ runCycle: (testPaths: string[]) => Promise<ExecutorCycleOutcome>;
+    /** Explicit path-scoped rerun request (a CLI shortcut's browser fanout). */ requestRerun: (testPaths?: string[]) => Promise<void>;
+};
+/**
+ * What a run branch produces. Results and errors accumulate in the sinks the
+ * controller owns, so a scheduler reports only what it alone knows: how long
+ * the tests took, the session it left behind, and how to tear down a runtime
+ * that does not outlive the run.
+ */ export type SchedulerRunResult = {
+    testTime: number;
+    watchSession?: BrowserWatchSession;
+    close?: () => Promise<void>;
+};
+/**
+ * How the shared dispatch layer reaches the pages of whichever run branch is
+ * live. Only the running branch knows its pages, so it installs the resolver
+ * and the dispatch layer stays branch-agnostic.
+ */ export type DispatchPageResolver = (target?: BrowserDispatchRequest['target']) => {
+    runnerPage?: BrowserProviderPage;
+    containerPage?: BrowserProviderPage;
+};

package/dist/watchRerunPlanner.d.ts

@@ -1,4 +1,9 @@
 import type { TestFileInfo } from './protocol.js';
+/**
+ * Paths the previous cycle ran that the current file set no longer contains.
+ * Core prunes its own state from this, so a file deleted mid-session stops
+ * being reported instead of lingering as a passing result.
+ */ export declare const collectDeletedTestPaths: (previous: TestFileInfo[], current: TestFileInfo[]) => string[];
 type WatchPlannerProjectEntry = {
     project: {
         name: string;

package/dist/watchRuntime.d.ts

@@ -0,0 +1,21 @@
+import { type BrowserRuntime } from './browserRsbuild.js';
+// Only process-wide concerns stay module-level: the runtime handle reused
+// across controller re-entry (config-change restarts), and the signal/exit
+// cleanup that must run once per process. Diff/rerun state lives on
+// `BrowserRuntime.watchState`.
+export type WatchContext = {
+    runtime: BrowserRuntime | null;
+    cleanupRegistered: boolean;
+    cleanupPromise: Promise<void> | null;
+};
+export declare const watchContext: WatchContext;
+/**
+ * Tear down the persistent watch runtime (dev servers, provider, browser,
+ * WebSocket server). Idempotent, and the single teardown the browser executor's
+ * `close` and the process-exit nets both go through.
+ */ export declare const runWatchRuntimeTeardown: <T>(state: {
+    runtime: T | null;
+    cleanupPromise: Promise<void> | null;
+}, destroy: (runtime: T) => Promise<void>) => Promise<void>;
+export declare const cleanupWatchRuntime: () => Promise<void>;
+export declare const registerWatchCleanup: (embedded: boolean) => void;

package/dist/watchSignals.d.ts

@@ -0,0 +1,22 @@
+import { type ExecutorInvalidationCallback } from '@rstest/core/internal/browser';
+/**
+ * The handover between this host's rerun triggers and core's watch-cycle
+ * driver. Triggers reach it from three unrelated places — the bundler's
+ * dev-compile hook, a CLI shortcut's fanout, the in-page rerun button — and
+ * only the ordering inside `signalInvalidation` keeps them from racing each
+ * other. Each run branch installs the pieces it owns; nothing here knows which
+ * branch is running.
+ */ export type WatchSignals = ReturnType<typeof createWatchSignals>;
+export declare const createWatchSignals: (onInvalidate: ExecutorInvalidationCallback | undefined) => {
+    setDispatchRerun(fn: () => Promise<void>): void;
+    runDispatchRerun(): Promise<void>;
+    setInterrupt(fn: () => Promise<void>): void;
+    signalInvalidation(fileFilters: string[], /**
+       * Run state this trigger binds to its own paths, taken in the same turn as
+       * the handover — after any interrupt, so no queued cycle can be dequeued in
+       * between and read it. The headed rerun's per-file test-name pattern is the
+       * one such state; core's cycle options cannot carry it, so the only thing
+       * that makes it the property of one cycle is claiming it here.
+       */ claimScope?: () => void): Promise<void>;
+    awaitSignalledCycle(): Promise<void>;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rstest/browser",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "description": "Browser mode support for Rstest testing framework.",
   "keywords": [
     "rstest",
@@ -55,14 +55,14 @@
     "@vitest/snapshot": "^4.1.10",
     "birpc": "^4.0.0",
     "picomatch": "^4.0.5",
-    "playwright": "^1.62.0",
+    "playwright": "^1.62.1",
     "@rstest/browser-ui": "0.0.0",
-    "@rstest/core": "0.11.5",
-    "@rstest/tsconfig": "0.0.1"
+    "@rstest/tsconfig": "0.0.1",
+    "@rstest/core": "0.11.6"
   },
   "peerDependencies": {
     "playwright": "^1.49.1",
-    "@rstest/core": "^0.11.5"
+    "@rstest/core": "0.11.6"
   },
   "peerDependenciesMeta": {
     "playwright": {

package/src/browserExecutor.ts

@@ -2,14 +2,19 @@ import {
   type BrowserTestExecutor,
   type BrowserTestRunResult,
   buildBrowserCoverageMap,
+  color,
   type CreateBrowserExecutorOptions,
   type ExecutorCycleOutcome,
+  type ExecutorInvalidationCallback,
   type ExecutorRunCycleOptions,
   type ListCommandResult,
+  logger,
   type RstestContext,
   type TestFileResult,
 } from '@rstest/core/internal/browser';
 import { listBrowserTests, runBrowserController } from './hostController';
+import type { BrowserWatchSession } from './schedulerSeam';
+import { cleanupWatchRuntime } from './watchRuntime';
 
 const emptyOutcome = (): ExecutorCycleOutcome => ({
   results: [],
@@ -22,12 +27,14 @@ const emptyOutcome = (): ExecutorCycleOutcome => ({
 /**
  * The browser side of the {@link TestExecutor} seam. It delegates into the
  * existing `hostController` in place (no file split this phase) and adapts the
- * host's `BrowserTestRunResult` into the shared `ExecutorCycleOutcome` — the
- * former `toBrowserOutcome` core adapter is folded in here and deleted.
+ * host's `BrowserTestRunResult` into the shared `ExecutorCycleOutcome`.
  *
- * Only used in non-watch runs (the shared executor loop); browser watch stays
- * host-driven and self-finalizing until Phase 6, so `runCycle` maps directly
- * onto one `runBrowserController` invocation and its coverage/close semantics.
+ * Watch and non-watch differ only in what one `runCycle` means. Non-watch: one
+ * `runBrowserController` invocation that returns a deferred `close`. Watch: the
+ * first cycle boots the persistent runtime and hands back a live
+ * {@link BrowserWatchSession}; every cycle after it is a rerun the host's own
+ * triggers signalled through `onInvalidate` and core scheduled. Either way core
+ * finalizes, so this adapter never touches reporters or the exit code.
  */
 export async function createBrowserExecutor(
   context: RstestContext,
@@ -42,12 +49,17 @@ export async function createBrowserExecutor(
     allowEmptyRun,
     appliedModifyRstestConfigEnvironments,
   } = options;
+  const isWatchMode = context.command === 'watch';
   let deferredClose: (() => Promise<void>) | undefined;
   // The host has no mid-launch abort, so `close()` must wait for an in-flight
   // cycle to settle before it can tear down — otherwise a close racing the
   // cycle (e.g. the signal-driven cleanup path) sees no `deferredClose` yet
   // and leaks the launching browser + servers.
   let inFlightCycle: Promise<unknown> | undefined;
+  // Registered before the first cycle: booting the runtime installs the watch
+  // triggers, and the first rebuild can signal as soon as it does.
+  let invalidationCallback: ExecutorInvalidationCallback | undefined;
+  let watchSession: BrowserWatchSession | undefined;
 
   // Merge the host's per-file `result.coverage` into one map (shared core
   // helper, stripping it from each result to avoid reporter/state cache
@@ -83,12 +95,47 @@ export async function createBrowserExecutor(
     async init(): Promise<void> {
       // Server/provider launch stays inside `runBrowserController` (delegate in
       // place). Kept as an explicit hook so the plan → init → runCycle barrier
-      // is honored structurally and Phase 5 can attach browser-side hook
-      // application here.
+      // holds structurally for both executors, and so browser-side work that
+      // must precede the first cycle has somewhere to go.
     },
     async runCycle(
       opts: ExecutorRunCycleOptions,
     ): Promise<ExecutorCycleOutcome> {
+      if (watchSession) {
+        // A watch rerun: the host's trigger already resolved the scope and
+        // handed it over as the invalidation hint, which core passes back here.
+        //
+        // `opts.updateSnapshot` is dropped, and that is a gap rather than a
+        // choice. Core resolves it per trigger so a cycle no `u` selected files
+        // for cannot rewrite their snapshots; the host instead re-reads the live
+        // `snapshotManager` flag for every page it loads, so a browser cycle
+        // queued inside the `u` hold window still runs under `'all'`. Closing it
+        // means plumbing this option through `watchSession.runCycle` to the
+        // per-page config, which is also what would make the seam doc on
+        // `ExecutorRunCycleOptions.updateSnapshot` true on this side.
+        //
+        // Whichever shape that takes has to settle a fold hazard first. Trigger
+        // kind is erased on this side of the seam: a `u` press reaches the host
+        // as `requestRerun`, routes through `dispatchRerun`/`signalInvalidation`
+        // like any rebuild, and arrives back at the driver as
+        // `trigger: 'invalidation'` with the same options — so `canFold` already
+        // unions the two, and only the drop above keeps that from mattering.
+        // Exactly one of two things must therefore be true once the option is
+        // honored: the originating trigger crosses the seam and becomes part of
+        // the fold identity, or `updateSnapshot` rides the per-cycle options the
+        // fold predicate already compares (`'all'` then differs from the session
+        // value, so the two cycles cannot fold). Sending the flag out of band —
+        // straight to the host, driver-side options unchanged — is the one shape
+        // that folds a rebuild's files into the `u` scope.
+        const cycle = watchSession.runCycle(opts.fileFilters ?? []);
+        inFlightCycle = cycle;
+        try {
+          return await cycle;
+        } finally {
+          inFlightCycle = undefined;
+        }
+      }
+
       const cycle = runBrowserController(context, {
         projects,
         shardedEntries,
@@ -98,6 +145,9 @@ export async function createBrowserExecutor(
         onTraceEvents: opts.onTraceEvents,
         env: opts.env,
         updateSnapshot: opts.updateSnapshot,
+        onInvalidate: isWatchMode
+          ? (hint) => invalidationCallback?.(hint)
+          : undefined,
       });
       inFlightCycle = cycle;
       try {
@@ -105,18 +155,43 @@ export async function createBrowserExecutor(
         // Non-watch runs return a deferred `close`; collapse teardown into the
         // shared `executors.close()` exit path.
         deferredClose = result?.close;
+        watchSession = result?.watchSession;
         return foldOutcome(result);
       } finally {
         inFlightCycle = undefined;
       }
     },
-    async collect(): Promise<{ list: ListCommandResult[] }> {
+    onInvalidate(cb: ExecutorInvalidationCallback): void {
+      invalidationCallback = cb;
+    },
+    hasWatchSession(): boolean {
+      return watchSession !== undefined;
+    },
+    async requestRerun(testPaths?: string[]): Promise<void> {
+      if (!watchSession) {
+        // Core gates rerun keys until every executor is past its first cycle, so
+        // reaching here means no session will ever open: the launch found no test
+        // files or failed outright, and reported that itself. The keys stay
+        // installed either way — a mixed run's node side keeps watching, and even
+        // a browser-only run outlives a launch that opened nothing — so resolving
+        // in silence would let the shortcut claim a rerun that never happened.
+        logger.log(
+          color.yellow(
+            '\nBrowser Mode has no live watch session, so this rerun skipped it.',
+          ),
+        );
+        return;
+      }
+      await watchSession.requestRerun(testPaths);
+    },
+    async collect(opts): Promise<{ list: ListCommandResult[] }> {
       const pending = listBrowserTests(context, {
         projects,
         shardedEntries,
         freezeShardedEntries,
         filesOnly,
         appliedModifyRstestConfigEnvironments,
+        env: opts.env,
       });
       inFlightCycle = pending;
       try {
@@ -132,6 +207,13 @@ export async function createBrowserExecutor(
         // A rejected cycle cleans up host-side; settling is all that's needed.
         await inFlightCycle.catch(() => undefined);
       }
+      if (isWatchMode) {
+        // The watch runtime spans every cycle, so it is not a per-cycle
+        // deferred close — the executor is its owner.
+        watchSession = undefined;
+        await cleanupWatchRuntime();
+        return;
+      }
       const close = deferredClose;
       deferredClose = undefined;
       await close?.();