@rstest/browser 0.11.4 → 0.11.6

package/dist/browserRsbuild.d.ts

@@ -0,0 +1,119 @@
+import { type ProjectContext, type RstestContext, rsbuild, type WatchInvalidationState } from '@rstest/core/internal/browser';
+import { WebSocketServer } from 'ws';
+import type { ContainerRpcManager } from './containerRpc.js';
+import type { BrowserDispatchHandler, BrowserHostConfig, BrowserProjectRuntime, TestFileInfo } from './protocol.js';
+import type { BrowserProvider, BrowserProviderBrowser, BrowserProviderContext, BrowserProviderPage } from './providers/index.js';
+type RsbuildDevServer = rsbuild.RsbuildDevServer;
+type RsbuildInstance = rsbuild.RsbuildInstance;
+export declare const serializeForInlineScript: (value: unknown) => string;
+// ============================================================================
+// Type Definitions
+type BrowserProjectEntries = {
+    project: ProjectContext;
+    setupFiles: string[];
+    testFiles: string[];
+};
+export type BrowserProviderProject = {
+    rootPath: string;
+    provider: BrowserProvider;
+};
+type BrowserLaunchOptions = {
+    provider: BrowserProvider;
+    browser: ProjectContext['normalizedConfig']['browser']['browser'];
+    headless: ProjectContext['normalizedConfig']['browser']['headless'];
+    port: ProjectContext['normalizedConfig']['browser']['port'];
+    strictPort: ProjectContext['normalizedConfig']['browser']['strictPort'];
+    providerOptions: Record<string, unknown>;
+};
+export type BrowserProjectServer = {
+    projectName: string;
+    environmentName: string;
+    rsbuildInstance: RsbuildInstance;
+    devServer: RsbuildDevServer;
+    port: number;
+    manifestPath: string;
+};
+// Watch diff/rerun state. Lives on the BrowserRuntime (one per set of
+// per-project compilers, surviving controller re-entry that reuses the
+// runtime) instead of module scope, so its lifetime always matches the
+// compilers whose baselines it holds.
+type BrowserWatchState = {
+    lastTestFiles: TestFileInfo[];
+    hooksEnabled: boolean;
+    // Diff baselines keyed per project: sibling projects have isolated
+    // compilers, so a shared flat baseline would let one project's compile
+    // clobber another's (missed reruns) and collide on compiler-local chunk
+    // keys.
+    invalidation: Map<string, WatchInvalidationState>;
+    // Affected files accumulated per project until a rerun drains them, so a
+    // compile finishing while another project's rerun is being planned cannot
+    // drop pending work.
+    pendingAffectedTestFiles: Map<string, Set<string>>;
+    // Per-project compile start times and the accumulated compile duration of
+    // the pending rerun, so the rerun's finalize reports the real buildTime.
+    compileStartTimes: Map<string, number>;
+    pendingBuildTimeMs: number;
+};
+export declare const drainPendingBuildTime: (watchState: BrowserWatchState) => number;
+export declare const drainPendingAffectedTestFiles: (watchState: BrowserWatchState) => string[];
+export type BrowserRuntime = {
+    // Per-project servers, keyed by project name.
+    projectServers: Map<string, BrowserProjectServer>;
+    // The server that hosts the container UI HTML (headed mode). The WebSocket
+    // server below is shared and reachable from any origin.
+    containerServer: BrowserProjectServer;
+    browser: BrowserProviderBrowser;
+    browserLaunchOptions: BrowserLaunchOptions;
+    wsPort: number;
+    tempDir: string;
+    containerPage?: BrowserProviderPage;
+    containerContext?: BrowserProviderContext;
+    setContainerOptions: (options: BrowserHostConfig) => void;
+    // Reserved extension seam for host-side dispatch capabilities.
+    dispatchHandlers: Map<string, BrowserDispatchHandler>;
+    wss: WebSocketServer;
+    rpcManager?: ContainerRpcManager;
+    projectEntries: BrowserProjectEntries[];
+    watchState: BrowserWatchState;
+};
+export declare const mapViewportByProject: (projects: BrowserProjectRuntime[]) => Map<string, {
+    width: number;
+    height: number;
+}>;
+export declare const createBrowserContextExcludeRegExp: (patterns: string[], projectRoot: string) => RegExp | null;
+export declare const getBrowserProjects: (context: RstestContext) => ProjectContext[];
+export declare const collectProjectEntries: (context: RstestContext, // The explicit browser-project subset the executor was constructed with. Falls
+// back to re-deriving from `context` for internal callers (e.g. the watch
+// plugin) that do not carry the plan's project list.
+browserProjects?: ProjectContext[]) => Promise<BrowserProjectEntries[]>;
+export declare const resolveContainerDist: () => string;
+// 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;
+export declare const destroyBrowserRuntime: (runtime: BrowserRuntime) => Promise<void>;
+export declare const createBrowserRuntime: ({ context, projectEntries: initialProjectEntries, browserProjects, shardedEntries, freezeShardedEntries, tempDir, isWatchMode, onTriggerRerun, containerDistPath, containerDevServer, forceHeadless, skipProviderLaunch, appliedModifyRstestConfigEnvironments }: {
+    context: RstestContext;
+    projectEntries: BrowserProjectEntries[];
+    /**
+   * The explicit browser-project subset (plan output). Drives launch-option
+   * consistency and the container origin (`browserProjects[0]`).
+   */ browserProjects: ProjectContext[];
+    shardedEntries?: Map<string, {
+        entries: Record<string, string>;
+    }>;
+    freezeShardedEntries?: boolean;
+    tempDir: string;
+    isWatchMode: boolean;
+    onTriggerRerun?: () => Promise<void>;
+    containerDistPath?: string;
+    containerDevServer?: string;
+    /** Force headless mode regardless of user config (used for list command) */ forceHeadless?: boolean;
+    skipProviderLaunch?: boolean;
+    appliedModifyRstestConfigEnvironments?: Set<string>;
+}) => Promise<BrowserRuntime>;
+export declare function resolveProjectEntries(context: RstestContext, shardedEntries: Map<string, {
+    entries: Record<string, string>;
+}> | undefined, browserProjects: ProjectContext[]): Promise<BrowserProjectEntries[]>;
+export { };

package/dist/containerRpc.d.ts

@@ -0,0 +1,52 @@
+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 = {
+    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.
+    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>;
+    /**
+   * 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 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 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>;
+    /** 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>;
+}

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/headedScheduler.d.ts

@@ -0,0 +1,58 @@
+import type { RstestContext, TestFileResult, TestResult } 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 { 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;
+    isWatchMode: boolean;
+    createDispatchRouter: () => HostDispatchRouter;
+    handlers: {
+        handleTestFileStart: (payload: TestFileStartPayload) => Promise<void>;
+        handleTestCaseResult: (payload: TestResult) => Promise<void>;
+        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'>;
+    setDispatchPageResolver: (resolver: DispatchPageResolver) => void;
+    createWatchSession: (execute: (testPaths: string[]) => Promise<void>) => 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, isWatchMode, createDispatchRouter, handlers: { handleTestFileStart, handleTestCaseResult, handleTestFileComplete, handleLog, handleFatal }, fatalErrorRef, watchSignals, setDispatchPageResolver, createWatchSession, collectProjectEntries, logWatchReady, destroyRuntime }: HeadedSchedulerDeps) => Promise<SchedulerRunResult>;
+export { };

package/dist/headlessScheduler.d.ts

@@ -0,0 +1,37 @@
+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 { BrowserWatchSession, DispatchPageResolver, SchedulerRunResult } from './schedulerSeam.js';
+import type { WatchSignals } from './watchSignals.js';
+type HeadlessSchedulerContext = Pick<RstestContext, 'command' | 'snapshotManager' | 'stateManager' | 'updateReporterResultState'> & {
+    normalizedConfig: Pick<RstestContext['normalizedConfig'], 'bail' | 'pool'>;
+};
+type HeadlessSchedulerDeps = {
+    context: HeadlessSchedulerContext;
+    browser: BrowserProviderBrowser;
+    browserLaunchOptions: BrowserRuntime['browserLaunchOptions'];
+    projectServers: BrowserRuntime['projectServers'];
+    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<void>) => 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 { };

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,30 @@
+import type { Reporter, TestFileResult } 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 ReloadTestFileAck = {
+    runId: string;
+};
+export type HeadedTestFileCompletePayload = TestFileResult & {
+    runId?: string;
+};
+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>;