@rstest/browser 0.8.4 → 0.9.0

package/dist/protocol.d.ts

@@ -1,6 +1,17 @@
 import type { DevicePreset } from '@rstest/core/browser';
-import type { RuntimeConfig, Test, TestFileResult, TestResult } from '@rstest/core/browser-runtime';
+import type { RuntimeConfig, TestFileResult, TestInfo, TestResult } from '@rstest/core/browser-runtime';
 import type { SnapshotUpdateState } from '@vitest/snapshot';
+export type { BrowserLocatorIR, BrowserLocatorStep, BrowserLocatorText, BrowserRpcRequest, BrowserRpcResponse, SnapshotRpcRequest, SnapshotRpcResponse, } from './rpcProtocol';
+export { validateBrowserRpcRequest } from './rpcProtocol';
+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 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 BrowserViewport = {
     width: number;
@@ -34,6 +45,11 @@ export type BrowserHostConfig = {
         updateSnapshot: SnapshotUpdateState;
     };
     testFile?: string;
+    /**
+     * Per-run identifier assigned by the container.
+     * Used by browser RPC calls to prevent stale requests from previous reruns.
+     */
+    runId?: string;
     /**
      * Base URL for runner (iframe) pages.
      */
@@ -92,49 +108,44 @@ export type BrowserClientMessage = {
     payload: {
         testPath: string;
         project: string;
-        tests: Test[];
+        tests: TestInfo[];
     };
 } | {
     type: 'collect-complete';
 } | {
-    type: 'snapshot-rpc-request';
-    payload: SnapshotRpcRequest;
+    type: typeof DISPATCH_RPC_REQUEST_TYPE;
+    payload: BrowserDispatchRequest;
 };
 /**
- * Snapshot RPC request from runner iframe.
- * The container will forward these to the host via WebSocket RPC.
+ * 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 SnapshotRpcRequest = {
-    id: string;
-    method: 'resolveSnapshotPath';
-    args: {
-        testPath: string;
-    };
-} | {
-    id: string;
-    method: 'readSnapshotFile';
-    args: {
-        filepath: string;
-    };
-} | {
-    id: string;
-    method: 'saveSnapshotFile';
-    args: {
-        filepath: string;
-        content: string;
-    };
-} | {
-    id: string;
-    method: 'removeSnapshotFile';
-    args: {
-        filepath: string;
+export type BrowserDispatchRequest = {
+    requestId: string;
+    runToken?: number;
+    namespace: string;
+    method: string;
+    args?: unknown;
+    target?: {
+        testFile?: string;
+        sessionId?: string;
+        projectName?: string;
     };
 };
 /**
- * Snapshot RPC response from container to runner iframe.
+ * Dispatch response envelope.
+ * `stale: true` signals a safe drop from an older run generation, not a failure.
  */
-export type SnapshotRpcResponse = {
-    id: string;
+export type BrowserDispatchResponse = {
+    requestId: string;
+    runToken?: number;
     result?: unknown;
     error?: string;
+    stale?: boolean;
+};
+export type BrowserDispatchResponseEnvelope = {
+    type: typeof DISPATCH_RESPONSE_TYPE;
+    payload: BrowserDispatchResponse;
 };
+export type BrowserDispatchHandler = (request: BrowserDispatchRequest) => Promise<unknown>;

package/dist/providers/index.d.ts

@@ -0,0 +1,79 @@
+import type { BrowserRpcRequest } from '../rpcProtocol';
+/**
+ * Browser provider contract hub.
+ *
+ * When adding a new built-in provider, implement `BrowserProviderImplementation`
+ * and register it in `providerImplementations` below.
+ */
+export type BrowserProvider = 'playwright';
+/** Minimal console shape needed by host logging bridge. */
+export type BrowserConsoleMessage = {
+    text: () => string;
+};
+/**
+ * Minimal page API surface required by hostController.
+ *
+ * This is a structural type (shape interface), NOT a direct Playwright import.
+ * It currently mirrors a subset of Playwright's Page API because that is the
+ * only provider. When adding a second provider whose page primitive diverges
+ * (e.g. WebDriver BiDi), consider pushing page-level orchestration (goto,
+ * exposeFunction, addInitScript, event listeners) into provider-specific
+ * implementations so hostController only calls high-level semantic methods.
+ */
+export type BrowserProviderPage = {
+    goto: (url: string, options?: {
+        waitUntil?: 'load';
+    }) => Promise<unknown>;
+    exposeFunction: (name: string, fn: (...args: any[]) => any) => Promise<void>;
+    addInitScript: (script: string) => Promise<void>;
+    on: {
+        (event: 'popup', listener: (page: BrowserProviderPage) => void): void;
+        (event: 'console', listener: (message: BrowserConsoleMessage) => void): void;
+    };
+    close: () => Promise<void>;
+};
+/** Minimal browser context API surface required by hostController. */
+export type BrowserProviderContext = {
+    newPage: () => Promise<BrowserProviderPage>;
+    on: (event: 'page', listener: (page: BrowserProviderPage) => void) => void;
+    close: () => Promise<void>;
+};
+/** Minimal browser API surface required by hostController. */
+export type BrowserProviderBrowser = {
+    close: () => Promise<void>;
+    newContext: (options: {
+        viewport: {
+            width: number;
+            height: number;
+        } | null;
+    }) => Promise<BrowserProviderContext>;
+};
+/** Provider launch result consumed by hostController. */
+export type BrowserProviderRuntime = {
+    browser: BrowserProviderBrowser;
+};
+/** Input contract for browser launch. */
+export type LaunchBrowserInput = {
+    browserName: 'chromium' | 'firefox' | 'webkit';
+    headless: boolean | undefined;
+};
+/** Input contract for provider-side browser RPC dispatch. */
+export type DispatchBrowserRpcInput = {
+    containerPage?: BrowserProviderPage;
+    runnerPage?: BrowserProviderPage;
+    request: BrowserRpcRequest;
+    timeoutFallbackMs: number;
+};
+/**
+ * Core provider implementation contract.
+ *
+ * Any new built-in provider must:
+ * - launch browser runtime for test execution
+ * - execute browser RPC requests (locator actions + assertions)
+ */
+export type BrowserProviderImplementation = {
+    name: BrowserProvider;
+    launchRuntime: (input: LaunchBrowserInput) => Promise<BrowserProviderRuntime>;
+    dispatchRpc: (input: DispatchBrowserRpcInput) => Promise<unknown>;
+};
+export declare function getBrowserProviderImplementation(provider: BrowserProvider): BrowserProviderImplementation;

package/dist/providers/playwright/compileLocator.d.ts

@@ -0,0 +1,3 @@
+import type { FrameLocator, Locator, Page } from 'playwright';
+import type { BrowserLocatorIR } from '../../protocol';
+export declare const compilePlaywrightLocator: (frame: FrameLocator | Page, locatorIR: BrowserLocatorIR) => Locator;

package/dist/providers/playwright/dispatchBrowserRpc.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Contains adapted logic from Playwright matchers:
+ * https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/matchers.ts
+ * Copyright (c) Microsoft Corporation, Apache-2.0.
+ */
+import type { Page } from 'playwright';
+import type { BrowserRpcRequest } from '../../rpcProtocol';
+export declare function dispatchPlaywrightBrowserRpc({ containerPage, runnerPage, request, timeoutFallbackMs, }: {
+    containerPage?: Page;
+    runnerPage?: Page;
+    request: BrowserRpcRequest;
+    timeoutFallbackMs: number;
+}): Promise<unknown>;

package/dist/providers/playwright/expectUtils.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Contains adapted logic from Playwright matchers:
+ * https://github.com/microsoft/playwright/blob/main/packages/playwright/src/matchers/matchers.ts
+ * Copyright (c) Microsoft Corporation, Apache-2.0.
+ */
+import type { BrowserLocatorText } from '../../rpcProtocol';
+type ExpectedTextValue = {
+    string?: string;
+    regexSource?: string;
+    regexFlags?: string;
+    matchSubstring?: boolean;
+    ignoreCase?: boolean;
+    normalizeWhiteSpace?: boolean;
+};
+export declare const serializeExpectedText: (text: BrowserLocatorText, options?: {
+    matchSubstring?: boolean;
+    normalizeWhiteSpace?: boolean;
+    ignoreCase?: boolean;
+}) => ExpectedTextValue[];
+export declare const formatExpectError: (result: {
+    errorMessage?: string;
+    log?: string[];
+}) => string;
+export {};

package/dist/providers/playwright/implementation.d.ts

@@ -0,0 +1,2 @@
+import type { BrowserProviderImplementation } from '../index';
+export declare const playwrightProviderImplementation: BrowserProviderImplementation;

package/dist/providers/playwright/index.d.ts

@@ -0,0 +1 @@
+export { playwrightProviderImplementation } from './implementation';

package/dist/providers/playwright/runtime.d.ts

@@ -0,0 +1,5 @@
+import type { BrowserProviderRuntime } from '../index';
+export declare function launchPlaywrightBrowser({ browserName, headless, }: {
+    browserName: 'chromium' | 'firefox' | 'webkit';
+    headless: boolean | undefined;
+}): Promise<BrowserProviderRuntime>;

package/dist/providers/playwright/textMatcher.d.ts

@@ -0,0 +1,8 @@
+export declare const reviveBrowserLocatorText: (text: {
+    type: "string";
+    value: string;
+} | {
+    type: "regexp";
+    source: string;
+    flags?: string;
+}) => string | RegExp;

package/dist/rpcProtocol.d.ts

@@ -0,0 +1,145 @@
+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;
+    /** Run identifier generated by container for stale-request protection. */
+    runId: 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 timeout override (ms). Falls back to browser rpcTimeout. */
+    timeout?: number;
+};
+export declare const validateBrowserRpcRequest: (payload: unknown) => BrowserRpcRequest;
+export type BrowserRpcResponse = {
+    id: string;
+    result?: unknown;
+    error?: string;
+};
+/**
+ * Snapshot RPC request from runner iframe.
+ * The container will forward these to the host via WebSocket RPC.
+ */
+export type SnapshotRpcRequest = {
+    id: string;
+    method: 'resolveSnapshotPath';
+    args: {
+        testPath: string;
+    };
+} | {
+    id: string;
+    method: 'readSnapshotFile';
+    args: {
+        filepath: string;
+    };
+} | {
+    id: string;
+    method: 'saveSnapshotFile';
+    args: {
+        filepath: string;
+        content: string;
+    };
+} | {
+    id: string;
+    method: 'removeSnapshotFile';
+    args: {
+        filepath: string;
+    };
+};
+/**
+ * Snapshot RPC response from container to runner iframe.
+ */
+export type SnapshotRpcResponse = {
+    id: string;
+    result?: unknown;
+    error?: string;
+};

package/dist/runSession.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Run generation/session lifecycle contract shared by browser scheduling paths.
+ */
+export type RunSession = {
+    token: number;
+    cancelled: boolean;
+    cancelSignal: Promise<void>;
+    signalCancel: () => void;
+    done?: Promise<void>;
+};
+export declare const createRunSession: (token: number) => RunSession;
+type CancelOptions<T extends RunSession> = {
+    waitForDone?: boolean;
+    onCancel?: (session: T) => Promise<void> | void;
+};
+/**
+ * Canonical run-token lifecycle manager.
+ * Centralizes token increment, invalidation, and cancellation semantics.
+ */
+export declare class RunSessionLifecycle<T extends RunSession> {
+    private currentToken;
+    private active;
+    get activeSession(): T | null;
+    get activeToken(): number;
+    createSession(factory: (token: number) => T): T;
+    isTokenActive(token: number): boolean;
+    isTokenStale(token: number): boolean;
+    invalidateActiveToken(): number;
+    clearIfActive(session: T): void;
+    cancel(session: T, options?: CancelOptions<T>): Promise<void>;
+    cancelActive(options?: CancelOptions<T>): Promise<void>;
+}
+export {};

package/dist/sessionRegistry.d.ts

@@ -0,0 +1,34 @@
+import type { BrowserProviderContext, BrowserProviderPage } from './providers';
+export type RunnerSessionRecord = {
+    id: string;
+    testFile: string;
+    projectName: string;
+    runToken: number;
+    mode: 'headless-page' | 'headed-iframe';
+    createdAt: number;
+    context?: BrowserProviderContext;
+    page?: BrowserProviderPage;
+    metadata?: Record<string, unknown>;
+};
+type RunnerSessionInput = Omit<RunnerSessionRecord, 'id' | 'createdAt'> & {
+    id?: string;
+    createdAt?: number;
+};
+/**
+ * Execution target index for host scheduling.
+ * Provides lookup by session id, test file, and run token without coupling to UI topology.
+ */
+export declare class RunnerSessionRegistry {
+    private nextId;
+    private sessionsById;
+    private sessionIdByTestFile;
+    register(input: RunnerSessionInput): RunnerSessionRecord;
+    getById(id: string): RunnerSessionRecord | undefined;
+    getByTestFile(testFile: string): RunnerSessionRecord | undefined;
+    list(): RunnerSessionRecord[];
+    listByRunToken(runToken: number): RunnerSessionRecord[];
+    deleteById(id: string): boolean;
+    deleteByTestFile(testFile: string): boolean;
+    clear(): void;
+}
+export {};

package/dist/sourceMap/sourceMapLoader.d.ts

@@ -0,0 +1,14 @@
+import type { DecodedSourceMapXInput, EncodedSourceMapXInput } from '@jridgewell/trace-mapping';
+export type SourceMapPayload = EncodedSourceMapXInput | DecodedSourceMapXInput;
+type Fetcher = typeof fetch;
+export declare const normalizeJavaScriptUrl: (value: string, options?: {
+    origin?: string;
+}) => string | null;
+export declare const loadSourceMapWithCache: ({ jsUrl, cache, force, origin, fetcher, }: {
+    jsUrl: string;
+    cache: Map<string, SourceMapPayload | null>;
+    force?: boolean;
+    origin?: string;
+    fetcher?: Fetcher;
+}) => Promise<SourceMapPayload | null>;
+export {};

package/dist/watchRerunPlanner.d.ts

@@ -0,0 +1,21 @@
+import type { TestFileInfo } from './protocol';
+export type WatchPlannerProjectEntry = {
+    project: {
+        name: string;
+    };
+    testFiles: string[];
+};
+type WatchRerunPlannerInput = {
+    projectEntries: WatchPlannerProjectEntry[];
+    previousTestFiles: TestFileInfo[];
+    affectedTestFiles: string[];
+};
+export type WatchRerunPlan = {
+    currentTestFiles: TestFileInfo[];
+    filesChanged: boolean;
+    normalizedAffectedTestFiles: string[];
+    affectedTestFiles: TestFileInfo[];
+};
+export declare const collectWatchTestFiles: (projectEntries: WatchPlannerProjectEntry[]) => TestFileInfo[];
+export declare const planWatchRerun: ({ projectEntries, previousTestFiles, affectedTestFiles, }: WatchRerunPlannerInput) => WatchRerunPlan;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rstest/browser",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "description": "Browser mode support for Rstest testing framework.",
   "bugs": {
     "url": "https://github.com/web-infra-dev/rstest/issues"
@@ -20,9 +20,12 @@
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/browser.d.ts",
+      "default": "./dist/browser.js"
+    },
+    "./internal": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
@@ -32,33 +35,35 @@
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "NOTICE",
+    "LICENSE-APACHE-2.0"
   ],
   "dependencies": {
     "@jridgewell/trace-mapping": "0.3.31",
     "convert-source-map": "^2.0.0",
-    "open-editor": "^4.0.0",
+    "open-editor": "^4.1.1",
     "pathe": "^2.0.3",
     "sirv": "^2.0.4",
-    "ws": "^8.18.3"
+    "ws": "^8.19.0"
   },
   "devDependencies": {
-    "@rslib/core": "^0.19.0",
+    "@rslib/core": "^0.19.6",
     "@types/convert-source-map": "^2.0.3",
     "@types/picomatch": "^4.0.2",
     "@types/ws": "^8.18.1",
     "@vitest/snapshot": "^3.2.4",
-    "birpc": "2.9.0",
+    "birpc": "^4.0.0",
     "picocolors": "^1.1.1",
     "picomatch": "^4.0.3",
-    "playwright": "^1.49.1",
+    "playwright": "^1.58.2",
     "@rstest/browser-ui": "0.0.0",
     "@rstest/tsconfig": "0.0.1",
-    "@rstest/core": "0.8.4"
+    "@rstest/core": "0.9.0"
   },
   "peerDependencies": {
     "playwright": "^1.49.1",
-    "@rstest/core": "^0.8.4"
+    "@rstest/core": "^0.9.0"
   },
   "peerDependenciesMeta": {
     "playwright": {
@@ -66,7 +71,7 @@
     }
   },
   "engines": {
-    "node": ">=18.12.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "publishConfig": {
     "access": "public",