@rstest/browser 0.11.6 → 0.11.8

package/dist/{browser.js → client/index.js}

@@ -1,81 +1,5 @@
-import { DISPATCH_RESPONSE_TYPE, DISPATCH_RPC_BRIDGE_NAME as protocol_DISPATCH_RPC_BRIDGE_NAME, DISPATCH_RPC_REQUEST_TYPE as protocol_DISPATCH_RPC_REQUEST_TYPE, DISPATCH_MESSAGE_TYPE as protocol_DISPATCH_MESSAGE_TYPE, DISPATCH_NAMESPACE_BROWSER } from "./33.js";
-const DEFAULT_RPC_TIMEOUT_MS = 30000;
-const getRpcTimeout = ()=>window.__RSTEST_BROWSER_OPTIONS__?.rpcTimeout ?? DEFAULT_RPC_TIMEOUT_MS;
-const pendingRequests = new Map();
-let requestIdCounter = 0;
-let messageListenerInitialized = false;
-const createRequestId = (prefix)=>{
-    if ('function' == typeof globalThis.crypto?.randomUUID) return globalThis.crypto.randomUUID();
-    requestIdCounter += 1;
-    return `${prefix}-${Date.now().toString(36)}-${requestIdCounter.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
-};
-const isDispatchResponse = (value)=>'object' == typeof value && null !== value && 'requestId' in value && 'string' == typeof value.requestId;
-const settlePendingRequest = (response)=>{
-    const pending = pendingRequests.get(response.requestId);
-    if (!pending) return;
-    pendingRequests.delete(response.requestId);
-    if (response.stale) return void pending.reject(new Error(pending.staleMessage));
-    if (response.error) return void pending.reject(new Error(response.error));
-    pending.resolve(response.result);
-};
-const initMessageListener = ()=>{
-    if (messageListenerInitialized) return;
-    messageListenerInitialized = true;
-    window.addEventListener('message', (event)=>{
-        if (event.data?.type === DISPATCH_RESPONSE_TYPE) settlePendingRequest(event.data.payload);
-    });
-};
-const unwrapDispatchBridgeResult = (requestId, result, staleMessage)=>{
-    if (!isDispatchResponse(result)) throw new Error('Invalid dispatch bridge response payload.');
-    if (result.requestId !== requestId) throw new Error(`Mismatched dispatch response id: expected ${requestId}, got ${result.requestId}`);
-    if (result.stale) throw new Error(staleMessage);
-    if (result.error) throw new Error(result.error);
-    return result.result;
-};
-const dispatchRpc = ({ requestId, request, timeoutMs, timeoutMessage, staleMessage })=>{
-    if (window.parent === window) {
-        const dispatchBridge = window[protocol_DISPATCH_RPC_BRIDGE_NAME];
-        if (!dispatchBridge) throw new Error('Dispatch RPC bridge is not available in top-level runner.');
-        return new Promise((resolve, reject)=>{
-            const timeoutId = setTimeout(()=>{
-                reject(new Error(timeoutMessage));
-            }, timeoutMs);
-            const call = Promise.resolve(dispatchBridge(request)).then((result)=>unwrapDispatchBridgeResult(requestId, result, staleMessage));
-            call.then((result)=>{
-                clearTimeout(timeoutId);
-                resolve(result);
-            }).catch((error)=>{
-                clearTimeout(timeoutId);
-                reject(error instanceof Error ? error : new Error(String(error)));
-            });
-        });
-    }
-    initMessageListener();
-    return new Promise((resolve, reject)=>{
-        const timeoutId = setTimeout(()=>{
-            pendingRequests.delete(requestId);
-            reject(new Error(timeoutMessage));
-        }, timeoutMs);
-        pendingRequests.set(requestId, {
-            staleMessage,
-            resolve: (value)=>{
-                clearTimeout(timeoutId);
-                resolve(value);
-            },
-            reject: (error)=>{
-                clearTimeout(timeoutId);
-                reject(error);
-            }
-        });
-        window.parent.postMessage({
-            type: protocol_DISPATCH_MESSAGE_TYPE,
-            payload: {
-                type: protocol_DISPATCH_RPC_REQUEST_TYPE,
-                payload: request
-            }
-        }, '*');
-    });
-};
+import { registerElementExpect } from "@rstest/core/internal/browser-runtime";
+import { createRequestId, DISPATCH_NAMESPACE_BROWSER, dispatchRpc, getRpcTimeout } from "./240~1.js";
 const getUrlSearchParam = (name)=>{
     try {
         const value = new URL(window.location.href).searchParams.get(name);
@@ -89,11 +13,6 @@ const getCurrentTestPath = ()=>{
     if (!testPath) throw new Error("Browser RPC requires testFile in __RSTEST_BROWSER_OPTIONS__. This usually indicates the runner iframe was not configured by the container or URL.");
     return testPath;
 };
-const getCurrentRunId = ()=>{
-    const runId = window.__RSTEST_BROWSER_OPTIONS__?.runId ?? getUrlSearchParam('runId');
-    if (!runId) throw new Error("Browser RPC requires runId in __RSTEST_BROWSER_OPTIONS__. This usually indicates the runner iframe URL/config is stale or incomplete.");
-    return runId;
-};
 const createBrowserDispatchRequest = (requestId, request)=>({
         requestId,
         namespace: DISPATCH_NAMESPACE_BROWSER,
@@ -110,7 +29,6 @@ const callBrowserRpc = async (payload)=>{
     const request = {
         id,
         testPath: getCurrentTestPath(),
-        runId: getCurrentRunId(),
         ...payload
     };
     const dispatchRequest = createBrowserDispatchRequest(id, request);
@@ -562,22 +480,5 @@ const api_element = (locator)=>{
     if (!isLocator(locator)) throw new TypeError('expect.element() expects a Locator returned from @rstest/browser page.getBy* APIs.');
     return createElementExpect(locator, false);
 };
-const markBrowserElement = ()=>{
-    Object.defineProperty(api_element, '__rstestBrowser', {
-        value: true,
-        configurable: false,
-        enumerable: false,
-        writable: false
-    });
-};
-const installExpectElement = ()=>{
-    const api = globalThis.RSTEST_API;
-    const target = api?.expect;
-    if (!target) throw new Error('RSTEST_API.expect is not registered yet. This usually indicates @rstest/browser was imported too early.');
-    if ('function' != typeof target.element || !target.element.__rstestBrowser) {
-        markBrowserElement();
-        target.element = api_element;
-    }
-};
-installExpectElement();
+registerElementExpect(api_element);
 export { Locator, page, setTestIdAttribute };

package/dist/client/protocol.d.ts

@@ -0,0 +1,225 @@
+import type { BrowserViewport } from '@rstest/core/internal/browser';
+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';
+export declare const DISPATCH_MESSAGE_TYPE = '__rstest_dispatch__';
+export declare const DISPATCH_RESPONSE_TYPE = '__rstest_dispatch_response__';
+export declare const DISPATCH_RPC_BRIDGE_NAME = '__rstest_dispatch_rpc__';
+export declare const DISPATCH_RPC_REQUEST_TYPE = 'dispatch-rpc-request';
+export declare const RSTEST_CONFIG_MESSAGE_TYPE = 'RSTEST_CONFIG';
+export declare const NO_RPC_TIMEOUT = -1;
+export declare const DISPATCH_NAMESPACE_RUNNER = 'runner';
+export declare const DISPATCH_NAMESPACE_BROWSER = 'browser';
+export declare const DISPATCH_NAMESPACE_FILE_CLEANUP = 'file-cleanup';
+export declare const DISPATCH_NAMESPACE_SNAPSHOT = 'snapshot';
+export declare const DISPATCH_METHOD_RPC = 'rpc';
+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.
+export type { BrowserViewport };
+export type BrowserProjectRuntime = {
+    name: string;
+    environmentName: string;
+    projectRoot: string;
+    runtimeConfig: SerializedRuntimeConfig;
+    viewport?: BrowserViewport;
+};
+/**
+ * Test file info with associated project name.
+ * Used to track which project a test file belongs to.
+ */ export type TestFileInfo = {
+    testPath: string;
+    projectName: string;
+};
+export type FileCleanupDispatchMethod = 'start' | 'end';
+export type FileCleanupDispatchPayload = {
+    projectName: string;
+    result?: TestFileResult;
+    runId?: string;
+    testPath: string;
+};
+/**
+ * The committed test-file set plus its monotonic version. The version is what
+ * the container acks once every iframe for that set exists in the DOM, so both
+ * halves must travel together — a set without its version cannot be acked.
+ */ export type VersionedTestFileSet = {
+    files: TestFileInfo[];
+    version: number;
+};
+/**
+ * Execution mode for browser tests.
+ * - 'run': Execute tests and report results (default)
+ * - 'collect': Only collect test metadata without running
+ */ export type BrowserExecutionMode = 'run' | 'collect';
+/**
+ * Wire shape of a `log` client message payload. The host receives this and maps
+ * it onto core's {@link UserConsoleLog} (notably `level` → `name`); that mapper
+ * (`hostController.ts` `handleLog`) annotates its result as `UserConsoleLog`, so
+ * the map→core direction is compiler-checked. Owning the wire shape here as one
+ * named type keeps the host's input type from drifting away from the producer.
+ */ export type BrowserLogPayload = {
+    level: 'log' | 'warn' | 'error' | 'info' | 'debug';
+    content: string;
+    /**
+   * Owning project, resolved by the client from its manifest. The host must
+   * not re-derive it from `testPath` — concurrent projects can run the same
+   * file, so a path-keyed lookup can attribute the log to the wrong project.
+   */ projectName: string;
+    taskId?: string;
+    taskName?: string;
+    taskParentNames?: string[];
+    taskType?: 'file' | 'suite' | 'case';
+    testPath: string;
+    type: 'stdout' | 'stderr';
+    trace?: string;
+};
+export type BrowserHostConfig = {
+    rootPath: string;
+    projects: BrowserProjectRuntime[];
+    snapshot: {
+        updateSnapshot: SnapshotUpdateState;
+    };
+    testFile?: string;
+    /**
+   * The run identity this document executes under — the runner's SOLE identity
+   * source, adopted once at boot and stamped on every outbound message. Headed:
+   * the container confers its frame's current lease over the config handshake
+   * (so even an HMR full reload boots with the run the host is awaiting NOW).
+   * Headless: injected host-side as `${run.token}:${session.id}`. Never
+   * derivable from the URL.
+   */ runId?: string;
+    /**
+   * Base URL for runner (iframe) pages. Container origin; used as a fallback
+   * when a project has no entry in `projectRunnerUrls`.
+   */ runnerUrl?: string;
+    /**
+   * Per-project runner origin base URLs, keyed by project name. Each browser
+   * project runs on its own dev server, so the container must load each test
+   * file's iframe from that project's own origin.
+   */ projectRunnerUrls?: Record<string, string>;
+    /**
+   * WebSocket port for container RPC.
+   */ wsPort?: number;
+    /**
+   * Execution mode. Defaults to 'run'.
+   */ mode?: BrowserExecutionMode;
+    /**
+   * Debug mode. When true, enables verbose logging in browser.
+   */ debug?: boolean;
+    /** Timeout for RPC operations in milliseconds; negative values disable it. */ rpcTimeout?: number;
+};
+export declare const RSTEST_BROWSER_CACHE_CLEANERS_KEY = '@rstest/browser/cache-cleaners';
+/**
+ * The wrapper every runner document posts over `postMessage` / the headless
+ * bridge. Identity rides BESIDE the payload, never inside it: `message`
+ * payloads reach core reporting (`RunnerEventSink`, `BlobReporter`) as-is, so a
+ * transport identity spread into them would leak a nondeterministic UUID into
+ * reporter output. `runId` is the identity the document was granted at boot
+ * (headed: the container's config handshake; headless: the injected inline
+ * options) — never re-derived from the URL or the frame. Absent only for a
+ * document that was never granted one; the headed host drops such messages.
+ */ export type RunnerEnvelope = {
+    runId?: string;
+    message: BrowserClientMessage;
+};
+export type BrowserClientMessage = {
+    type: 'ready';
+} | {
+    type: 'file-start';
+    payload: {
+        testPath: string;
+        projectName: string;
+    };
+} | {
+    type: 'case-result';
+    payload: TestResult;
+} | {
+    type: 'file-complete';
+    payload: TestFileResult;
+} | {
+    type: 'log';
+    payload: BrowserLogPayload;
+} | {
+    type: 'fatal';
+    payload: {
+        message: string;
+        stack?: string;
+    };
+} | {
+    type: 'complete';
+} | {
+    type: 'collect-result';
+    payload: {
+        testPath: string;
+        project: string;
+        tests: TestInfo[];
+    };
+} | {
+    type: 'collect-complete';
+} | {
+    type: typeof DISPATCH_RPC_REQUEST_TYPE;
+    payload: BrowserDispatchRequest;
+};
+/**
+ * Lifecycle methods the runner emits via `dispatchRunnerLifecycle()` as
+ * dispatch-rpc-requests on the `runner` namespace (as opposed to the
+ * {@link BrowserClientMessage} types it `send()`s). The runner client imports
+ * this instead of redeclaring the list, so the emit site cannot drift from the
+ * host router.
+ */ export type RunnerLifecycleMethod = 'file-ready' | 'suite-start' | 'suite-result' | 'case-start';
+/**
+ * {@link BrowserClientMessage} types that are forwarded to the `runner`
+ * namespace (by message `type`) rather than handled at the transport layer.
+ * `Extract` keeps this a checked subset of the message union. `ready` and
+ * `complete` are deliberately absent: they still arrive, but their only job
+ * is done at the dispatch gate and the router ignores them silently.
+ */ type RunnerMessageMethod = Extract<BrowserClientMessage['type'], 'file-start' | 'case-result' | 'file-complete' | 'log' | 'fatal'>;
+/**
+ * Single source of truth for every method handled by the `runner` dispatch
+ * namespace. The host handler table is keyed by this union (a missing key is a
+ * compile error), so adding a runner method here forces a matching handler and
+ * cannot silently no-op at runtime.
+ */ export type RunnerDispatchMethod = RunnerLifecycleMethod | RunnerMessageMethod;
+/**
+ * Transport-agnostic envelope used by host routing.
+ * `namespace + method + args + target` describes an operation independent of
+ * the underlying message channel, and `runToken` provides run-level isolation.
+ */ export type BrowserDispatchRequest = {
+    requestId: string;
+    // Optional so headed/container paths can adopt the same envelope even when
+    // run-token isolation is only enforced in headless scheduling today.
+    runToken?: number;
+    /**
+   * Headed run identity, stamped by the runner's dispatch transport from the
+   * identity its document adopted at boot. The headed host accepts a request
+   * iff this names a live run; headless keeps using the host-injected
+   * `runToken` instead (`runToken` is the CYCLE generation, `runId` is the
+   * RUN identity — they are not interchangeable).
+   */ runId?: string;
+    namespace: string;
+    method: string;
+    args?: unknown;
+    // Routing reads `namespace`, `method`, `runToken`, and `target.sessionId`
+    // (see dispatchRouter.ts / dispatchBrowserRpcRequest). `target.testFile` and
+    // `target.projectName` are carried for diagnostics / forward-compatibility and
+    // are NOT consulted for routing today — adding a routing-relevant field here
+    // means wiring a reader on the host side, which structural typing won't force.
+    target?: {
+        testFile?: string;
+        sessionId?: string;
+        projectName?: string;
+    };
+};
+/**
+ * Dispatch response envelope.
+ * `stale: true` signals a safe drop from an older run generation, not a failure.
+ */ export type BrowserDispatchResponse = {
+    requestId: string;
+    runToken?: number;
+    result?: unknown;
+    error?: string;
+    stale?: boolean;
+};
+export type BrowserDispatchHandler = (request: BrowserDispatchRequest) => Promise<unknown>;

package/dist/client/rpcProtocol.d.ts

@@ -0,0 +1,138 @@
+export type BrowserLocatorText = {
+    type: 'string';
+    value: string;
+} | {
+    type: 'regexp';
+    source: string;
+    flags?: string;
+};
+export type BrowserLocatorStep = {
+    type: 'getByRole';
+    role: string;
+    options?: {
+        name?: BrowserLocatorText;
+        exact?: boolean;
+        checked?: boolean;
+        disabled?: boolean;
+        expanded?: boolean;
+        selected?: boolean;
+        pressed?: boolean;
+        includeHidden?: boolean;
+        level?: number;
+    };
+} | {
+    type: 'locator';
+    selector: string;
+} | {
+    type: 'getByText';
+    text: BrowserLocatorText;
+    options?: {
+        exact?: boolean;
+    };
+} | {
+    type: 'getByLabel';
+    text: BrowserLocatorText;
+    options?: {
+        exact?: boolean;
+    };
+} | {
+    type: 'getByPlaceholder';
+    text: BrowserLocatorText;
+    options?: {
+        exact?: boolean;
+    };
+} | {
+    type: 'getByAltText';
+    text: BrowserLocatorText;
+    options?: {
+        exact?: boolean;
+    };
+} | {
+    type: 'getByTitle';
+    text: BrowserLocatorText;
+    options?: {
+        exact?: boolean;
+    };
+} | {
+    type: 'getByTestId';
+    text: BrowserLocatorText;
+} | {
+    type: 'filter';
+    options: {
+        hasText?: BrowserLocatorText;
+        hasNotText?: BrowserLocatorText;
+        has?: BrowserLocatorIR;
+        hasNot?: BrowserLocatorIR;
+    };
+} | {
+    type: 'and';
+    locator: BrowserLocatorIR;
+} | {
+    type: 'or';
+    locator: BrowserLocatorIR;
+} | {
+    type: 'nth';
+    index: number;
+} | {
+    type: 'first';
+} | {
+    type: 'last';
+};
+export type BrowserLocatorIR = {
+    steps: BrowserLocatorStep[];
+};
+export type BrowserRpcRequest = {
+    id: string;
+    /** Absolute test file path for locating runner iframe */ testPath: string;
+    kind: 'locator' | 'expect' | 'config';
+    locator: BrowserLocatorIR;
+    method: string;
+    args: unknown[];
+    /**
+   * Negation for expect matchers (equivalent to Playwright expect(...).not).
+   * Only meaningful for kind === 'expect'.
+   */ isNot?: boolean;
+    /** Optional assertion timeout override (ms). Falls back to the host-provided assertion timeout. */ timeout?: number;
+};
+export declare const validateBrowserRpcRequest: (payload: unknown) => BrowserRpcRequest;
+/**
+ * Single source of truth for snapshot RPC methods and their argument shapes.
+ * The request union, the client sender, both host-side mappers, and every
+ * exhaustiveness check derive from this map — adding or renaming a method here
+ * forces a compile error at every site that has not been updated.
+ */ export type SnapshotRpcMethodArgs = {
+    resolveSnapshotPath: {
+        testPath: string;
+    };
+    readSnapshotFile: {
+        filepath: string;
+    };
+    saveSnapshotFile: {
+        filepath: string;
+        content: string;
+    };
+    removeSnapshotFile: {
+        filepath: string;
+    };
+};
+export type SnapshotRpcMethod = keyof SnapshotRpcMethodArgs;
+/**
+ * Snapshot RPC request from runner iframe.
+ * The container will forward these to the host via WebSocket RPC.
+ */ export type SnapshotRpcRequest = {
+    [M in SnapshotRpcMethod]: {
+        id: string;
+        method: M;
+        args: SnapshotRpcMethodArgs[M];
+    };
+}[SnapshotRpcMethod];
+/**
+ * Client-side snapshot RPC call (request without the transport `id`).
+ * Distributive over {@link SnapshotRpcMethod} so `method` and `args` stay paired
+ * at the call site — a mismatched pair fails to compile.
+ */ export type SnapshotRpcCall = {
+    [M in SnapshotRpcMethod]: {
+        method: M;
+        args: SnapshotRpcMethodArgs[M];
+    };
+}[SnapshotRpcMethod];