@rstest/browser 0.7.9

package/src/client/public.ts

@@ -0,0 +1,12 @@
+/**
+ * Re-export runtime API from @rstest/core/browser-runtime for browser use.
+ * This file is used as an alias target for '@rstest/core' in browser mode.
+ *
+ * Uses @rstest/core/browser-runtime which only exports the test APIs
+ * (describe, it, expect, etc.) without any Node.js dependencies.
+ */
+
+// Re-export types from @rstest/core (these are compile-time only)
+export type { Assertion, Mock } from '@rstest/core';
+// Re-export all public test APIs
+export * from '@rstest/core/browser-runtime';

package/src/client/snapshot.ts

@@ -0,0 +1,177 @@
+import type {
+  BrowserHostConfig,
+  SnapshotRpcRequest,
+  SnapshotRpcResponse,
+} from '../protocol';
+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);
+        }
+      }
+    }
+  });
+};
+
+/**
+ * Send a snapshot RPC request to the container (parent window).
+ * The container will forward it to the host via WebSocket RPC.
+ */
+const sendRpcRequest = <T>(
+  method: SnapshotRpcRequest['method'],
+  args: SnapshotRpcRequest['args'],
+): Promise<T> => {
+  initMessageListener();
+
+  const id = `snapshot-rpc-${++requestIdCounter}`;
+  const rpcTimeout = getRpcTimeout();
+
+  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 },
+        },
+      },
+      '*',
+    );
+  });
+};
+
+/**
+ * Browser snapshot environment that proxies file operations to the host
+ * via postMessage RPC through the container.
+ */
+export class BrowserSnapshotEnvironment {
+  getVersion(): string {
+    return '1';
+  }
+
+  getHeader(): string {
+    return `${SNAPSHOT_HEADER} v${this.getVersion()}`;
+  }
+
+  async resolveRawPath(_testPath: string, rawPath: string): Promise<string> {
+    return rawPath;
+  }
+
+  async resolvePath(filepath: string): Promise<string> {
+    return sendRpcRequest<string>('resolveSnapshotPath', {
+      testPath: filepath,
+    });
+  }
+
+  async prepareDirectory(): Promise<void> {
+    // Directory creation is handled by saveSnapshotFile on the host
+  }
+
+  async saveSnapshotFile(filepath: string, snapshot: string): Promise<void> {
+    await sendRpcRequest<void>('saveSnapshotFile', {
+      filepath,
+      content: snapshot,
+    });
+  }
+
+  async readSnapshotFile(filepath: string): Promise<string | null> {
+    return sendRpcRequest<string | null>('readSnapshotFile', { filepath });
+  }
+
+  async removeSnapshotFile(filepath: string): Promise<void> {
+    await sendRpcRequest<void>('removeSnapshotFile', { filepath });
+  }
+
+  /**
+   * Process stack trace for inline snapshots.
+   * Maps bundled URLs back to original source file paths.
+   */
+  processStackTrace(stack: {
+    file: string;
+    line: number;
+    column: number;
+    method: string;
+  }): { file: string; line: number; column: number; method: string } {
+    const mapped = mapStackFrame(stack);
+    return {
+      file: mapped.file,
+      line: mapped.line,
+      column: mapped.column,
+      method: mapped.method || stack.method,
+    };
+  }
+}

package/src/client/sourceMapSupport.ts

@@ -0,0 +1,178 @@
+import { originalPositionFor, TraceMap } from '@jridgewell/trace-mapping';
+import convert from 'convert-source-map';
+
+// Source map cache: JS URL → TraceMap
+const sourceMapCache = new Map<string, TraceMap | null>();
+
+/**
+ * Get TraceMap for specified URL (sync cache lookup)
+ */
+const getSourceMap = (url: string): TraceMap | null => {
+  return sourceMapCache.get(url) ?? null;
+};
+
+/**
+ * Preload source map for specified JS URL.
+ * First tries to extract inline source map from JS code,
+ * then falls back to fetching external .map file.
+ *
+ * @param jsUrl - The URL of the JS file
+ * @param force - If true, bypass cache and always fetch fresh source map
+ */
+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();
+
+    // 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;
+    }
+
+    // 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;
+    }
+
+    // No source map found
+    sourceMapCache.set(jsUrl, null);
+  } catch {
+    sourceMapCache.set(jsUrl, null);
+  }
+};
+
+/**
+ * Get all script URLs currently on the page.
+ * Used to detect newly loaded chunk scripts.
+ */
+export const getScriptUrls = (): Set<string> => {
+  const scripts = document.querySelectorAll('script[src]');
+  const urls = new Set<string>();
+  for (const script of scripts) {
+    const src = script.getAttribute('src');
+    if (src) {
+      // Normalize to full URL
+      const fullUrl = src.startsWith('http')
+        ? src
+        : `${window.location.origin}${src.startsWith('/') ? '' : '/'}${src}`;
+      urls.add(fullUrl);
+    }
+  }
+  return urls;
+};
+
+/**
+ * Find the newly added script URL by comparing script sets.
+ * Returns the first new script URL found, or null if none.
+ */
+export const findNewScriptUrl = (
+  beforeUrls: Set<string>,
+  afterUrls: Set<string>,
+): string | null => {
+  for (const url of afterUrls) {
+    if (!beforeUrls.has(url)) {
+      return url;
+    }
+  }
+  return null;
+};
+
+/**
+ * Preload source map for a test file's chunk URL.
+ *
+ * Always fetches fresh source map to handle file changes during watch mode.
+ *
+ * @param chunkUrl - The full URL of the chunk JS file
+ */
+export const preloadTestFileSourceMap = async (
+  chunkUrl: string,
+): Promise<void> => {
+  // Always force refresh to ensure we have the latest source map
+  // This handles the case where user saves file during test execution
+  await preloadSourceMap(chunkUrl, true);
+};
+
+/**
+ * Preload source map for the runner.js file.
+ *
+ * This is essential for inline snapshot support because the snapshot code
+ * runs in runner.js (which contains @rstest/core/browser-runtime).
+ * Without this, stack traces from inline snapshots cannot be mapped back
+ * to the original source files.
+ */
+export const preloadRunnerSourceMap = async (): Promise<void> => {
+  const runnerUrl = `${window.location.origin}/static/js/runner.js`;
+  await preloadSourceMap(runnerUrl);
+};
+
+/**
+ * Clear cache (for testing purposes)
+ */
+export const clearCache = (): void => {
+  sourceMapCache.clear();
+};
+
+/**
+ * Stack frame interface matching @vitest/snapshot's format
+ */
+export interface StackFrame {
+  file: string;
+  line: number;
+  column: number;
+  method?: string;
+}
+
+/**
+ * Map a stack frame from bundled URL to original source file.
+ * This is used by BrowserSnapshotEnvironment.processStackTrace
+ */
+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 traceMap = getSourceMap(fullUrl);
+  if (!traceMap) {
+    return frame;
+  }
+
+  const pos = originalPositionFor(traceMap, {
+    line,
+    column: column - 1, // source map uses 0-based column
+  });
+
+  if (pos.source && pos.line != null && pos.column != null) {
+    return {
+      ...frame,
+      file: pos.source,
+      line: pos.line,
+      column: pos.column + 1, // convert back to 1-based
+      method: pos.name || frame.method,
+    };
+  }
+
+  return frame;
+};

package/src/env.d.ts

@@ -0,0 +1,43 @@
+import type { BrowserClientMessage, BrowserHostConfig } from './protocol';
+
+declare module '@rstest/browser-manifest' {
+  export type ManifestProjectConfig = {
+    name: string;
+    environmentName: string;
+    projectRoot: string;
+  };
+
+  export type ManifestTestContext = {
+    getTestKeys: () => string[];
+    loadTest: (key: string) => Promise<unknown>;
+    projectRoot: string;
+  };
+
+  export const projects: ManifestProjectConfig[];
+
+  export const projectSetupLoaders: Record<
+    string,
+    Array<() => Promise<unknown>>
+  >;
+
+  export const projectTestContexts: Record<string, ManifestTestContext>;
+
+  // Backward compatibility exports
+  export const projectConfig: ManifestProjectConfig | undefined;
+  export const setupLoaders: Array<() => Promise<unknown>>;
+  export const getTestKeys: () => string[];
+  export const loadTest: (key: string) => Promise<unknown>;
+}
+
+declare global {
+  const RSTEST_VERSION: string;
+
+  interface Window {
+    __RSTEST_BROWSER_OPTIONS__?: BrowserHostConfig;
+    __rstest_dispatch__?: (message: BrowserClientMessage) => void;
+    __rstest_container_dispatch__?: (data: unknown) => void;
+    __rstest_container_on__?: (data: unknown) => void;
+    __RSTEST_DONE__?: boolean;
+    __RSTEST_TEST_FILES__?: string[];
+  }
+}