@rstest/browser 0.11.5 → 0.11.7

package/dist/containerRpc.d.ts

@@ -0,0 +1,60 @@
+import { type BirpcReturn } from 'birpc';
+import { type WebSocket, WebSocketServer } from 'ws';
+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<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[], 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
+   * `snapshot.updateSnapshot` between watch reruns).
+   */ onHostConfigUpdate: (config: BrowserHostConfig) => Promise<void>;
+};
+export type ContainerRpc = BirpcReturn<ContainerRpcMethods, HostRpcMethods>;
+// ============================================================================
+// RPC Manager - Encapsulates WebSocket and birpc management
+// ============================================================================
+/**
+ * Manages the WebSocket connection and birpc communication with the container UI.
+ * Provides a clean interface for sending RPC calls and handling connections.
+ */ export declare class ContainerRpcManager {
+    private wss;
+    private ws;
+    private rpc;
+    private methods;
+    private onDisconnect?;
+    private onAttach?;
+    private detachActiveSocketListeners;
+    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[], version: number): Promise<void>;
+    /** Push a refreshed host config to the container (watch reruns) */ updateHostConfig(config: BrowserHostConfig): Promise<void>;
+    /** Grant a run to a test file's frame and navigate it */ reloadTestFile(testFile: string, runId: string, testNamePattern?: string): Promise<void>;
+}

package/dist/dispatchCapabilities.d.ts

@@ -1,5 +1,5 @@
-import type { Reporter } from '@rstest/core/internal/browser';
 import { HostDispatchRouter } from './dispatchRouter.js';
+import type { ReporterHookArg } from './hostPayloads.js';
 import type { BrowserClientMessage, BrowserDispatchHandler, SnapshotRpcRequest } from './protocol.js';
 export type HostDispatchRouterOptions = ConstructorParameters<typeof HostDispatchRouter>[0];
 type RunnerPayload<TType extends BrowserClientMessage['type']> = Extract<BrowserClientMessage, {
@@ -7,7 +7,6 @@ type RunnerPayload<TType extends BrowserClientMessage['type']> = Extract<Browser
 }> extends {
     payload: infer TPayload;
 } ? TPayload : never;
-type ReporterHookArg<THook extends keyof Reporter> = NonNullable<Reporter[THook]> extends (...args: infer TArgs) => unknown ? TArgs[0] : never;
 type RunnerDispatchFileReadyPayload = ReporterHookArg<'onTestFileReady'>;
 type RunnerDispatchSuiteStartPayload = ReporterHookArg<'onTestSuiteStart'>;
 type RunnerDispatchSuiteResultPayload = ReporterHookArg<'onTestSuiteResult'>;

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

@@ -0,0 +1,58 @@
+import type { RstestContext, TestFileResult } from '@rstest/core/internal/browser';
+import { type BrowserRuntime } from './browserRsbuild.js';
+import type { HostDispatchRouter } from './dispatchRouter.js';
+import type { BrowserHostConfig, TestFileInfo } from './protocol.js';
+import { planWatchRerun } from './watchRerunPlanner.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'>;
+};
+type HeadedSchedulerDeps = {
+    context: HeadedSchedulerContext;
+    runtime: BrowserRuntime;
+    allTestFiles: TestFileInfo[];
+    hostOptions: BrowserHostConfig;
+    v8Coverage?: BrowserV8CoverageRuntime;
+    projectRoots: Map<string, string>;
+    isWatchMode: boolean;
+    createDispatchRouter: () => HostDispatchRouter;
+    handlers: {
+        // 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>;
+    };
+    fatalErrorRef: {
+        current: Error | null;
+    };
+    watchSignals: Pick<WatchSignals, 'setDispatchRerun' | 'signalInvalidation'>;
+    setDispatchPageResolver: (resolver: DispatchPageResolver) => void;
+    createWatchSession: (execute: (testPaths: string[]) => Promise<unknown[]>) => BrowserWatchSession;
+    collectProjectEntries: () => Promise<Parameters<typeof planWatchRerun>[0]['projectEntries']>;
+    logWatchReady: () => void;
+    destroyRuntime: () => Promise<void>;
+};
+/**
+ * A headed cycle's work list: the files of its scope that still exist, each
+ * paired with the test-name pattern whichever trigger put it in scope asked for.
+ *
+ * Both halves are resolved in one pass, synchronously, at the top of the cycle.
+ * A queued scope can go stale before its cycle is dequeued — a later trigger may
+ * have rebuilt the file set without one of these files — and it is skipped the
+ * way the headless twin skips it; throwing would abandon the still-valid files
+ * beside it and fail the run. The patterns are claimed here, and only for the
+ * paths in this scope, so a click landing once the cycle is under way keeps its
+ * pattern for the cycle it signalled instead of losing it to this one mid-loop.
+ *
+ * A skipped path keeps its pattern too, for the same reason: consuming it on the
+ * way past would leave the next cycle that does run the file — the file set can
+ * be rebuilt back — running it unfiltered, so the user's click would silently
+ * become a full-file rerun. The cost is one map entry per path that never comes
+ * back, which the next launch drops with the map.
+ */ export declare const claimHeadedCycleScope: (testPaths: string[], currentTestFiles: TestFileInfo[], pendingTestNamePatterns: Map<string, string>) => {
+    file: TestFileInfo;
+    testNamePattern?: string;
+}[];
+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

@@ -0,0 +1,38 @@
+import type { RstestContext, TestFileResult } from '@rstest/core/internal/browser';
+import { type BrowserRuntime } from './browserRsbuild.js';
+import type { HostDispatchRouterOptions } from './dispatchCapabilities.js';
+import type { HostDispatchRouter } from './dispatchRouter.js';
+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 { BrowserV8CoverageRuntime, BrowserWatchSession, DispatchPageResolver, SchedulerRunResult } from './schedulerSeam.js';
+import type { WatchSignals } from './watchSignals.js';
+type HeadlessSchedulerContext = Pick<RstestContext, 'command' | 'rootPath' | 'snapshotManager' | 'stateManager' | 'updateReporterResultState'> & {
+    normalizedConfig: Pick<RstestContext['normalizedConfig'], 'bail' | 'pool'>;
+};
+type HeadlessSchedulerDeps = {
+    context: HeadlessSchedulerContext;
+    browser: BrowserProviderBrowser;
+    browserLaunchOptions: BrowserRuntime['browserLaunchOptions'];
+    projectServers: BrowserRuntime['projectServers'];
+    v8Coverage?: BrowserV8CoverageRuntime;
+    allTestFiles: TestFileInfo[];
+    projectRuntimeConfigs: BrowserProjectRuntime[];
+    hostOptions: BrowserHostConfig;
+    watchState: BrowserRuntime['watchState'];
+    isWatchMode: boolean;
+    createDispatchRouter: (options?: HostDispatchRouterOptions) => HostDispatchRouter;
+    handlers: {
+        handleFatal: (payload: FatalPayload) => Promise<void>;
+        handleTestFileComplete: (payload: TestFileResult) => Promise<void>;
+    };
+    watchSignals: Pick<WatchSignals, 'setDispatchRerun' | 'setInterrupt' | 'signalInvalidation'>;
+    setDispatchPageResolver: (resolver: DispatchPageResolver) => void;
+    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, 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/hostController.d.ts

@@ -1,51 +1,17 @@
-import { type BrowserTestRunOptions, type BrowserTestRunResult, type ListBrowserTestsOptions, type ListCommandResult, type RstestContext } from '@rstest/core/internal/browser';
-type LazyCompilationModule = {
-    nameForCondition?: () => string | null | undefined;
-};
-type BrowserLazyCompilationConfig = {
-    imports: true;
-    entries: false;
-    test?: (module: LazyCompilationModule) => boolean;
+import { type BrowserTestRunOptions, type BrowserTestRunResult, type ExecutorInvalidationCallback, type ListBrowserTestsOptions, type ListCommandResult, type RstestContext } from '@rstest/core/internal/browser';
+import type { BrowserWatchSession } from './schedulerSeam.js';
+// ============================================================================
+export type BrowserControllerOptions = BrowserTestRunOptions & {
+    /**
+   * Watch only: core's watch-cycle driver (see `TestExecutor.onInvalidate`).
+   * Its promise settles when the cycle it queued has finalized, which only an
+   * explicit request may wait for (see `signalInvalidation`).
+   */ onInvalidate?: ExecutorInvalidationCallback;
 };
-/**
- * Resolve the actual port the dev server is listening on.
- *
- * Rsbuild's `devServer.listen()` may return `0` when configured with
- * `server.port: 0` because its internal `getPort` never reads back the
- * OS-assigned ephemeral port.  This helper falls back to
- * `httpServer.address()` to obtain the real bound port.
- */ export declare const resolveListenPort: (listenPort: number, httpServer: {
-    address: () => ReturnType<import('node:net').Server['address']>;
-} | null) => number;
-export declare const createBrowserLazyCompilationConfig: (setupFiles: string[]) => BrowserLazyCompilationConfig;
-/**
- * HMR — and the lazyCompilation transport it carries — is wired only for headed
- * watch, the sole path that reuses a persistent page and applies module updates
- * in place. Headless always loads each test file in a fresh page (pulling the
- * latest incrementally-built chunks over HTTP), and one-shot runs never rerun,
- * so pushing HMR updates there is dead weight that only races factory
- * registration for chunk-split node_modules (rspack#11922) and lets
- * lazyCompilation's accept-chain walk abort the next spec when no boundary
- * exists (#1472). Disabling HMR does not make watch rebuilds any less
- * incremental — HMR is only the client push transport.
- */ export declare const shouldEnableBrowserHmr: (isWatchMode: boolean, isHeadless: boolean) => boolean;
-export declare const createBrowserRsbuildDevConfig: (enableHmr: boolean) => {
-    writeToDisk: boolean;
-    hmr: boolean;
-    client: {
-        logLevel: 'error';
-    };
+export type BrowserControllerResult = BrowserTestRunResult & {
+    watchSession?: BrowserWatchSession;
 };
-export declare const createBrowserContextExcludeRegExp: (patterns: string[], projectRoot: string) => RegExp | null;
-// Host-side mirror of the browser runtime's `toContextKey` (client/entry.ts):
-// `./<path-relative-to-project-root>` with forward slashes. The runtime derives
-// the same key from the target test file, so the non-watch import map below must
-// key by the identical form for `loadTest(key)` to resolve.
-export declare const toContextKey: (filePath: string, projectRootPosix: string) => string;
-// ============================================================================
-// Main Entry Point
-// ============================================================================
-export declare const runBrowserController: (context: RstestContext, options?: BrowserTestRunOptions) => Promise<BrowserTestRunResult | void>;
+export declare const runBrowserController: (context: RstestContext, options?: BrowserControllerOptions) => Promise<BrowserControllerResult | void>;
 // ============================================================================
 // List Browser Tests
 // ============================================================================
@@ -62,4 +28,3 @@ export declare const runBrowserController: (context: RstestContext, options?: Br
  * This function creates a headless browser runtime, loads test files,
  * and collects their test structure (describe/test declarations).
  */ export declare const listBrowserTests: (context: RstestContext, options?: ListBrowserTestsOptions) => Promise<ListBrowserTestsResult>;
-export { };

package/dist/hostPayloads.d.ts

@@ -0,0 +1,24 @@
+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;
+    projectName: string;
+};
+/** Payload for log event — single-sourced from the wire protocol. */ export type LogPayload = BrowserLogPayload;
+/** Payload for fatal error event */ export type FatalPayload = {
+    message: string;
+    stack?: string;
+};
+export type ReporterHookArg<THook extends keyof Reporter> = NonNullable<Reporter[THook]> extends (...args: infer TArgs) => unknown ? TArgs[0] : never;
+export type TestFileReadyPayload = ReporterHookArg<'onTestFileReady'>;
+export type TestSuiteStartPayload = ReporterHookArg<'onTestSuiteStart'>;
+export type TestSuiteResultPayload = ReporterHookArg<'onTestSuiteResult'>;
+export type TestCaseStartPayload = ReporterHookArg<'onTestCaseStart'>;
+export type DeferredPromise<T> = {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: unknown) => void;
+};
+export declare const getFileTaskId: (testPath: string) => string;
+export declare const toError: (error: unknown) => Error;
+export declare const createDeferredPromise: <T>() => DeferredPromise<T>;