@rstest/browser 0.8.5 → 0.9.0

package/src/protocol.ts

@@ -1,12 +1,34 @@
 import type { DevicePreset } from '@rstest/core/browser';
 import type {
   RuntimeConfig,
-  Test,
   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 const DISPATCH_MESSAGE_TYPE = '__rstest_dispatch__';
+export const DISPATCH_RESPONSE_TYPE = '__rstest_dispatch_response__';
+export const DISPATCH_RPC_BRIDGE_NAME = '__rstest_dispatch_rpc__';
+export const DISPATCH_RPC_REQUEST_TYPE = 'dispatch-rpc-request';
+export const RSTEST_CONFIG_MESSAGE_TYPE = 'RSTEST_CONFIG';
+
+export const DISPATCH_NAMESPACE_RUNNER = 'runner';
+export const DISPATCH_NAMESPACE_BROWSER = 'browser';
+export const DISPATCH_NAMESPACE_SNAPSHOT = 'snapshot';
+export const DISPATCH_METHOD_RPC = 'rpc';
+
 export type SerializedRuntimeConfig = RuntimeConfig;
 
 export type BrowserViewport =
@@ -47,6 +69,11 @@ export type BrowserHostConfig = {
     updateSnapshot: SnapshotUpdateState;
   };
   testFile?: string; // Optional: if provided, only run this specific test file
+  /**
+   * 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.
    */
@@ -96,46 +123,54 @@ export type BrowserClientMessage =
   // Collect mode messages
   | {
       type: 'collect-result';
-      payload: { testPath: string; project: string; tests: Test[] };
+      payload: { testPath: string; project: string; tests: TestInfo[] };
     }
   | { type: 'collect-complete' }
-  // Snapshot RPC requests (from runner iframe to container)
+  // Unified RPC envelope for all runner -> container/host capability calls.
+  // Snapshot already uses this path via namespace "snapshot". Future PR #948
+  // capabilities can add new namespaces instead of adding new message types.
   | {
-      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;
+  // Optional so headed/container paths can adopt the same envelope even when
+  // run-token isolation is only enforced in headless scheduling today.
+  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/src/providers/index.ts

@@ -0,0 +1,103 @@
+import type { BrowserRpcRequest } from '../rpcProtocol';
+import { playwrightProviderImplementation } from './playwright';
+
+/**
+ * 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>;
+};
+
+const providerImplementations: Record<
+  BrowserProvider,
+  BrowserProviderImplementation
+> = {
+  playwright: playwrightProviderImplementation,
+};
+
+export function getBrowserProviderImplementation(
+  provider: BrowserProvider,
+): BrowserProviderImplementation {
+  const implementation = providerImplementations[provider];
+  if (!implementation) {
+    throw new Error(`Unsupported browser provider: ${String(provider)}`);
+  }
+  return implementation;
+}

package/src/providers/playwright/compileLocator.ts

@@ -0,0 +1,130 @@
+import type { FrameLocator, Locator, Page } from 'playwright';
+import type { BrowserLocatorIR } from '../../protocol';
+import { reviveBrowserLocatorText } from './textMatcher';
+
+export const compilePlaywrightLocator = (
+  frame: FrameLocator | Page,
+  locatorIR: BrowserLocatorIR,
+): Locator => {
+  const compileFromFrame = (ir: BrowserLocatorIR): Locator => {
+    let current: FrameLocator | Page | Locator = frame;
+
+    const ensureLocator = (): Locator => {
+      if ((current as any).filter) {
+        return current as Locator;
+      }
+      // Convert FrameLocator to a Locator within the frame.
+      current = (current as FrameLocator).locator(':root');
+      return current as Locator;
+    };
+
+    for (const step of ir.steps as any[]) {
+      switch (step.type) {
+        case 'getByRole': {
+          const name = step.options?.name
+            ? reviveBrowserLocatorText(step.options.name)
+            : undefined;
+          const options = step.options ? { ...step.options, name } : undefined;
+          current = (current as any).getByRole(step.role, options);
+          break;
+        }
+        case 'locator':
+          current = (current as any).locator(step.selector);
+          break;
+        case 'getByText':
+          current = (current as any).getByText(
+            reviveBrowserLocatorText(step.text),
+            step.options,
+          );
+          break;
+        case 'getByLabel':
+          current = (current as any).getByLabel(
+            reviveBrowserLocatorText(step.text),
+            step.options,
+          );
+          break;
+        case 'getByPlaceholder':
+          current = (current as any).getByPlaceholder(
+            reviveBrowserLocatorText(step.text),
+            step.options,
+          );
+          break;
+        case 'getByAltText':
+          current = (current as any).getByAltText(
+            reviveBrowserLocatorText(step.text),
+            step.options,
+          );
+          break;
+        case 'getByTitle':
+          current = (current as any).getByTitle(
+            reviveBrowserLocatorText(step.text),
+            step.options,
+          );
+          break;
+        case 'getByTestId':
+          current = (current as any).getByTestId(
+            reviveBrowserLocatorText(step.text) as any,
+          );
+          break;
+        case 'filter': {
+          const locator = ensureLocator();
+          const options: {
+            hasText?: string | RegExp;
+            hasNotText?: string | RegExp;
+            has?: Locator;
+            hasNot?: Locator;
+          } = {};
+          if (step.options?.hasText) {
+            options.hasText = reviveBrowserLocatorText(step.options.hasText);
+          }
+          if (step.options?.hasNotText) {
+            options.hasNotText = reviveBrowserLocatorText(
+              step.options.hasNotText,
+            );
+          }
+          if (step.options?.has) {
+            options.has = compileFromFrame(step.options.has);
+          }
+          if (step.options?.hasNot) {
+            options.hasNot = compileFromFrame(step.options.hasNot);
+          }
+          current = locator.filter(options);
+          break;
+        }
+        case 'and': {
+          const locator = ensureLocator();
+          const other = compileFromFrame(step.locator);
+          current = locator.and(other);
+          break;
+        }
+        case 'or': {
+          const locator = ensureLocator();
+          const other = compileFromFrame(step.locator);
+          current = locator.or(other);
+          break;
+        }
+        case 'nth': {
+          const locator = ensureLocator();
+          current = locator.nth(step.index);
+          break;
+        }
+        case 'first': {
+          const locator = ensureLocator();
+          current = locator.first();
+          break;
+        }
+        case 'last': {
+          const locator = ensureLocator();
+          current = locator.last();
+          break;
+        }
+        default:
+          throw new Error(`Unknown locator step: ${String(step?.type)}`);
+      }
+    }
+
+    return ensureLocator();
+  };
+
+  return compileFromFrame(locatorIR);
+};