@rstest/browser 0.11.1 → 0.11.2

package/dist/protocol.d.ts

@@ -1,5 +1,5 @@
 import type { BrowserViewport } from '@rstest/core/internal/browser';
-import type { RuntimeConfig, TestFileResult, TestInfo, TestResult } from '@rstest/core/internal/browser-runtime';
+import type { BrowserRuntimeConfig, TestFileResult, TestInfo, TestResult } from '@rstest/core/internal/browser-runtime';
 import type { SnapshotUpdateState } from '@vitest/snapshot';
 export type { BrowserLocatorIR, BrowserRpcRequest, SnapshotRpcCall, SnapshotRpcMethod, SnapshotRpcMethodArgs, SnapshotRpcRequest } from './rpcProtocol.js';
 export { validateBrowserRpcRequest } from './rpcProtocol.js';
@@ -12,7 +12,7 @@ export declare const DISPATCH_NAMESPACE_RUNNER = 'runner';
 export declare const DISPATCH_NAMESPACE_BROWSER = 'browser';
 export declare const DISPATCH_NAMESPACE_SNAPSHOT = 'snapshot';
 export declare const DISPATCH_METHOD_RPC = 'rpc';
-export type SerializedRuntimeConfig = RuntimeConfig;
+export type SerializedRuntimeConfig = BrowserRuntimeConfig;
 // `BrowserViewport` is a core config type (`@rstest/core` owns the canonical
 // definition used by `NormalizedBrowserModeConfig`). Re-export it so the host
 // assigns the SAME type across the seam instead of a hand-copied duplicate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rstest/browser",
-  "version": "0.11.1",
+  "version": "0.11.2",
   "description": "Browser mode support for Rstest testing framework.",
   "keywords": [
     "rstest",
@@ -52,17 +52,17 @@
     "@types/convert-source-map": "^2.0.3",
     "@types/picomatch": "^4.0.3",
     "@types/ws": "^8.18.1",
-    "@vitest/snapshot": "^3.2.6",
+    "@vitest/snapshot": "^3.2.7",
     "birpc": "^4.0.0",
     "picomatch": "^4.0.5",
     "playwright": "^1.61.1",
-    "@rstest/core": "0.11.1",
+    "@rstest/core": "0.11.2",
     "@rstest/tsconfig": "0.0.1",
     "@rstest/browser-ui": "0.0.0"
   },
   "peerDependencies": {
     "playwright": "^1.49.1",
-    "@rstest/core": "^0.11.1"
+    "@rstest/core": "^0.11.2"
   },
   "peerDependenciesMeta": {
     "playwright": {

package/src/AGENTS.md

@@ -2,15 +2,28 @@
 
 This document is architecture-only and focuses on browser mode scheduling in `@rstest/browser` host-side modules.
 
+## Run lifecycle ownership (browser/node isomorphism)
+
+`runBrowserController` splits finalize ownership on `context.command`:
+
+- **Non-watch runs**: the host never self-finalizes. It returns a fully-populated `BrowserTestRunResult` with a deferred `close`, and `@rstest/core`'s `finalizeRunCycle` reduces the run's `ExecutorCycleOutcome`s into the verdict — reporter `onTestRunEnd`, coverage merge + report, exit code, and the bail message. `BrowserTestRunOptions.skipOnTestRunEnd` (deprecated and ignored since the finalize unification) has been removed.
+- **Watch runs**: the host owns the per-rerun lifecycle (`onTestRunStart`/`onTestRunEnd` per rerun) and self-finalizes; core skips its finalize entirely for browser-only and zero-node mixed watch runs.
+
+Runner lifecycle events flow through per-project `RunnerEventSink`s (`createRunnerEventSink` from core — the same event pump the node pool RPC uses). The host keeps a `Map<projectName, RunnerEventSink>` and resolves sinks via `sinkForProjectName`/`sinkForTestPath` (falling back to the first project for unknown names); it never fans out to reporters or `stateManager` directly.
+
+Cross-file `bail` is enforced at file boundaries in the headless scheduler: before picking up the next file, each worker checks the cycle-wide `stateManager.getCountOfFailedTests()` and drains the remaining queue as skipped results once the budget is reached. The headed debugging UI does not apply bail; within a running file, the runner's per-test gate uses the client-local failed count (see `src/client/AGENTS.md`).
+
 ## Module topology
 
 ```mermaid
 flowchart LR
   subgraph Host["@rstest/browser host (Node.js)"]
     IDX["index.ts\nrunBrowserTests()"]
+    CV["configValidation.ts\nvalidateBrowserConfig()"]
     HC["hostController.ts\nrunBrowserController()"]
     RT["createBrowserRuntime()"]
     DR["dispatchCapabilities.ts + dispatchRouter.ts\nnamespace router"]
+    BRR["browserRpcRegistry.ts\nBrowser RPC allowlists"]
     RL["runSession.ts\nRunSessionLifecycle"]
     SR["sessionRegistry.ts\nRunnerSessionRegistry"]
     WP["watchRerunPlanner.ts"]
@@ -31,9 +44,11 @@ flowchart LR
     RPC["dispatch-rpc-request"]
   end
 
+  IDX -."re-export; invoked by @rstest/core before the run".-> CV
   IDX --> HC
   HC --> RT
   HC --> DR
+  DR --> BRR
   HC --> WP
   WP --> LS
   HC --> RL
@@ -81,6 +96,7 @@ sequenceDiagram
 
   Runner->>Container: postMessage runner lifecycle
   Container->>Host: forward lifecycle callbacks (onTest*)
+  Host->>Host: feed per-project RunnerEventSink (stateManager + reporters)
 
   Runner->>Container: postMessage dispatch rpc request
   Container->>Host: rpc.dispatch(request)
@@ -121,7 +137,7 @@ sequenceDiagram
   participant Handler as namespace handler
 
   Runner->>Host: __rstest_dispatch__ lifecycle
-  Host->>Host: forward lifecycle callbacks
+  Host->>Host: feed per-project RunnerEventSink (stateManager + reporters)
 
   Runner->>Host: __rstest_dispatch_rpc__ request
   Host->>Router: routing inbound request

package/src/browserExecutor.ts

@@ -0,0 +1,138 @@
+import {
+  type BrowserTestExecutor,
+  type BrowserTestRunResult,
+  buildBrowserCoverageMap,
+  type CreateBrowserExecutorOptions,
+  type ExecutorCycleOutcome,
+  type ExecutorRunCycleOptions,
+  type ListCommandResult,
+  type RstestContext,
+  type TestFileResult,
+} from '@rstest/core/internal/browser';
+import { listBrowserTests, runBrowserController } from './hostController';
+
+const emptyOutcome = (): ExecutorCycleOutcome => ({
+  results: [],
+  testResults: [],
+  errors: [],
+  testPaths: [],
+  duration: { buildTime: 0, testTime: 0 },
+});
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+export async function createBrowserExecutor(
+  context: RstestContext,
+  options: CreateBrowserExecutorOptions,
+): Promise<BrowserTestExecutor> {
+  const {
+    projects,
+    coverageProvider,
+    freezeShardedEntries,
+    filesOnly,
+    allowEmptyRun,
+    appliedModifyRstestConfigEnvironments,
+  } = options;
+  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;
+
+  // Merge the host's per-file `result.coverage` into one map (shared core
+  // helper, stripping it from each result to avoid reporter/state cache
+  // bloat), then hand the shared finalize a coverage `map` (no `raw` — browser
+  // coverage is istanbul-only).
+  const foldOutcome = (
+    result: BrowserTestRunResult | void,
+  ): ExecutorCycleOutcome => {
+    if (!result) {
+      return emptyOutcome();
+    }
+    const map = buildBrowserCoverageMap(
+      result.results as TestFileResult[],
+      coverageProvider,
+    );
+    return {
+      results: result.results,
+      testResults: result.testResults,
+      errors: result.unhandledErrors ?? [],
+      testPaths: result.results.map((r) => r.testPath),
+      duration: {
+        buildTime: result.duration.buildTime,
+        testTime: result.duration.testTime,
+      },
+      coverage: { map: map?.toJSON() },
+      resolveSourcemap: result.resolveSourcemap,
+    };
+  };
+
+  return {
+    name: 'browser',
+    projects,
+    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.
+    },
+    async runCycle(
+      opts: ExecutorRunCycleOptions,
+    ): Promise<ExecutorCycleOutcome> {
+      const cycle = runBrowserController(context, {
+        projects,
+        shardedEntries: opts.shardedEntries,
+        freezeShardedEntries,
+        allowEmptyRun,
+        appliedModifyRstestConfigEnvironments,
+        onTraceEvents: opts.onTraceEvents,
+        env: opts.env,
+      });
+      inFlightCycle = cycle;
+      try {
+        const result = await cycle;
+        // Non-watch runs return a deferred `close`; collapse teardown into the
+        // shared `executors.close()` exit path.
+        deferredClose = result?.close;
+        return foldOutcome(result);
+      } finally {
+        inFlightCycle = undefined;
+      }
+    },
+    async collect(opts): Promise<{ list: ListCommandResult[] }> {
+      const pending = listBrowserTests(context, {
+        projects,
+        shardedEntries: opts.shardedEntries,
+        freezeShardedEntries,
+        filesOnly,
+        appliedModifyRstestConfigEnvironments,
+      });
+      inFlightCycle = pending;
+      try {
+        const { list, close } = await pending;
+        deferredClose = close;
+        return { list };
+      } finally {
+        inFlightCycle = undefined;
+      }
+    },
+    async close(): Promise<void> {
+      if (inFlightCycle) {
+        // A rejected cycle cleans up host-side; settling is all that's needed.
+        await inFlightCycle.catch(() => undefined);
+      }
+      const close = deferredClose;
+      deferredClose = undefined;
+      await close?.();
+    },
+  };
+}

package/src/client/AGENTS.md

@@ -34,13 +34,13 @@ flowchart LR
   subgraph IframePath["Iframe path (headed)"]
     S1["send()"] --> P1["parent.postMessage(__rstest_dispatch__)"]
     R1["dispatchRunnerLifecycle()"] --> P2["postMessage dispatch-rpc-request"]
-    SN1["snapshot.sendRpcRequest()"] --> P3["postMessage dispatch-rpc-request + wait __rstest_dispatch_response__"]
+    SN1["snapshot.ts / browserRpc.ts via dispatchTransport.dispatchRpc()"] --> P3["postMessage dispatch-rpc-request + wait __rstest_dispatch_response__"]
   end
 
   subgraph TopLevelRunPath["Top-level page path (headless run)"]
     S2["send()"] --> D1["window.__rstest_dispatch__"]
     R2["dispatchRunnerLifecycle()"] --> D2["window.__rstest_dispatch_rpc__"]
-    SN2["snapshot.sendRpcRequest()"] --> D3["window.__rstest_dispatch_rpc__"]
+    SN2["snapshot.ts / browserRpc.ts via dispatchTransport.dispatchRpc()"] --> D3["window.__rstest_dispatch_rpc__"]
   end
 
   subgraph TopLevelCollectPath["Top-level page path (list collect)"]
@@ -48,31 +48,36 @@ flowchart LR
   end
 ```
 
-## Snapshot RPC sequence
+## Dispatch RPC sequence (snapshot / browser namespaces)
+
+The `snapshot` namespace (snapshot file ops) and the `browser` namespace
+(locator/page RPC from `browserRpc.ts`) share one client channel:
+`dispatchTransport.ts` owns request ids, timeouts, and pending-response
+resolution for both the iframe and top-level transports.
 
 ```mermaid
 sequenceDiagram
-  participant Snap as snapshot.ts
-  participant Runner as entry.ts runtime
+  participant Caller as snapshot.ts / browserRpc.ts
+  participant Transport as dispatchTransport.ts
   participant Container as browser-ui channel
   participant Host as host dispatch router
 
-  Snap->>Runner: sendRpcRequest(method, args)
+  Caller->>Transport: dispatchRpc(request)
 
   alt top-level runner (headless run)
-    Runner->>Host: __rstest_dispatch_rpc__(namespace=snapshot)
-    Host-->>Runner: BrowserDispatchResponse
-    Runner-->>Snap: result/error
+    Transport->>Host: __rstest_dispatch_rpc__(namespace=snapshot|browser)
+    Host-->>Transport: BrowserDispatchResponse
+    Transport-->>Caller: result/error
   else iframe runner (headed)
-    Runner->>Container: postMessage(dispatch-rpc-request)
+    Transport->>Container: postMessage(dispatch-rpc-request)
     Container->>Host: rpc.dispatch(request)
     Host-->>Container: BrowserDispatchResponse
-    Container-->>Runner: __rstest_dispatch_response__
-    Runner-->>Snap: resolve/reject pending request
+    Container-->>Transport: __rstest_dispatch_response__
+    Transport-->>Caller: resolve/reject pending request
   end
 ```
 
-List collect mode does not use the snapshot RPC namespace.
+List collect mode does not use the snapshot or browser RPC namespaces.
 
 ## Runtime invariants
 
@@ -80,3 +85,5 @@ List collect mode does not use the snapshot RPC namespace.
 - Runner lifecycle events (`file-ready`, `suite-start`, `suite-result`, `case-start`) go through the `runner` dispatch namespace.
 - Snapshot file operations go through the `snapshot` dispatch namespace and never access filesystem directly in browser runtime.
 - Console interception is per test file and must restore original console methods in `finally`.
+- An unhandled window error or `unhandledrejection` that escapes a test file fails the file even when every test passed. Before finalizing each file result, the runner yields two macrotasks so a rejection leaked by a synchronous test is still observed (the browser dispatches `unhandledrejection` in a task queued after the current task).
+- The `getCountOfFailedTests` runner hook returns the client-local per-file failed count; cross-file `bail` is enforced host-side at file boundaries (see `../AGENTS.md`), not by this hook.

package/src/client/entry.ts

@@ -67,14 +67,19 @@ type GlobalWithRuntimeEnv = typeof globalThis &
 const restoreRuntimeConfig = (
   config: BrowserProjectRuntime['runtimeConfig'],
 ): RuntimeConfig => {
-  const { testNamePattern } = config as RuntimeConfig;
+  const { testNamePattern } = config;
+  // The browser wire (BrowserRuntimeConfig) omits node-only fields
+  // (testEnvironment / coverage / logHeapUsage / detectAsyncLeaks) that the
+  // browser runtime never reads. The shared WorkerState / runner types require
+  // the full RuntimeConfig shape and runner heap sampling is guarded against
+  // the absent logHeapUsage, so widening back here is sound.
   return {
     ...config,
     testNamePattern:
       typeof testNamePattern === 'string'
         ? unwrapRegex(testNamePattern)
         : testNamePattern,
-  };
+  } as RuntimeConfig;
 };
 
 const ensureRuntimeEnv = (env: RuntimeConfig['env'] | undefined): void => {
@@ -542,6 +547,28 @@ const run = async () => {
     return;
   }
 
+  // Capture unhandled errors/rejections that escape a test file's execution.
+  // Parity with the node worker, which attaches process-level
+  // uncaughtException/unhandledRejection to the running file's result and fails
+  // the file. `activeUnhandledErrors` points at the currently running file's
+  // collector (undefined between files, so stray late events are ignored).
+  let activeUnhandledErrors: Error[] | undefined;
+  const onWindowError = (event: ErrorEvent): void => {
+    activeUnhandledErrors?.push(
+      event.error instanceof Error
+        ? event.error
+        : new Error(event.message || String(event.error)),
+    );
+  };
+  const onUnhandledRejection = (event: PromiseRejectionEvent): void => {
+    const { reason } = event;
+    activeUnhandledErrors?.push(
+      reason instanceof Error ? reason : new Error(String(reason)),
+    );
+  };
+  window.addEventListener('error', onWindowError);
+  window.addEventListener('unhandledrejection', onUnhandledRejection);
+
   // 2. Run tests for each file
   for (const key of testKeysToRun) {
     const testPath = toAbsolutePath(key, currentProject.projectRoot);
@@ -669,6 +696,9 @@ const run = async () => {
       },
     });
 
+    const unhandledErrors: Error[] = [];
+    activeUnhandledErrors = unhandledErrors;
+
     try {
       // Load setup files for this project after runtime is ready.
       await loadSetupFiles();
@@ -692,6 +722,32 @@ const run = async () => {
         runtime.api,
       );
 
+      // The browser dispatches `unhandledrejection` in a task queued at the
+      // current task's microtask checkpoint, so a rejection leaked by a
+      // synchronous test is not observable yet when `runTests()` resolves.
+      // Yield two macrotasks: the first reaches the checkpoint that queues
+      // the event task, the second runs after that task regardless of how
+      // the browser orders the timer and event task sources.
+      for (let i = 0; i < 2; i++) {
+        await new Promise<void>((resolve) => {
+          setTimeout(resolve, 0);
+        });
+      }
+
+      // An unhandled error/rejection that escaped the run fails the file even
+      // when every test passed.
+      if (unhandledErrors.length > 0) {
+        result.status = 'fail';
+        result.errors = [
+          ...(result.errors ?? []),
+          ...unhandledErrors.map((error) => ({
+            name: error.name,
+            message: error.message,
+            stack: error.stack,
+          })),
+        ];
+      }
+
       // Collect coverage data from global __coverage__ object
       if (globalThis.__coverage__) {
         result.coverage = globalThis.__coverage__ as CoverageMapData;
@@ -716,9 +772,13 @@ const run = async () => {
     } finally {
       // Restore original console methods
       restoreConsole();
+      activeUnhandledErrors = undefined;
     }
   }
 
+  window.removeEventListener('error', onWindowError);
+  window.removeEventListener('unhandledrejection', onUnhandledRejection);
+
   send({ type: 'complete' });
   window.__RSTEST_DONE__ = true;
 };

package/src/client/snapshot.ts

@@ -5,10 +5,9 @@ import {
   dispatchRpc,
   getRpcTimeout,
 } from './dispatchTransport';
+import { SNAPSHOT_HEADER } from '@rstest/core/internal/browser-runtime';
 import { mapStackFrame } from './sourceMapSupport';
 
-const SNAPSHOT_HEADER = '// Rstest Snapshot';
-
 const createSnapshotDispatchRequest = (
   requestId: string,
   call: SnapshotRpcCall,

package/src/concurrency.ts

@@ -1,12 +1,17 @@
-import { getNumCpus, parseWorkers } from '@rstest/core/internal/browser';
+import {
+  getNumCpus,
+  parseWorkers,
+  resolveWorkerCount,
+} from '@rstest/core/internal/browser';
 import type { Rstest } from '@rstest/core/internal/browser';
 
 // Re-export the shared worker primitives so existing consumers (and unit tests
 // importing from `../src/concurrency`) keep a stable import surface.
 export { getNumCpus, parseWorkers };
 
-// Shared headless concurrency policy.
-// Keep this in one place so executors reuse the same worker semantics.
+// The browser headless path caps CPU-derived workers at 12 and halves that
+// capped base in watch; the shared `resolveWorkerCount` helper owns the
+// `maxWorkers` override and workload clamp.
 const DEFAULT_MAX_HEADLESS_WORKERS = 12;
 
 type HeadlessConcurrencyContext = Pick<Rstest, 'command'> & {
@@ -17,32 +22,44 @@ type HeadlessConcurrencyContext = Pick<Rstest, 'command'> & {
   };
 };
 
+const resolveHeadlessWorkerCount = ({
+  command,
+  maxWorkers,
+  totalTasks,
+  numCpus = getNumCpus(),
+}: {
+  command: HeadlessConcurrencyContext['command'];
+  maxWorkers?: string | number;
+  totalTasks: number;
+  numCpus?: number;
+}): number => {
+  const base = Math.max(Math.min(DEFAULT_MAX_HEADLESS_WORKERS, numCpus - 1), 1);
+  return resolveWorkerCount({
+    command,
+    maxWorkers,
+    totalTasks,
+    recommended: base,
+    watchRecommended: Math.max(Math.floor(base / 2), 1),
+    numCpus,
+  });
+};
+
 export const resolveDefaultHeadlessWorkers = (
   command: HeadlessConcurrencyContext['command'],
   numCpus: number = getNumCpus(),
-): number => {
-  const baseWorkers = Math.max(
-    Math.min(DEFAULT_MAX_HEADLESS_WORKERS, numCpus - 1),
-    1,
-  );
-
-  return command === 'watch'
-    ? Math.max(Math.floor(baseWorkers / 2), 1)
-    : baseWorkers;
-};
+): number =>
+  resolveHeadlessWorkerCount({
+    command,
+    totalTasks: Number.POSITIVE_INFINITY,
+    numCpus,
+  });
 
 export const getHeadlessConcurrency = (
   context: HeadlessConcurrencyContext,
   totalTests: number,
-): number => {
-  if (totalTests <= 0) {
-    return 1;
-  }
-
-  const maxWorkers = context.normalizedConfig.pool.maxWorkers;
-  if (maxWorkers !== undefined) {
-    return Math.min(parseWorkers(maxWorkers), totalTests);
-  }
-
-  return Math.min(resolveDefaultHeadlessWorkers(context.command), totalTests);
-};
+): number =>
+  resolveHeadlessWorkerCount({
+    command: context.command,
+    maxWorkers: context.normalizedConfig.pool.maxWorkers,
+    totalTasks: totalTests,
+  });