@rstest/browser 0.8.5 → 0.9.1

package/src/AGENTS.md

@@ -0,0 +1,128 @@
+# Browser mode host architecture
+
+This document is architecture-only and focuses on browser mode scheduling in `@rstest/browser` host-side modules.
+
+## Module topology
+
+```mermaid
+flowchart LR
+  subgraph Host["@rstest/browser host (Node.js)"]
+    IDX["index.ts\nrunBrowserTests()"]
+    HC["hostController.ts\nrunBrowserController()"]
+    RT["createBrowserRuntime()"]
+    DR["dispatchCapabilities.ts + dispatchRouter.ts\nnamespace router"]
+    RL["runSession.ts\nRunSessionLifecycle"]
+    SR["sessionRegistry.ts\nRunnerSessionRegistry"]
+    WP["watchRerunPlanner.ts"]
+    LS["headlessLatestRerunScheduler.ts"]
+  end
+
+  subgraph UI["@rstest/browser-ui container (headed path)"]
+    UR["useRpc() / birpc"]
+    CH["core/channel.ts\nforwardDispatchRpcRequest()"]
+    MH["main.tsx message listener\nforward lifecycle callbacks"]
+  end
+
+  subgraph Runner["runner runtime (src/client/entry.ts)"]
+    MSG["runner lifecycle messages"]
+    RPC["dispatch-rpc-request"]
+  end
+
+  IDX --> HC
+  HC --> RT
+  HC --> DR
+  HC --> WP
+  WP --> LS
+  HC --> RL
+  RL --> SR
+
+  UR <--> HC
+  MSG --> MH
+  MH --> UR
+  RPC --> CH
+  CH --> UR
+
+  HC -."headless bridge:\nexposeFunction(\_\_rstest_dispatch\_\_, \_\_rstest_dispatch_rpc\_\_)".-> Runner
+```
+
+## Headed transport path
+
+Primary dispatch request direction is `Runner -> Container -> Host -> Router -> Handler`.
+`Host -> Container` in this path is bootstrap setup and callback delivery, not router request initiation.
+`dispatchRouter` handles inbound request routing only; outbound response delivery is a transport reply.
+
+### Bootstrap control plane
+
+```mermaid
+sequenceDiagram
+  participant Host as browser hostController
+  participant Container as browser-ui container
+
+  Host->>Container: open container and establish birpc
+  Host->>Container: provide BrowserHostConfig
+  Container-->>Host: getTestFiles and rerun requests
+```
+
+### Runtime dispatch RPC data plane
+
+```mermaid
+sequenceDiagram
+  participant Runner as client iframe runner
+  participant Container as browser-ui channel
+  participant Host as browser hostController
+  participant Router as browser dispatchRouter
+  participant Handler as namespace handler
+
+  Runner->>Container: postMessage runner lifecycle
+  Container->>Host: forward lifecycle callbacks (onTest*)
+
+  Runner->>Container: postMessage dispatch rpc request
+  Container->>Host: rpc.dispatch(request)
+  Host->>Router: routing inbound request
+  Router->>Handler: resolve namespace handler
+  Handler->>Host: execute host capability work
+  Host-->>Handler: capability result or error
+  Handler-->>Router: return handler result
+  Router-->>Host: routing done, response payload
+  Host-->>Container: transport reply payload
+  Container-->>Runner: transport reply to runner
+```
+
+## Headless transport path
+
+Primary dispatch request direction is `Runner -> Host -> Router -> Handler`.
+`Host -> Runner` in this path is bridge registration, not router request initiation.
+`dispatchRouter` handles inbound request routing only; outbound response delivery is a transport reply.
+
+### Bootstrap control plane
+
+```mermaid
+sequenceDiagram
+  participant Host as browser hostController
+  participant Runner as client top level runner
+
+  Host->>Runner: exposeFunction __rstest_dispatch__
+  Host->>Runner: exposeFunction __rstest_dispatch_rpc__
+```
+
+### Runtime dispatch RPC data plane
+
+```mermaid
+sequenceDiagram
+  participant Runner as client top level runner
+  participant Host as browser hostController
+  participant Router as browser dispatchRouter
+  participant Handler as namespace handler
+
+  Runner->>Host: __rstest_dispatch__ lifecycle
+  Host->>Host: forward lifecycle callbacks
+
+  Runner->>Host: __rstest_dispatch_rpc__ request
+  Host->>Router: routing inbound request
+  Router->>Handler: resolve namespace handler
+  Handler->>Host: execute host capability work
+  Host-->>Handler: capability result or error
+  Handler-->>Router: return handler result
+  Router-->>Host: routing done, response payload
+  Host-->>Runner: transport reply payload
+```

package/src/augmentExpect.ts

@@ -0,0 +1,62 @@
+import type { Locator } from './client/locator';
+
+export type BrowserElementExpect = {
+  not: BrowserElementExpect;
+  toBeVisible: (options?: { timeout?: number }) => Promise<void>;
+  toBeHidden: (options?: { timeout?: number }) => Promise<void>;
+  toBeEnabled: (options?: { timeout?: number }) => Promise<void>;
+  toBeDisabled: (options?: { timeout?: number }) => Promise<void>;
+  toBeChecked: (options?: { timeout?: number }) => Promise<void>;
+  toBeUnchecked: (options?: { timeout?: number }) => Promise<void>;
+  toBeAttached: (options?: { timeout?: number }) => Promise<void>;
+  toBeDetached: (options?: { timeout?: number }) => Promise<void>;
+  toBeEditable: (options?: { timeout?: number }) => Promise<void>;
+  toBeFocused: (options?: { timeout?: number }) => Promise<void>;
+  toBeEmpty: (options?: { timeout?: number }) => Promise<void>;
+  toBeInViewport: (options?: {
+    timeout?: number;
+    ratio?: number;
+  }) => Promise<void>;
+  toHaveText: (
+    text: string | RegExp,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+  toContainText: (
+    text: string | RegExp,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+  toHaveValue: (
+    value: string | RegExp,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+  toHaveId: (
+    value: string | RegExp,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+  toHaveAttribute: (
+    name: string,
+    value?: string | RegExp,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+  toHaveClass: (
+    value: string | RegExp,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+  toHaveCount: (count: number, options?: { timeout?: number }) => Promise<void>;
+  toHaveCSS: (
+    name: string,
+    value: string | RegExp,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+  toHaveJSProperty: (
+    name: string,
+    value: unknown,
+    options?: { timeout?: number },
+  ) => Promise<void>;
+};
+
+declare module '@rstest/core' {
+  interface ExpectStatic {
+    element: (locator: Locator) => BrowserElementExpect;
+  }
+}

package/src/browser.ts

@@ -0,0 +1,3 @@
+import './augmentExpect';
+
+export * from './client/api';

package/src/browserRpcRegistry.ts

@@ -0,0 +1,57 @@
+/**
+ * Runtime allowlists for Browser RPC methods.
+ *
+ * Planned capabilities are intentionally documented in comments (not runtime
+ * data) to keep this module focused on host-side validation.
+ *
+ * Planned gaps (non-exhaustive):
+ * - Locator query/interop: filter({ hasNot, hasNotText }), locator.selector/length,
+ *   locator.query()/element()/elements()/all(), page.elementLocator(element),
+ *   locators.extend(...)
+ * - Locator actions: tripleClick, hover out, drag/drop helpers
+ * - Assertions: a11y matchers (accessible name/description), toHaveRole,
+ *   toHaveValues
+ * - Artifacts intentionally excluded for now: screenshot/toMatchScreenshot/
+ *   trace/video
+ */
+export const supportedLocatorActions = new Set<string>([
+  'click',
+  'dblclick',
+  'fill',
+  'hover',
+  'press',
+  'clear',
+  'check',
+  'uncheck',
+  'focus',
+  'blur',
+  'scrollIntoViewIfNeeded',
+  'waitFor',
+  'dispatchEvent',
+  'selectOption',
+  'setInputFiles',
+]);
+
+export const supportedExpectElementMatchers = new Set<string>([
+  'toBeVisible',
+  'toBeHidden',
+  'toBeEnabled',
+  'toBeDisabled',
+  'toBeAttached',
+  'toBeDetached',
+  'toBeEditable',
+  'toBeFocused',
+  'toBeEmpty',
+  'toBeInViewport',
+  'toHaveText',
+  'toContainText',
+  'toHaveValue',
+  'toHaveAttribute',
+  'toHaveClass',
+  'toHaveCount',
+  'toBeChecked',
+  'toBeUnchecked',
+  'toHaveId',
+  'toHaveCSS',
+  'toHaveJSProperty',
+]);

package/src/client/AGENTS.md

@@ -0,0 +1,82 @@
+# Browser mode runner architecture
+
+This document is architecture-only and focuses on the browser runner runtime in `src/client`.
+
+## Runner bootstrap pipeline
+
+```mermaid
+flowchart TD
+  A["waitForConfig()"] --> B["read \_\_RSTEST_BROWSER_OPTIONS\_\_ + URL overrides"]
+  B --> R["send ready"]
+  R --> C["setRealTimers()"]
+  C --> D["preloadRunnerSourceMap()"]
+  D --> E["resolve project + runtimeConfig"]
+  E --> F{"execution mode"}
+
+  F -->|collect| G["create runtime + load setup/test modules + runner.collectTests()"]
+  G --> H["send collect-result / collect-complete"]
+
+  F -->|run| I["interceptConsole() + createRstestRuntime()"]
+  I --> J["send file-start"]
+  J --> K["load setup files + load test module"]
+  K --> L["runner.runTests() + send case-result"]
+  L --> N["send file-complete per file"]
+  N --> O["send complete after all files"]
+
+  H --> M["window.\_\_RSTEST_DONE\_\_ = true"]
+  O --> M
+```
+
+## Transport architecture
+
+```mermaid
+flowchart LR
+  subgraph IframePath["Iframe path (headed)"]
+    S1["send()"] --> P1["parent.postMessage(\_\_rstest_dispatch\_\_)"]
+    R1["dispatchRunnerLifecycle()"] --> P2["postMessage dispatch-rpc-request"]
+    SN1["snapshot.sendRpcRequest()"] --> P3["postMessage dispatch-rpc-request + wait \_\_rstest_dispatch_response\_\_"]
+  end
+
+  subgraph TopLevelRunPath["Top-level page path (headless run)"]
+    S2["send()"] --> D1["window.\_\_rstest_dispatch\_\_"]
+    R2["dispatchRunnerLifecycle()"] --> D2["window.\_\_rstest_dispatch_rpc\_\_"]
+    SN2["snapshot.sendRpcRequest()"] --> D3["window.\_\_rstest_dispatch_rpc\_\_"]
+  end
+
+  subgraph TopLevelCollectPath["Top-level page path (list collect)"]
+    S3["send()"] --> C1["window.\_\_rstest_dispatch\_\_"]
+  end
+```
+
+## Snapshot RPC sequence
+
+```mermaid
+sequenceDiagram
+  participant Snap as snapshot.ts
+  participant Runner as entry.ts runtime
+  participant Container as browser-ui channel
+  participant Host as host dispatch router
+
+  Snap->>Runner: sendRpcRequest(method, args)
+
+  alt top-level runner (headless run)
+    Runner->>Host: __rstest_dispatch_rpc__(namespace=snapshot)
+    Host-->>Runner: BrowserDispatchResponse
+    Runner-->>Snap: result/error
+  else iframe runner (headed)
+    Runner->>Container: postMessage(dispatch-rpc-request)
+    Container->>Host: rpc.dispatch(request)
+    Host-->>Container: BrowserDispatchResponse
+    Container-->>Runner: __rstest_dispatch_response__
+    Runner-->>Snap: resolve/reject pending request
+  end
+```
+
+List collect mode does not use the snapshot RPC namespace.
+
+## Runtime invariants
+
+- `entry.ts` is the only bootstrap entry and decides `collect` vs `run` mode.
+- Runner lifecycle events (`file-ready`, `suite-start`, `suite-result`, `case-start`) go through the `runner` dispatch namespace.
+- Snapshot file operations go through the `snapshot` dispatch namespace and never access filesystem directly in browser runtime.
+- Console interception is per test file and must restore original console methods in `finally`.

package/src/client/api.ts

@@ -0,0 +1,213 @@
+import type { BrowserElementExpect } from '../augmentExpect';
+import type { BrowserLocatorText, BrowserRpcRequest } from '../rpcProtocol';
+import { callBrowserRpc } from './browserRpc';
+import {
+  isLocator,
+  Locator,
+  page,
+  serializeText,
+  setTestIdAttribute,
+} from './locator';
+
+const serializeMatcherText = (value: string | RegExp): BrowserLocatorText => {
+  return serializeText(value);
+};
+
+const createElementExpect = (
+  locator: Locator,
+  isNot: boolean,
+): BrowserElementExpect => {
+  const callExpect = async (
+    method: string,
+    args: unknown[],
+    timeout?: number,
+  ): Promise<void> => {
+    await callBrowserRpc<void>({
+      kind: 'expect',
+      locator: locator.ir,
+      method,
+      args,
+      isNot,
+      timeout,
+    } satisfies Omit<BrowserRpcRequest, 'id' | 'testPath' | 'runId'>);
+  };
+
+  const api: Omit<BrowserElementExpect, 'not'> = {
+    async toBeVisible(options) {
+      await callExpect('toBeVisible', [], options?.timeout);
+    },
+    async toBeHidden(options) {
+      await callExpect('toBeHidden', [], options?.timeout);
+    },
+    async toBeEnabled(options) {
+      await callExpect('toBeEnabled', [], options?.timeout);
+    },
+    async toBeDisabled(options) {
+      await callExpect('toBeDisabled', [], options?.timeout);
+    },
+    async toBeChecked(options) {
+      await callExpect('toBeChecked', [], options?.timeout);
+    },
+    async toBeUnchecked(options) {
+      await callExpect('toBeUnchecked', [], options?.timeout);
+    },
+    async toBeAttached(options) {
+      await callExpect('toBeAttached', [], options?.timeout);
+    },
+    async toBeDetached(options) {
+      await callExpect('toBeDetached', [], options?.timeout);
+    },
+    async toBeEditable(options) {
+      await callExpect('toBeEditable', [], options?.timeout);
+    },
+    async toBeFocused(options) {
+      await callExpect('toBeFocused', [], options?.timeout);
+    },
+    async toBeEmpty(options) {
+      await callExpect('toBeEmpty', [], options?.timeout);
+    },
+    async toBeInViewport(options) {
+      const ratio = options?.ratio;
+      await callExpect(
+        'toBeInViewport',
+        ratio === undefined ? [] : [ratio],
+        options?.timeout,
+      );
+    },
+    async toHaveText(text, options) {
+      await callExpect(
+        'toHaveText',
+        [serializeMatcherText(text)],
+        options?.timeout,
+      );
+    },
+    async toContainText(text, options) {
+      await callExpect(
+        'toContainText',
+        [serializeMatcherText(text)],
+        options?.timeout,
+      );
+    },
+    async toHaveValue(value, options) {
+      await callExpect(
+        'toHaveValue',
+        [serializeMatcherText(value)],
+        options?.timeout,
+      );
+    },
+    async toHaveId(value, options) {
+      await callExpect(
+        'toHaveId',
+        [serializeMatcherText(value)],
+        options?.timeout,
+      );
+    },
+    async toHaveAttribute(name, value, options) {
+      const args =
+        value === undefined ? [name] : [name, serializeMatcherText(value)];
+      await callExpect('toHaveAttribute', args, options?.timeout);
+    },
+    async toHaveClass(value, options) {
+      await callExpect(
+        'toHaveClass',
+        [serializeMatcherText(value)],
+        options?.timeout,
+      );
+    },
+    async toHaveCount(count, options) {
+      await callExpect('toHaveCount', [count], options?.timeout);
+    },
+    async toHaveCSS(name, value, options) {
+      if (typeof name !== 'string' || !name) {
+        throw new TypeError('toHaveCSS expects a non-empty CSS property name');
+      }
+      await callExpect(
+        'toHaveCSS',
+        [name, serializeMatcherText(value)],
+        options?.timeout,
+      );
+    },
+    async toHaveJSProperty(name, value, options) {
+      if (typeof name !== 'string' || !name) {
+        throw new TypeError(
+          'toHaveJSProperty expects a non-empty property name',
+        );
+      }
+      await callExpect('toHaveJSProperty', [name, value], options?.timeout);
+    },
+  };
+
+  const withNot = api as BrowserElementExpect;
+  Object.defineProperty(withNot, 'not', {
+    configurable: false,
+    enumerable: false,
+    get() {
+      return createElementExpect(locator, !isNot);
+    },
+  });
+  return withNot;
+};
+
+const element = (locator: unknown): BrowserElementExpect => {
+  if (!isLocator(locator)) {
+    throw new TypeError(
+      'expect.element() expects a Locator returned from @rstest/browser page.getBy* APIs.',
+    );
+  }
+
+  return createElementExpect(locator, false);
+};
+
+const markBrowserElement = (): void => {
+  Object.defineProperty(element, '__rstestBrowser', {
+    value: true,
+    configurable: false,
+    enumerable: false,
+    writable: false,
+  });
+};
+
+const installExpectElement = (): void => {
+  // In browser runtime, `@rstest/core` exports are proxies that forward property
+  // access to `globalThis.RSTEST_API`. Patch the underlying expect implementation.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const api = (globalThis as any).RSTEST_API as any;
+  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 (typeof target.element !== 'function' || !target.element.__rstestBrowser) {
+    markBrowserElement();
+    target.element = element;
+  }
+};
+
+installExpectElement();
+
+export type {
+  BrowserPage,
+  BrowserSerializable,
+  LocatorBlurOptions,
+  LocatorCheckOptions,
+  LocatorClickOptions,
+  LocatorDblclickOptions,
+  LocatorDispatchEventInit,
+  LocatorFillOptions,
+  LocatorFilterOptions,
+  LocatorFocusOptions,
+  LocatorGetByRoleOptions,
+  LocatorHoverOptions,
+  LocatorKeyboardModifier,
+  LocatorMouseButton,
+  LocatorPosition,
+  LocatorPressOptions,
+  LocatorScrollIntoViewIfNeededOptions,
+  LocatorSelectOptionOptions,
+  LocatorSetInputFilesOptions,
+  LocatorTextOptions,
+  LocatorWaitForOptions,
+} from './locator';
+export { Locator, page, setTestIdAttribute };

package/src/client/browserRpc.ts

@@ -0,0 +1,86 @@
+import type { BrowserDispatchRequest } from '../protocol';
+import { DISPATCH_METHOD_RPC, DISPATCH_NAMESPACE_BROWSER } from '../protocol';
+import type { BrowserRpcRequest } from '../rpcProtocol';
+import {
+  createRequestId,
+  dispatchRpc,
+  getRpcTimeout,
+} from './dispatchTransport';
+
+const getUrlSearchParam = (name: string): string | undefined => {
+  try {
+    const value = new URL(window.location.href).searchParams.get(name);
+    return value ?? undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const getCurrentTestPath = (): string => {
+  const testPath =
+    window.__RSTEST_BROWSER_OPTIONS__?.testFile ??
+    getUrlSearchParam('testFile');
+  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 = (): string => {
+  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: string,
+  request: BrowserRpcRequest,
+): BrowserDispatchRequest => {
+  return {
+    requestId,
+    namespace: DISPATCH_NAMESPACE_BROWSER,
+    method: DISPATCH_METHOD_RPC,
+    args: request,
+    target: {
+      testFile: request.testPath,
+    },
+  };
+};
+
+export const callBrowserRpc = async <T>(
+  payload: Omit<BrowserRpcRequest, 'id' | 'testPath' | 'runId'>,
+): Promise<T> => {
+  if (
+    payload.kind === 'config' &&
+    window.__RSTEST_BROWSER_OPTIONS__?.mode === 'collect'
+  ) {
+    return undefined as T;
+  }
+
+  const id = createRequestId('browser-rpc');
+  const rpcTimeout = getRpcTimeout();
+  const request: BrowserRpcRequest = {
+    id,
+    testPath: getCurrentTestPath(),
+    runId: getCurrentRunId(),
+    ...payload,
+  };
+  const dispatchRequest = createBrowserDispatchRequest(id, request);
+
+  return dispatchRpc<T>({
+    requestId: id,
+    request: dispatchRequest,
+    timeoutMs: rpcTimeout,
+    staleMessage: 'Stale browser RPC request ignored.',
+    timeoutMessage: `Browser RPC timeout after ${rpcTimeout / 1000}s: ${request.kind}.${request.method}`,
+  });
+};