@rstest/browser 0.8.5 → 0.9.1

package/src/concurrency.ts

@@ -0,0 +1,62 @@
+import os from 'node:os';
+import type { Rstest } from '@rstest/core/browser';
+
+// Shared headless concurrency policy.
+// Keep this in one place so executors reuse the same worker semantics.
+const DEFAULT_MAX_HEADLESS_WORKERS = 12;
+
+export type HeadlessConcurrencyContext = Pick<Rstest, 'command'> & {
+  normalizedConfig: {
+    pool: {
+      maxWorkers?: string | number;
+    };
+  };
+};
+
+export const getNumCpus = (): number => {
+  return os.availableParallelism?.() ?? os.cpus().length;
+};
+
+export const parseWorkers = (
+  maxWorkers: string | number,
+  numCpus = getNumCpus(),
+): number => {
+  const parsed = Number.parseInt(maxWorkers.toString(), 10);
+
+  if (typeof maxWorkers === 'string' && maxWorkers.trim().endsWith('%')) {
+    const workers = Math.floor((parsed / 100) * numCpus);
+    return Math.max(workers, 1);
+  }
+
+  return parsed > 0 ? parsed : 1;
+};
+
+export const resolveDefaultHeadlessWorkers = (
+  command: HeadlessConcurrencyContext['command'],
+  numCpus = getNumCpus(),
+): number => {
+  const baseWorkers = Math.max(
+    Math.min(DEFAULT_MAX_HEADLESS_WORKERS, numCpus - 1),
+    1,
+  );
+
+  return command === 'watch'
+    ? Math.max(Math.floor(baseWorkers / 2), 1)
+    : baseWorkers;
+};
+
+export const getHeadlessConcurrency = (
+  context: HeadlessConcurrencyContext,
+  totalTests: number,
+): number => {
+  if (totalTests <= 0) {
+    return 1;
+  }
+
+  const maxWorkers = context.normalizedConfig.pool.maxWorkers;
+  if (maxWorkers !== undefined) {
+    return Math.min(parseWorkers(maxWorkers), totalTests);
+  }
+
+  return Math.min(resolveDefaultHeadlessWorkers(context.command), totalTests);
+};

package/src/dispatchCapabilities.ts

@@ -0,0 +1,162 @@
+import type { Reporter } from '@rstest/core/browser';
+import { HostDispatchRouter } from './dispatchRouter';
+import type {
+  BrowserClientMessage,
+  BrowserDispatchHandler,
+  BrowserDispatchRequest,
+  SnapshotRpcRequest,
+} from './protocol';
+
+export type HostDispatchRouterOptions = ConstructorParameters<
+  typeof HostDispatchRouter
+>[0];
+
+type RunnerPayload<TType extends BrowserClientMessage['type']> =
+  Extract<BrowserClientMessage, { type: TType }> extends {
+    payload: infer TPayload;
+  }
+    ? TPayload
+    : never;
+
+type ReporterHookArg<THook extends keyof Reporter> = Parameters<
+  NonNullable<Reporter[THook]>
+>[0];
+
+type RunnerDispatchFileReadyPayload = ReporterHookArg<'onTestFileReady'>;
+type RunnerDispatchSuiteStartPayload = ReporterHookArg<'onTestSuiteStart'>;
+type RunnerDispatchSuiteResultPayload = ReporterHookArg<'onTestSuiteResult'>;
+type RunnerDispatchCaseStartPayload = ReporterHookArg<'onTestCaseStart'>;
+
+export type RunnerDispatchCallbacks = {
+  onTestFileStart: (payload: RunnerPayload<'file-start'>) => Promise<void>;
+  onTestFileReady: (payload: RunnerDispatchFileReadyPayload) => Promise<void>;
+  onTestSuiteStart: (payload: RunnerDispatchSuiteStartPayload) => Promise<void>;
+  onTestSuiteResult: (
+    payload: RunnerDispatchSuiteResultPayload,
+  ) => Promise<void>;
+  onTestCaseStart: (payload: RunnerDispatchCaseStartPayload) => Promise<void>;
+  onTestCaseResult: (payload: RunnerPayload<'case-result'>) => Promise<void>;
+  onTestFileComplete: (
+    payload: RunnerPayload<'file-complete'>,
+  ) => Promise<void>;
+  onLog: (payload: RunnerPayload<'log'>) => Promise<void>;
+  onFatal: (payload: RunnerPayload<'fatal'>) => Promise<void>;
+};
+
+type CreateHostDispatchRouterOptions = {
+  routerOptions?: HostDispatchRouterOptions;
+  runnerCallbacks: RunnerDispatchCallbacks;
+  runSnapshotRpc: (request: SnapshotRpcRequest) => Promise<unknown>;
+  extensionHandlers?: Map<string, BrowserDispatchHandler>;
+  onDuplicateNamespace?: (namespace: string) => void;
+};
+
+const toSnapshotRpcRequest = (
+  request: BrowserDispatchRequest,
+): SnapshotRpcRequest | null => {
+  switch (request.method) {
+    case 'resolveSnapshotPath':
+      return {
+        id: request.requestId,
+        method: 'resolveSnapshotPath',
+        args: request.args as { testPath: string },
+      };
+    case 'readSnapshotFile':
+      return {
+        id: request.requestId,
+        method: 'readSnapshotFile',
+        args: request.args as { filepath: string },
+      };
+    case 'saveSnapshotFile':
+      return {
+        id: request.requestId,
+        method: 'saveSnapshotFile',
+        args: request.args as { filepath: string; content: string },
+      };
+    case 'removeSnapshotFile':
+      return {
+        id: request.requestId,
+        method: 'removeSnapshotFile',
+        args: request.args as { filepath: string },
+      };
+    default:
+      return null;
+  }
+};
+
+export const createHostDispatchRouter = ({
+  routerOptions,
+  runnerCallbacks,
+  runSnapshotRpc,
+  extensionHandlers,
+  onDuplicateNamespace,
+}: CreateHostDispatchRouterOptions): HostDispatchRouter => {
+  const router = new HostDispatchRouter(routerOptions);
+
+  router.register('runner', async (request: BrowserDispatchRequest) => {
+    switch (request.method) {
+      case 'file-start':
+        await runnerCallbacks.onTestFileStart(
+          request.args as RunnerPayload<'file-start'>,
+        );
+        break;
+      case 'file-ready':
+        await runnerCallbacks.onTestFileReady(
+          request.args as RunnerDispatchFileReadyPayload,
+        );
+        break;
+      case 'suite-start':
+        await runnerCallbacks.onTestSuiteStart(
+          request.args as RunnerDispatchSuiteStartPayload,
+        );
+        break;
+      case 'suite-result':
+        await runnerCallbacks.onTestSuiteResult(
+          request.args as RunnerDispatchSuiteResultPayload,
+        );
+        break;
+      case 'case-start':
+        await runnerCallbacks.onTestCaseStart(
+          request.args as RunnerDispatchCaseStartPayload,
+        );
+        break;
+      case 'case-result':
+        await runnerCallbacks.onTestCaseResult(
+          request.args as RunnerPayload<'case-result'>,
+        );
+        break;
+      case 'file-complete':
+        await runnerCallbacks.onTestFileComplete(
+          request.args as RunnerPayload<'file-complete'>,
+        );
+        break;
+      case 'log':
+        await runnerCallbacks.onLog(request.args as RunnerPayload<'log'>);
+        break;
+      case 'fatal':
+        await runnerCallbacks.onFatal(request.args as RunnerPayload<'fatal'>);
+        break;
+      default:
+        break;
+    }
+  });
+
+  router.register('snapshot', async (request: BrowserDispatchRequest) => {
+    const snapshotRequest = toSnapshotRpcRequest(request);
+    if (!snapshotRequest) {
+      return undefined;
+    }
+    return runSnapshotRpc(snapshotRequest);
+  });
+
+  for (const [namespace, handler] of extensionHandlers ?? []) {
+    if (router.has(namespace)) {
+      onDuplicateNamespace?.(namespace);
+      continue;
+    }
+
+    router.register(namespace, handler);
+  }
+
+  return router;
+};

package/src/dispatchRouter.ts

@@ -0,0 +1,82 @@
+import type {
+  BrowserDispatchRequest,
+  BrowserDispatchResponse,
+} from './protocol';
+
+type DispatchHandler = (request: BrowserDispatchRequest) => Promise<unknown>;
+
+type HostDispatchRouterOptions = {
+  isRunTokenStale?: (runToken: number) => boolean;
+  onStale?: (request: BrowserDispatchRequest) => void;
+};
+
+const toErrorMessage = (error: unknown): string => {
+  return error instanceof Error ? error.message : String(error);
+};
+
+/**
+ * Host-side routing layer for dispatch envelopes.
+ * Capabilities are registered by namespace, while routing stays transport-agnostic.
+ */
+export class HostDispatchRouter {
+  private handlers = new Map<string, DispatchHandler>();
+  private options: HostDispatchRouterOptions;
+
+  constructor(options?: HostDispatchRouterOptions) {
+    this.options = options ?? {};
+  }
+
+  register(namespace: string, handler: DispatchHandler): void {
+    this.handlers.set(namespace, handler);
+  }
+
+  unregister(namespace: string): void {
+    this.handlers.delete(namespace);
+  }
+
+  has(namespace: string): boolean {
+    return this.handlers.has(namespace);
+  }
+
+  async dispatch(
+    request: BrowserDispatchRequest,
+  ): Promise<BrowserDispatchResponse> {
+    const runToken = request.runToken;
+    if (
+      typeof runToken === 'number' &&
+      this.options.isRunTokenStale?.(runToken)
+    ) {
+      // Return a stale marker so callers can drop old-run writes safely.
+      this.options.onStale?.(request);
+      return {
+        requestId: request.requestId,
+        runToken,
+        stale: true,
+      };
+    }
+
+    const handler = this.handlers.get(request.namespace);
+    if (!handler) {
+      return {
+        requestId: request.requestId,
+        runToken,
+        error: `No dispatch handler registered for namespace "${request.namespace}"`,
+      };
+    }
+
+    try {
+      const result = await handler(request);
+      return {
+        requestId: request.requestId,
+        runToken,
+        result,
+      };
+    } catch (error) {
+      return {
+        requestId: request.requestId,
+        runToken,
+        error: toErrorMessage(error),
+      };
+    }
+  }
+}

package/src/env.d.ts

@@ -1,4 +1,8 @@
-import type { BrowserClientMessage, BrowserHostConfig } from './protocol';
+import type {
+  BrowserClientMessage,
+  BrowserDispatchRequest,
+  BrowserHostConfig,
+} from './protocol';
 
 declare module '@rstest/browser-manifest' {
   export type ManifestProjectConfig = {
@@ -35,6 +39,9 @@ declare global {
   interface Window {
     __RSTEST_BROWSER_OPTIONS__?: BrowserHostConfig;
     __rstest_dispatch__?: (message: BrowserClientMessage) => void;
+    __rstest_dispatch_rpc__?: (
+      request: BrowserDispatchRequest,
+    ) => Promise<unknown>;
     __rstest_container_dispatch__?: (data: unknown) => void;
     __rstest_container_on__?: (data: unknown) => void;
     __RSTEST_DONE__?: boolean;

package/src/headedSerialTaskQueue.ts

@@ -0,0 +1,19 @@
+export type HeadedSerialTask = () => Promise<void>;
+
+/**
+ * Serializes headed browser file execution so only one task runs at a time.
+ * The queue keeps draining even if an earlier task rejects.
+ */
+export const createHeadedSerialTaskQueue = () => {
+  let queue: Promise<void> = Promise.resolve();
+
+  const enqueue = (task: HeadedSerialTask): Promise<void> => {
+    const next = queue.then(task);
+    queue = next.catch(() => {});
+    return next;
+  };
+
+  return {
+    enqueue,
+  };
+};

package/src/headlessLatestRerunScheduler.ts

@@ -0,0 +1,76 @@
+export type HeadlessLatestRerunScheduler<TFile> = {
+  enqueueLatest: (files: TFile[]) => Promise<void>;
+  whenIdle: () => Promise<void>;
+};
+
+type HeadlessLatestRerunSchedulerOptions<TFile, TRun> = {
+  getActiveRun: () => TRun | null;
+  isRunCancelled: (run: TRun) => boolean;
+  invalidateActiveRun: () => void;
+  interruptActiveRun: (run: TRun) => Promise<void>;
+  runFiles: (files: TFile[]) => Promise<void>;
+  onError?: (error: unknown) => Promise<void> | void;
+  onInterrupt?: (run: TRun) => void;
+};
+
+/**
+ * Latest-only rerun scheduler for headless watch mode.
+ * Keeps only the newest pending payload and interrupts active run generations.
+ */
+export const createHeadlessLatestRerunScheduler = <TFile, TRun>(
+  options: HeadlessLatestRerunSchedulerOptions<TFile, TRun>,
+): HeadlessLatestRerunScheduler<TFile> => {
+  let pendingFiles: TFile[] | null = null;
+  let draining: Promise<void> | null = null;
+  let latestEnqueueVersion = 0;
+
+  const runDrainLoop = async (): Promise<void> => {
+    while (pendingFiles) {
+      const nextFiles = pendingFiles;
+      pendingFiles = null;
+
+      try {
+        await options.runFiles(nextFiles);
+      } catch (error) {
+        try {
+          await options.onError?.(error);
+        } catch {
+          // Keep draining even if error reporting fails.
+        }
+      }
+    }
+  };
+
+  const ensureDrainLoop = (): void => {
+    if (draining) {
+      return;
+    }
+
+    draining = runDrainLoop().finally(() => {
+      draining = null;
+    });
+  };
+
+  return {
+    async enqueueLatest(files: TFile[]): Promise<void> {
+      const enqueueVersion = ++latestEnqueueVersion;
+      const activeRun = options.getActiveRun();
+      if (activeRun && !options.isRunCancelled(activeRun)) {
+        options.onInterrupt?.(activeRun);
+        options.invalidateActiveRun();
+        await options.interruptActiveRun(activeRun);
+      }
+
+      // If a newer enqueue arrived while interrupting, drop this stale payload.
+      if (enqueueVersion !== latestEnqueueVersion) {
+        return;
+      }
+
+      pendingFiles = files;
+      ensureDrainLoop();
+    },
+    async whenIdle(): Promise<void> {
+      await draining;
+    },
+  };
+};

package/src/headlessTransport.ts

@@ -0,0 +1,28 @@
+import type {
+  BrowserClientMessage,
+  BrowserDispatchRequest,
+  BrowserDispatchResponse,
+} from './protocol';
+import { DISPATCH_MESSAGE_TYPE, DISPATCH_RPC_BRIDGE_NAME } from './protocol';
+import type { BrowserProviderPage } from './providers';
+
+type HeadlessRunnerTransportHandlers = {
+  onDispatchMessage: (message: BrowserClientMessage) => Promise<void>;
+  onDispatchRpc: (
+    request: BrowserDispatchRequest,
+  ) => Promise<BrowserDispatchResponse>;
+};
+
+/**
+ * Headless transport adapter.
+ * This only binds page bridge functions and delegates all scheduling decisions upstream.
+ */
+export const attachHeadlessRunnerTransport = async (
+  page: BrowserProviderPage,
+  handlers: HeadlessRunnerTransportHandlers,
+): Promise<void> => {
+  // Fire-and-forget runner lifecycle messages (ready/log/result/fatal).
+  await page.exposeFunction(DISPATCH_MESSAGE_TYPE, handlers.onDispatchMessage);
+  // Request/response RPC bridge shared by snapshot and future namespaces.
+  await page.exposeFunction(DISPATCH_RPC_BRIDGE_NAME, handlers.onDispatchRpc);
+};