@rstest/browser 0.8.4 → 0.9.0

package/src/client/locator.ts

@@ -0,0 +1,452 @@
+import type {
+  BrowserLocatorIR,
+  BrowserLocatorText,
+  BrowserRpcRequest,
+} from '../rpcProtocol';
+import { callBrowserRpc } from './browserRpc';
+
+export const serializeText = (value: string | RegExp): BrowserLocatorText => {
+  if (typeof value === 'string') {
+    return { type: 'string', value };
+  }
+  return { type: 'regexp', source: value.source, flags: value.flags };
+};
+
+export type LocatorGetByRoleOptions = {
+  name?: string | RegExp;
+  exact?: boolean;
+  checked?: boolean;
+  disabled?: boolean;
+  expanded?: boolean;
+  selected?: boolean;
+  pressed?: boolean;
+  includeHidden?: boolean;
+  level?: number;
+};
+
+export type LocatorTextOptions = {
+  exact?: boolean;
+};
+
+export type LocatorKeyboardModifier =
+  | 'Alt'
+  | 'Control'
+  | 'ControlOrMeta'
+  | 'Meta'
+  | 'Shift';
+
+export type LocatorMouseButton = 'left' | 'right' | 'middle';
+
+export type LocatorPosition = {
+  x: number;
+  y: number;
+};
+
+export type LocatorClickOptions = {
+  button?: LocatorMouseButton;
+  clickCount?: number;
+  delay?: number;
+  force?: boolean;
+  modifiers?: LocatorKeyboardModifier[];
+  position?: LocatorPosition;
+  timeout?: number;
+  trial?: boolean;
+};
+
+export type LocatorDblclickOptions = Omit<LocatorClickOptions, 'clickCount'>;
+
+export type LocatorHoverOptions = Pick<
+  LocatorClickOptions,
+  'force' | 'modifiers' | 'position' | 'timeout' | 'trial'
+>;
+
+export type LocatorPressOptions = {
+  delay?: number;
+  timeout?: number;
+};
+
+export type LocatorFillOptions = {
+  force?: boolean;
+  timeout?: number;
+};
+
+export type LocatorCheckOptions = {
+  force?: boolean;
+  position?: LocatorPosition;
+  timeout?: number;
+  trial?: boolean;
+};
+
+export type LocatorFocusOptions = {
+  timeout?: number;
+};
+
+export type LocatorBlurOptions = {
+  timeout?: number;
+};
+
+export type LocatorScrollIntoViewIfNeededOptions = {
+  timeout?: number;
+};
+
+export type LocatorWaitForOptions = {
+  state?: 'attached' | 'detached' | 'visible' | 'hidden';
+  timeout?: number;
+};
+
+export type BrowserSerializable =
+  | null
+  | boolean
+  | number
+  | string
+  | BrowserSerializable[]
+  | { [key: string]: BrowserSerializable };
+
+export type LocatorDispatchEventInit = BrowserSerializable;
+
+export type LocatorSelectOptionOptions = {
+  force?: boolean;
+  timeout?: number;
+};
+
+export type LocatorSetInputFilesOptions = {
+  timeout?: number;
+};
+
+export type LocatorFilterOptions = {
+  hasText?: string | RegExp;
+  hasNotText?: string | RegExp;
+  has?: Locator;
+  hasNot?: Locator;
+};
+
+export class Locator {
+  readonly ir: BrowserLocatorIR;
+
+  constructor(ir: BrowserLocatorIR) {
+    this.ir = ir;
+  }
+
+  getByRole(role: string, options?: LocatorGetByRoleOptions): Locator {
+    const next = {
+      steps: [
+        ...this.ir.steps,
+        {
+          type: 'getByRole',
+          role,
+          options: options
+            ? {
+                ...options,
+                name:
+                  options.name === undefined
+                    ? undefined
+                    : serializeText(options.name),
+              }
+            : undefined,
+        },
+      ],
+    } satisfies BrowserLocatorIR;
+    return new Locator(next);
+  }
+
+  locator(selector: string): Locator {
+    return new Locator({
+      steps: [...this.ir.steps, { type: 'locator', selector }],
+    });
+  }
+
+  getByText(text: string | RegExp, options?: LocatorTextOptions): Locator {
+    return new Locator({
+      steps: [
+        ...this.ir.steps,
+        { type: 'getByText', text: serializeText(text), options },
+      ],
+    });
+  }
+
+  getByLabel(text: string | RegExp, options?: LocatorTextOptions): Locator {
+    return new Locator({
+      steps: [
+        ...this.ir.steps,
+        { type: 'getByLabel', text: serializeText(text), options },
+      ],
+    });
+  }
+
+  getByPlaceholder(
+    text: string | RegExp,
+    options?: LocatorTextOptions,
+  ): Locator {
+    return new Locator({
+      steps: [
+        ...this.ir.steps,
+        { type: 'getByPlaceholder', text: serializeText(text), options },
+      ],
+    });
+  }
+
+  getByAltText(text: string | RegExp, options?: LocatorTextOptions): Locator {
+    return new Locator({
+      steps: [
+        ...this.ir.steps,
+        { type: 'getByAltText', text: serializeText(text), options },
+      ],
+    });
+  }
+
+  getByTitle(text: string | RegExp, options?: LocatorTextOptions): Locator {
+    return new Locator({
+      steps: [
+        ...this.ir.steps,
+        { type: 'getByTitle', text: serializeText(text), options },
+      ],
+    });
+  }
+
+  getByTestId(text: string | RegExp): Locator {
+    return new Locator({
+      steps: [
+        ...this.ir.steps,
+        { type: 'getByTestId', text: serializeText(text) },
+      ],
+    });
+  }
+
+  filter(options: LocatorFilterOptions): Locator {
+    return new Locator({
+      steps: [
+        ...this.ir.steps,
+        {
+          type: 'filter',
+          options: {
+            hasText: options.hasText
+              ? serializeText(options.hasText)
+              : undefined,
+            hasNotText: options.hasNotText
+              ? serializeText(options.hasNotText)
+              : undefined,
+            has:
+              options.has === undefined
+                ? undefined
+                : isLocator(options.has)
+                  ? options.has.ir
+                  : (() => {
+                      throw new TypeError(
+                        'Locator.filter({ has }) expects a Locator returned from @rstest/browser page.getBy* APIs.',
+                      );
+                    })(),
+            hasNot:
+              options.hasNot === undefined
+                ? undefined
+                : isLocator(options.hasNot)
+                  ? options.hasNot.ir
+                  : (() => {
+                      throw new TypeError(
+                        'Locator.filter({ hasNot }) expects a Locator returned from @rstest/browser page.getBy* APIs.',
+                      );
+                    })(),
+          },
+        },
+      ],
+    });
+  }
+
+  and(other: Locator): Locator {
+    if (!isLocator(other)) {
+      throw new TypeError(
+        'Locator.and() expects a Locator returned from @rstest/browser page.getBy* APIs.',
+      );
+    }
+    return new Locator({
+      steps: [...this.ir.steps, { type: 'and', locator: other.ir }],
+    });
+  }
+
+  or(other: Locator): Locator {
+    if (!isLocator(other)) {
+      throw new TypeError(
+        'Locator.or() expects a Locator returned from @rstest/browser page.getBy* APIs.',
+      );
+    }
+    return new Locator({
+      steps: [...this.ir.steps, { type: 'or', locator: other.ir }],
+    });
+  }
+
+  nth(index: number): Locator {
+    return new Locator({ steps: [...this.ir.steps, { type: 'nth', index }] });
+  }
+
+  first(): Locator {
+    return new Locator({ steps: [...this.ir.steps, { type: 'first' }] });
+  }
+
+  last(): Locator {
+    return new Locator({ steps: [...this.ir.steps, { type: 'last' }] });
+  }
+
+  async click(options?: LocatorClickOptions): Promise<void> {
+    await this.callLocator('click', options === undefined ? [] : [options]);
+  }
+
+  async dblclick(options?: LocatorDblclickOptions): Promise<void> {
+    await this.callLocator('dblclick', options === undefined ? [] : [options]);
+  }
+
+  async fill(value: string, options?: LocatorFillOptions): Promise<void> {
+    await this.callLocator(
+      'fill',
+      options === undefined ? [value] : [value, options],
+    );
+  }
+
+  async hover(options?: LocatorHoverOptions): Promise<void> {
+    await this.callLocator('hover', options === undefined ? [] : [options]);
+  }
+
+  async press(key: string, options?: LocatorPressOptions): Promise<void> {
+    await this.callLocator(
+      'press',
+      options === undefined ? [key] : [key, options],
+    );
+  }
+
+  async clear(): Promise<void> {
+    await this.callLocator('clear', []);
+  }
+
+  async check(options?: LocatorCheckOptions): Promise<void> {
+    await this.callLocator('check', options === undefined ? [] : [options]);
+  }
+
+  async uncheck(options?: LocatorCheckOptions): Promise<void> {
+    await this.callLocator('uncheck', options === undefined ? [] : [options]);
+  }
+
+  async focus(options?: LocatorFocusOptions): Promise<void> {
+    await this.callLocator('focus', options === undefined ? [] : [options]);
+  }
+
+  async blur(options?: LocatorBlurOptions): Promise<void> {
+    await this.callLocator('blur', options === undefined ? [] : [options]);
+  }
+
+  async scrollIntoViewIfNeeded(
+    options?: LocatorScrollIntoViewIfNeededOptions,
+  ): Promise<void> {
+    await this.callLocator(
+      'scrollIntoViewIfNeeded',
+      options === undefined ? [] : [options],
+    );
+  }
+
+  async waitFor(options?: LocatorWaitForOptions): Promise<void> {
+    await this.callLocator('waitFor', options === undefined ? [] : [options]);
+  }
+
+  async dispatchEvent(
+    type: string,
+    eventInit?: LocatorDispatchEventInit,
+  ): Promise<void> {
+    if (typeof type !== 'string' || !type) {
+      throw new TypeError(
+        'Locator.dispatchEvent() expects a non-empty event type string.',
+      );
+    }
+    await this.callLocator(
+      'dispatchEvent',
+      eventInit === undefined ? [type] : [type, eventInit],
+    );
+  }
+
+  async selectOption(
+    value: string | string[],
+    options?: LocatorSelectOptionOptions,
+  ): Promise<void> {
+    if (
+      typeof value !== 'string' &&
+      !(Array.isArray(value) && value.every((v) => typeof v === 'string'))
+    ) {
+      throw new TypeError(
+        'Locator.selectOption() only supports string or string[] values in browser mode.',
+      );
+    }
+    await this.callLocator(
+      'selectOption',
+      options === undefined ? [value] : [value, options],
+    );
+  }
+
+  async setInputFiles(
+    files: string | string[],
+    options?: LocatorSetInputFilesOptions,
+  ): Promise<void> {
+    if (
+      typeof files !== 'string' &&
+      !(Array.isArray(files) && files.every((v) => typeof v === 'string'))
+    ) {
+      throw new TypeError(
+        'Locator.setInputFiles() only supports file path string or string[] in browser mode.',
+      );
+    }
+    await this.callLocator(
+      'setInputFiles',
+      options === undefined ? [files] : [files, options],
+    );
+  }
+
+  private async callLocator(method: string, args: unknown[]): Promise<void> {
+    await callBrowserRpc<void>({
+      kind: 'locator',
+      locator: this.ir,
+      method,
+      args,
+    } satisfies Omit<BrowserRpcRequest, 'id' | 'testPath' | 'runId'>);
+  }
+}
+
+const browserPageQueryMethods = [
+  'locator',
+  'getByRole',
+  'getByText',
+  'getByLabel',
+  'getByPlaceholder',
+  'getByAltText',
+  'getByTitle',
+  'getByTestId',
+] as const;
+
+type BrowserPageQueryMethod = (typeof browserPageQueryMethods)[number];
+
+export type BrowserPage = Pick<Locator, BrowserPageQueryMethod>;
+
+const rootLocator = new Locator({ steps: [] });
+
+const createBrowserPage = (): BrowserPage => {
+  return Object.fromEntries(
+    browserPageQueryMethods.map((methodName) => {
+      return [methodName, rootLocator[methodName].bind(rootLocator)];
+    }),
+  ) as BrowserPage;
+};
+
+export const page: BrowserPage = createBrowserPage();
+
+export const isLocator = (value: unknown): value is Locator => {
+  return value instanceof Locator;
+};
+
+/**
+ * Configure the attribute used by `getByTestId()` queries.
+ * Forwards to the host provider (e.g. Playwright `selectors.setTestIdAttribute()`).
+ *
+ * @default 'data-testid'
+ */
+export const setTestIdAttribute = async (attribute: string): Promise<void> => {
+  await callBrowserRpc<void>({
+    kind: 'config',
+    locator: { steps: [] },
+    method: 'setTestIdAttribute',
+    args: [attribute],
+  } satisfies Omit<BrowserRpcRequest, 'id' | 'testPath' | 'runId'>);
+};

package/src/client/snapshot.ts

@@ -1,68 +1,27 @@
-import type {
-  BrowserHostConfig,
-  SnapshotRpcRequest,
-  SnapshotRpcResponse,
-} from '../protocol';
+import type { BrowserDispatchRequest, SnapshotRpcRequest } from '../protocol';
+import { DISPATCH_NAMESPACE_SNAPSHOT } from '../protocol';
+import {
+  createRequestId,
+  dispatchRpc,
+  getRpcTimeout,
+} from './dispatchTransport';
 import { mapStackFrame } from './sourceMapSupport';
 
-declare global {
-  interface Window {
-    __RSTEST_BROWSER_OPTIONS__?: BrowserHostConfig;
-  }
-}
-
 const SNAPSHOT_HEADER = '// Rstest Snapshot';
 
-/** Default RPC timeout if not specified in config (30 seconds) */
-const DEFAULT_RPC_TIMEOUT_MS = 30_000;
-
-/**
- * Get RPC timeout from browser options or use default.
- */
-const getRpcTimeout = (): number => {
-  return (
-    window.__RSTEST_BROWSER_OPTIONS__?.rpcTimeout ?? DEFAULT_RPC_TIMEOUT_MS
-  );
-};
-
-/**
- * Pending RPC requests waiting for responses from the container.
- */
-const pendingRequests = new Map<
-  string,
-  {
-    resolve: (value: unknown) => void;
-    reject: (error: Error) => void;
-  }
->();
-
-let requestIdCounter = 0;
-let messageListenerInitialized = false;
-
-/**
- * Initialize the message listener for snapshot RPC responses.
- * This is called once when the first RPC request is made.
- */
-const initMessageListener = (): void => {
-  if (messageListenerInitialized) {
-    return;
-  }
-  messageListenerInitialized = true;
-
-  window.addEventListener('message', (event: MessageEvent) => {
-    if (event.data?.type === '__rstest_snapshot_response__') {
-      const response = event.data.payload as SnapshotRpcResponse;
-      const pending = pendingRequests.get(response.id);
-      if (pending) {
-        pendingRequests.delete(response.id);
-        if (response.error) {
-          pending.reject(new Error(response.error));
-        } else {
-          pending.resolve(response.result);
-        }
-      }
-    }
-  });
+const createSnapshotDispatchRequest = (
+  requestId: string,
+  method: SnapshotRpcRequest['method'],
+  args: SnapshotRpcRequest['args'],
+): BrowserDispatchRequest => {
+  // Snapshot is just one namespace on the shared dispatch RPC channel.
+  // Keep this mapping explicit so new runner-side RPC clients can mirror it.
+  return {
+    requestId,
+    namespace: DISPATCH_NAMESPACE_SNAPSHOT,
+    method,
+    args,
+  };
 };
 
 /**
@@ -73,44 +32,20 @@ const sendRpcRequest = <T>(
   method: SnapshotRpcRequest['method'],
   args: SnapshotRpcRequest['args'],
 ): Promise<T> => {
-  initMessageListener();
-
-  const id = `snapshot-rpc-${++requestIdCounter}`;
+  const requestId = createRequestId('snapshot-rpc');
   const rpcTimeout = getRpcTimeout();
+  const dispatchRequest = createSnapshotDispatchRequest(
+    requestId,
+    method,
+    args,
+  );
 
-  return new Promise<T>((resolve, reject) => {
-    // Set a timeout for the RPC call
-    const timeoutId = setTimeout(() => {
-      pendingRequests.delete(id);
-      reject(
-        new Error(
-          `Snapshot RPC timeout after ${rpcTimeout / 1000}s: ${method}`,
-        ),
-      );
-    }, rpcTimeout);
-
-    pendingRequests.set(id, {
-      resolve: (value) => {
-        clearTimeout(timeoutId);
-        resolve(value as T);
-      },
-      reject: (error) => {
-        clearTimeout(timeoutId);
-        reject(error);
-      },
-    });
-
-    // Send request to parent window (container)
-    window.parent.postMessage(
-      {
-        type: '__rstest_dispatch__',
-        payload: {
-          type: 'snapshot-rpc-request',
-          payload: { id, method, args },
-        },
-      },
-      '*',
-    );
+  return dispatchRpc<T>({
+    requestId,
+    request: dispatchRequest,
+    timeoutMs: rpcTimeout,
+    staleMessage: 'Stale snapshot RPC request ignored.',
+    timeoutMessage: `Snapshot RPC timeout after ${rpcTimeout / 1000}s: ${method}`,
   });
 };
 

package/src/client/sourceMapSupport.ts

@@ -1,8 +1,13 @@
 import { originalPositionFor, TraceMap } from '@jridgewell/trace-mapping';
-import convert from 'convert-source-map';
+import {
+  loadSourceMapWithCache,
+  normalizeJavaScriptUrl,
+  type SourceMapPayload,
+} from '../sourceMap/sourceMapLoader';
 
 // Source map cache: JS URL → TraceMap
 const sourceMapCache = new Map<string, TraceMap | null>();
+const sourceMapPayloadCache = new Map<string, SourceMapPayload | null>();
 
 /**
  * Get TraceMap for specified URL (sync cache lookup)
@@ -23,40 +28,23 @@ const preloadSourceMap = async (
   jsUrl: string,
   force = false,
 ): Promise<void> => {
-  if (!force && sourceMapCache.has(jsUrl)) return;
-
-  try {
-    // First, fetch JS file and try to extract inline source map
-    const jsResponse = await fetch(jsUrl);
-    if (!jsResponse.ok) {
-      sourceMapCache.set(jsUrl, null);
-      return;
-    }
-
-    const code = await jsResponse.text();
+  const normalizedUrl = normalizeJavaScriptUrl(jsUrl, {
+    origin: window.location.origin,
+  });
+  if (!normalizedUrl) {
+    return;
+  }
 
-    // Try to extract inline source map using convert-source-map
-    const inlineConverter = convert.fromSource(code);
-    if (inlineConverter) {
-      const mapObject = inlineConverter.toObject();
-      sourceMapCache.set(jsUrl, new TraceMap(mapObject));
-      return;
-    }
+  if (!force && sourceMapCache.has(normalizedUrl)) return;
 
-    // Fallback: try to fetch external .map file
-    const mapUrl = `${jsUrl}.map`;
-    const mapResponse = await fetch(mapUrl);
-    if (mapResponse.ok) {
-      const mapJson = await mapResponse.json();
-      sourceMapCache.set(jsUrl, new TraceMap(mapJson));
-      return;
-    }
+  const sourceMap = await loadSourceMapWithCache({
+    jsUrl: normalizedUrl,
+    cache: sourceMapPayloadCache,
+    force,
+    origin: window.location.origin,
+  });
 
-    // No source map found
-    sourceMapCache.set(jsUrl, null);
-  } catch {
-    sourceMapCache.set(jsUrl, null);
-  }
+  sourceMapCache.set(normalizedUrl, sourceMap ? new TraceMap(sourceMap) : null);
 };
 
 /**
@@ -128,6 +116,7 @@ export const preloadRunnerSourceMap = async (): Promise<void> => {
  */
 export const clearCache = (): void => {
   sourceMapCache.clear();
+  sourceMapPayloadCache.clear();
 };
 
 /**
@@ -147,11 +136,11 @@ export interface StackFrame {
 export const mapStackFrame = (frame: StackFrame): StackFrame => {
   const { file, line, column } = frame;
 
-  // Normalize file path to full URL for cache lookup
-  let fullUrl = file;
-  if (!file.startsWith('http://') && !file.startsWith('https://')) {
-    // Convert relative path to full URL
-    fullUrl = `${window.location.origin}${file.startsWith('/') ? '' : '/'}${file}`;
+  const fullUrl = normalizeJavaScriptUrl(file, {
+    origin: window.location.origin,
+  });
+  if (!fullUrl) {
+    return frame;
   }
 
   const traceMap = getSourceMap(fullUrl);