@rstest/browser 0.11.6 → 0.11.8

package/dist/containerRpc.d.ts

@@ -1,24 +1,30 @@
-import { type TestResult } from '@rstest/core/internal/browser';
 import { type BirpcReturn } from 'birpc';
 import { type WebSocket, WebSocketServer } from 'ws';
-import type { BrowserDispatchRequest, BrowserDispatchResponse, BrowserHostConfig, TestFileInfo } from './protocol.js';
-import type { FatalPayload, HeadedTestFileCompletePayload, LogPayload, ReloadTestFileAck, TestFileStartPayload } from './hostPayloads.js';
-/** RPC methods exposed by the host (server) to the container (client) */ export type HostRpcMethods = {
+import type { BrowserDispatchRequest, BrowserDispatchResponse, BrowserHostConfig, TestFileInfo, VersionedTestFileSet } from './protocol.js';
+/**
+ * RPC methods exposed by the host (server) to the container (client).
+ * Runner lifecycle events (file-start, case-result, file-complete, log,
+ * fatal, ...) do NOT get dedicated methods: the container relays every runner
+ * message as a `dispatch` request on the `runner` namespace, stamped with the
+ * envelope's run identity, so the host has exactly one inbound gate.
+ */ export type HostRpcMethods = {
     rerunTest: (testFile: string, testNamePattern?: string) => Promise<void>;
-    getTestFiles: () => Promise<TestFileInfo[]>;
-    onRunnerFramesReady: (testFiles: string[]) => Promise<void>;
-    // Test result callbacks from container
-    onTestFileStart: (payload: TestFileStartPayload) => Promise<void>;
-    onTestCaseResult: (payload: TestResult) => Promise<void>;
-    onTestFileComplete: (payload: HeadedTestFileCompletePayload) => Promise<void>;
-    onLog: (payload: LogPayload) => Promise<void>;
-    onFatal: (payload: FatalPayload) => Promise<void>;
-    // Generic dispatch endpoint used by runner RPC requests.
+    getTestFiles: () => Promise<VersionedTestFileSet>;
+    /**
+   * The container committed the frame set for this version — every iframe for
+   * the set exists in the DOM. Versions are monotonic, so a stale ack can
+   * never satisfy a newer wait (a content signature could ABA back to a
+   * previously-acked value; a counter cannot).
+   */ onFrameSetReady: (version: number) => Promise<void>;
     dispatch: (request: BrowserDispatchRequest) => Promise<BrowserDispatchResponse>;
 };
 /** RPC methods exposed by the container (client) to the host (server) */ export type ContainerRpcMethods = {
-    onTestFileUpdate: (testFiles: TestFileInfo[]) => Promise<void>;
-    reloadTestFile: (testFile: string, testNamePattern?: string) => Promise<ReloadTestFileAck>;
+    onTestFileUpdate: (testFiles: TestFileInfo[], version: number) => Promise<void>;
+    /**
+   * Grant `runId` (host-minted, already registered host-side) to this file's
+   * frame and navigate it. Identity travels IN — the container never mints or
+   * echoes identity back.
+   */ reloadTestFile: (testFile: string, runId: string, testNamePattern?: string) => Promise<void>;
     /**
    * Replace the container's copy of the host config so runner iframes loaded
    * from now on receive fresh values (e.g. the 'u' shortcut flipping
@@ -38,15 +44,17 @@ export type ContainerRpc = BirpcReturn<ContainerRpcMethods, HostRpcMethods>;
     private rpc;
     private methods;
     private onDisconnect?;
+    private onAttach?;
     private detachActiveSocketListeners;
-    constructor(wss: WebSocketServer, methods: HostRpcMethods, onDisconnect?: (error: Error) => void);
-    /** Update the RPC methods (used when starting a new test run) */ updateMethods(methods: HostRpcMethods, onDisconnect?: (error: Error) => void): void;
+    private transportEpoch;
+    constructor(wss: WebSocketServer, methods: HostRpcMethods, onDisconnect?: (error: Error) => void, onAttach?: (transportEpoch: number) => void);
+    /** Update the RPC methods (used when starting a new test run) */ updateMethods(methods: HostRpcMethods, onDisconnect?: (error: Error) => void, onAttach?: (transportEpoch: number) => void): void;
     private setupConnectionHandler;
     private attachWebSocket;
     /** Check if a container is currently connected */ get isConnected(): boolean;
     /** Get the current WebSocket instance (for reuse in watch mode) */ get currentWebSocket(): WebSocket | null;
     /** Reattach an existing WebSocket (for watch mode reuse) */ reattach(ws: WebSocket): void;
-    /** Notify container of test file changes */ notifyTestFileUpdate(files: TestFileInfo[]): Promise<void>;
+    /** Notify container of test file changes */ notifyTestFileUpdate(files: TestFileInfo[], version: number): Promise<void>;
     /** Push a refreshed host config to the container (watch reruns) */ updateHostConfig(config: BrowserHostConfig): Promise<void>;
-    /** Request container to reload a specific test file */ reloadTestFile(testFile: string, testNamePattern?: string): Promise<ReloadTestFileAck>;
+    /** Grant a run to a test file's frame and navigate it */ reloadTestFile(testFile: string, runId: string, testNamePattern?: string): Promise<void>;
 }

package/dist/headedRunRegistry.d.ts

@@ -0,0 +1,51 @@
+export type HeadedRunRegistry = ReturnType<typeof createHeadedRunRegistry>;
+export declare const createHeadedRunRegistry: () => {
+    /**
+     * Allocate a run and own its deferred, synchronously — the caller sends
+     * the reload RPC only after this returns, so no file-set commit or
+     * inbound message can land between "the run exists" and "the table knows
+     * it" (the ack-window class of race cannot be constructed).
+     */ mint(testPath: string): {
+        runId: string;
+        settled: Promise<void>;
+    };
+    /**
+     * The one liveness question, asked once per inbound message: may this
+     * identity be processed? Any answer of `true` also proves the run's
+     * document booted, which disarms the boot deadline.
+     *
+     * `terminal` marks a message that ends the run ("file-complete" /
+     * "fatal"). It claims settlement for the caller's handler and must be
+     * asked synchronously, before the handler's first await, so a file-set
+     * commit racing the handler cannot settle the run a second time. A second
+     * terminal for the same run is answered `false` — it is a duplicate.
+     */ admit(runId: string, terminal: boolean): boolean;
+    /**
+     * A run whose fixture cleanup never finishes will never send its
+     * terminal message — a way to go silent that no other deadline covers,
+     * so it is a settlement obligation and lives here: the deadline dies
+     * with the record in the one guarded delete, which is what makes "run
+     * settled elsewhere, timer fires anyway" unrepresentable. Expiry fires
+     * only while the run is still open and CLAIMS it in the same synchronous
+     * step, exactly like a terminal message's admit: `onExpire`'s handler
+     * now owns the settlement, and the recovery it performs (tearing down
+     * the container transport) can no longer sweep this run out from under
+     * itself. Re-arming replaces the previous deadline.
+     */ armCleanupDeadline(runId: string, ms: number, onExpire: () => void): void;
+    disarmCleanupDeadline(runId: string): void;
+    resolve(runId: string): void;
+    reject(runId: string, error: unknown): void;
+    /**
+     * The file-set commit's settlement obligation: close every open run whose
+     * path left the committed set — the container is about to unmount those
+     * frames, so their completions can never arrive (and if one is already in
+     * transport, its runId is gone from the table and drops by rule).
+     */ retainPaths(paths: readonly string[]): void;
+    /** Transport death: no completion can arrive for any open run. */ rejectAll(error: Error): void;
+    /**
+     * A new transport attachment orphans every run leased under the previous
+     * one, even when the old socket never fired `close` (its listeners are
+     * detached before the event can). Runs minted from now on carry the new
+     * epoch.
+     */ setTransportEpoch(epoch: number): void;
+};

package/dist/headedScheduler.d.ts

@@ -1,10 +1,9 @@
-import type { RstestContext, TestFileResult, TestResult } from '@rstest/core/internal/browser';
+import type { RstestContext, TestFileResult } from '@rstest/core/internal/browser';
 import { type BrowserRuntime } from './browserRsbuild.js';
 import type { HostDispatchRouter } from './dispatchRouter.js';
-import { type FatalPayload, type LogPayload, type TestFileStartPayload } from './hostPayloads.js';
 import type { BrowserHostConfig, TestFileInfo } from './protocol.js';
 import { planWatchRerun } from './watchRerunPlanner.js';
-import type { BrowserWatchSession, DispatchPageResolver, SchedulerRunResult } from './schedulerSeam.js';
+import type { BrowserV8CoverageRuntime, BrowserWatchSession, DispatchPageResolver, SchedulerRunResult } from './schedulerSeam.js';
 import type { WatchSignals } from './watchSignals.js';
 type HeadedSchedulerContext = Pick<RstestContext, 'rootPath' | 'snapshotManager' | 'updateReporterResultState'> & {
     normalizedConfig: Pick<RstestContext['normalizedConfig'], 'name'>;
@@ -14,21 +13,22 @@ type HeadedSchedulerDeps = {
     runtime: BrowserRuntime;
     allTestFiles: TestFileInfo[];
     hostOptions: BrowserHostConfig;
+    v8Coverage?: BrowserV8CoverageRuntime;
+    projectRoots: Map<string, string>;
     isWatchMode: boolean;
     createDispatchRouter: () => HostDispatchRouter;
     handlers: {
-        handleTestFileStart: (payload: TestFileStartPayload) => Promise<void>;
-        handleTestCaseResult: (payload: TestResult) => Promise<void>;
+        // For the one result the host authors itself (the cleanup-timeout
+        // failure); every runner-authored result flows through the dispatch
+        // router instead.
         handleTestFileComplete: (payload: TestFileResult) => Promise<void>;
-        handleLog: (payload: LogPayload) => Promise<void>;
-        handleFatal: (payload: FatalPayload) => Promise<void>;
     };
     fatalErrorRef: {
         current: Error | null;
     };
-    watchSignals: Pick<WatchSignals, 'setDispatchRerun' | 'signalInvalidation' | 'awaitSignalledCycle'>;
+    watchSignals: Pick<WatchSignals, 'setDispatchRerun' | 'signalInvalidation'>;
     setDispatchPageResolver: (resolver: DispatchPageResolver) => void;
-    createWatchSession: (execute: (testPaths: string[]) => Promise<void>) => BrowserWatchSession;
+    createWatchSession: (execute: (testPaths: string[]) => Promise<unknown[]>) => BrowserWatchSession;
     collectProjectEntries: () => Promise<Parameters<typeof planWatchRerun>[0]['projectEntries']>;
     logWatchReady: () => void;
     destroyRuntime: () => Promise<void>;
@@ -54,5 +54,5 @@ type HeadedSchedulerDeps = {
     file: TestFileInfo;
     testNamePattern?: string;
 }[];
-export declare const createHeadedScheduler: ({ context, runtime, allTestFiles, hostOptions, isWatchMode, createDispatchRouter, handlers: { handleTestFileStart, handleTestCaseResult, handleTestFileComplete, handleLog, handleFatal }, fatalErrorRef, watchSignals, setDispatchPageResolver, createWatchSession, collectProjectEntries, logWatchReady, destroyRuntime }: HeadedSchedulerDeps) => Promise<SchedulerRunResult>;
+export declare const createHeadedScheduler: ({ context, runtime, allTestFiles, hostOptions, v8Coverage, projectRoots, isWatchMode, createDispatchRouter, handlers: { handleTestFileComplete }, fatalErrorRef, watchSignals, setDispatchPageResolver, createWatchSession, collectProjectEntries, logWatchReady, destroyRuntime }: HeadedSchedulerDeps) => Promise<SchedulerRunResult>;
 export { };

package/dist/headlessScheduler.d.ts

@@ -6,9 +6,9 @@ import { type FatalPayload } from './hostPayloads.js';
 import type { BrowserHostConfig, BrowserProjectRuntime, TestFileInfo } from './protocol.js';
 import type { BrowserProviderBrowser } from './providers/index.js';
 import { planWatchRerun } from './watchRerunPlanner.js';
-import type { BrowserWatchSession, DispatchPageResolver, SchedulerRunResult } from './schedulerSeam.js';
+import type { BrowserV8CoverageRuntime, BrowserWatchSession, DispatchPageResolver, SchedulerRunResult } from './schedulerSeam.js';
 import type { WatchSignals } from './watchSignals.js';
-type HeadlessSchedulerContext = Pick<RstestContext, 'command' | 'snapshotManager' | 'stateManager' | 'updateReporterResultState'> & {
+type HeadlessSchedulerContext = Pick<RstestContext, 'command' | 'rootPath' | 'snapshotManager' | 'stateManager' | 'updateReporterResultState'> & {
     normalizedConfig: Pick<RstestContext['normalizedConfig'], 'bail' | 'pool'>;
 };
 type HeadlessSchedulerDeps = {
@@ -16,6 +16,7 @@ type HeadlessSchedulerDeps = {
     browser: BrowserProviderBrowser;
     browserLaunchOptions: BrowserRuntime['browserLaunchOptions'];
     projectServers: BrowserRuntime['projectServers'];
+    v8Coverage?: BrowserV8CoverageRuntime;
     allTestFiles: TestFileInfo[];
     projectRuntimeConfigs: BrowserProjectRuntime[];
     hostOptions: BrowserHostConfig;
@@ -28,10 +29,10 @@ type HeadlessSchedulerDeps = {
     };
     watchSignals: Pick<WatchSignals, 'setDispatchRerun' | 'setInterrupt' | 'signalInvalidation'>;
     setDispatchPageResolver: (resolver: DispatchPageResolver) => void;
-    createWatchSession: (execute: (testPaths: string[]) => Promise<void>) => BrowserWatchSession;
+    createWatchSession: (execute: (testPaths: string[]) => Promise<unknown[]>) => BrowserWatchSession;
     collectProjectEntries: () => Promise<Parameters<typeof planWatchRerun>[0]['projectEntries']>;
     logWatchReady: () => void;
     destroyRuntime: () => Promise<void>;
 };
-export declare const createHeadlessScheduler: ({ context, browser, browserLaunchOptions, projectServers, allTestFiles, projectRuntimeConfigs, hostOptions, watchState, isWatchMode, createDispatchRouter, handlers: { handleFatal, handleTestFileComplete }, watchSignals, setDispatchPageResolver, createWatchSession, collectProjectEntries, logWatchReady, destroyRuntime }: HeadlessSchedulerDeps) => Promise<SchedulerRunResult>;
+export declare const createHeadlessScheduler: ({ context, browser, browserLaunchOptions, projectServers, v8Coverage, allTestFiles, projectRuntimeConfigs, hostOptions, watchState, isWatchMode, createDispatchRouter, handlers: { handleFatal, handleTestFileComplete }, watchSignals, setDispatchPageResolver, createWatchSession, collectProjectEntries, logWatchReady, destroyRuntime }: HeadlessSchedulerDeps) => Promise<SchedulerRunResult>;
 export { };

package/dist/headlessTransport.d.ts

@@ -1,7 +1,9 @@
-import type { BrowserClientMessage, BrowserDispatchRequest, BrowserDispatchResponse } from './protocol.js';
+import type { BrowserDispatchRequest, BrowserDispatchResponse, RunnerEnvelope } from './protocol.js';
 import type { BrowserProviderPage } from './providers/index.js';
 type HeadlessRunnerTransportHandlers = {
-    onDispatchMessage: (message: BrowserClientMessage) => Promise<void>;
+    // The envelope's `runId` is ignored here: headless identity is the
+    // host-injected `runToken` bound at this transport attachment.
+    onDispatchMessage: (envelope: RunnerEnvelope) => Promise<void>;
     onDispatchRpc: (request: BrowserDispatchRequest) => Promise<BrowserDispatchResponse>;
 };
 /**

package/dist/hostPayloads.d.ts

@@ -1,4 +1,4 @@
-import type { Reporter, TestFileResult } from '@rstest/core/internal/browser';
+import type { Reporter } from '@rstest/core/internal/browser';
 import type { BrowserLogPayload } from './protocol.js';
 /** Payload for test file start event */ export type TestFileStartPayload = {
     testPath: string;
@@ -14,12 +14,6 @@ export type TestFileReadyPayload = ReporterHookArg<'onTestFileReady'>;
 export type TestSuiteStartPayload = ReporterHookArg<'onTestSuiteStart'>;
 export type TestSuiteResultPayload = ReporterHookArg<'onTestSuiteResult'>;
 export type TestCaseStartPayload = ReporterHookArg<'onTestCaseStart'>;
-export type ReloadTestFileAck = {
-    runId: string;
-};
-export type HeadedTestFileCompletePayload = TestFileResult & {
-    runId?: string;
-};
 export type DeferredPromise<T> = {
     promise: Promise<T>;
     resolve: (value: T | PromiseLike<T>) => void;