@rstest/browser 0.9.2 → 0.9.4

package/src/hostController.ts

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { AddressInfo } from 'node:net';
 import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
 import type { Rspack } from '@rstest/core';
 import {
   type BrowserTestRunOptions,
@@ -30,7 +31,7 @@ import {
 import { type BirpcReturn, createBirpc } from 'birpc';
 import openEditor from 'open-editor';
 import { basename, dirname, join, normalize, relative, resolve } from 'pathe';
-import * as picomatch from 'picomatch';
+import picomatch from 'picomatch';
 import sirv from 'sirv';
 import { type WebSocket, WebSocketServer } from 'ws';
 import { getHeadlessConcurrency } from './concurrency';
@@ -123,10 +124,24 @@ type BrowserProviderProject = {
   provider: BrowserProvider;
 };
 
-type BrowserLaunchOptions = Pick<
-  ProjectContext['normalizedConfig']['browser'],
-  'provider' | 'browser' | 'headless' | 'port' | 'strictPort'
->;
+type BrowserLaunchOptions = {
+  provider: BrowserProvider;
+  browser: ProjectContext['normalizedConfig']['browser']['browser'];
+  headless: ProjectContext['normalizedConfig']['browser']['headless'];
+  port: ProjectContext['normalizedConfig']['browser']['port'];
+  strictPort: ProjectContext['normalizedConfig']['browser']['strictPort'];
+  providerOptions: Record<string, unknown>;
+};
+
+const getBrowserProviderOptions = (
+  project: ProjectContext,
+): Record<string, unknown> => {
+  const browserConfig = project.normalizedConfig.browser as {
+    providerOptions?: Record<string, unknown>;
+  };
+
+  return browserConfig.providerOptions ?? {};
+};
 
 /** Payload for test file start event */
 type TestFileStartPayload = {
@@ -157,6 +172,33 @@ type TestFileReadyPayload = ReporterHookArg<'onTestFileReady'>;
 type TestSuiteStartPayload = ReporterHookArg<'onTestSuiteStart'>;
 type TestSuiteResultPayload = ReporterHookArg<'onTestSuiteResult'>;
 type TestCaseStartPayload = ReporterHookArg<'onTestCaseStart'>;
+type ReloadTestFileAck = {
+  runId: string;
+};
+type HeadedTestFileCompletePayload = TestFileResult & {
+  runId?: string;
+};
+
+type DeferredPromise<T> = {
+  promise: Promise<T>;
+  resolve: (value: T | PromiseLike<T>) => void;
+  reject: (reason?: unknown) => void;
+};
+
+const createDeferredPromise = <T>(): DeferredPromise<T> => {
+  let resolve!: DeferredPromise<T>['resolve'];
+  let reject!: DeferredPromise<T>['reject'];
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return {
+    promise,
+    resolve,
+    reject,
+  };
+};
 
 /** RPC methods exposed by the host (server) to the container (client) */
 type HostRpcMethods = {
@@ -166,7 +208,7 @@ type HostRpcMethods = {
   // Test result callbacks from container
   onTestFileStart: (payload: TestFileStartPayload) => Promise<void>;
   onTestCaseResult: (payload: TestResult) => Promise<void>;
-  onTestFileComplete: (payload: TestFileResult) => Promise<void>;
+  onTestFileComplete: (payload: HeadedTestFileCompletePayload) => Promise<void>;
   onLog: (payload: LogPayload) => Promise<void>;
   onFatal: (payload: FatalPayload) => Promise<void>;
   // Generic dispatch endpoint used by runner RPC requests.
@@ -178,7 +220,10 @@ type HostRpcMethods = {
 /** RPC methods exposed by the container (client) to the host (server) */
 type ContainerRpcMethods = {
   onTestFileUpdate: (testFiles: TestFileInfo[]) => Promise<void>;
-  reloadTestFile: (testFile: string, testNamePattern?: string) => Promise<void>;
+  reloadTestFile: (
+    testFile: string,
+    testNamePattern?: string,
+  ) => Promise<ReloadTestFileAck>;
 };
 
 type ContainerRpc = BirpcReturn<ContainerRpcMethods, HostRpcMethods>;
@@ -196,16 +241,27 @@ class ContainerRpcManager {
   private ws: WebSocket | null = null;
   private rpc: ContainerRpc | null = null;
   private methods: HostRpcMethods;
+  private onDisconnect?: (error: Error) => void;
+  private detachActiveSocketListeners: (() => void) | null = null;
 
-  constructor(wss: WebSocketServer, methods: HostRpcMethods) {
+  constructor(
+    wss: WebSocketServer,
+    methods: HostRpcMethods,
+    onDisconnect?: (error: Error) => void,
+  ) {
     this.wss = wss;
     this.methods = methods;
+    this.onDisconnect = onDisconnect;
     this.setupConnectionHandler();
   }
 
   /** Update the RPC methods (used when starting a new test run) */
-  updateMethods(methods: HostRpcMethods): void {
+  updateMethods(
+    methods: HostRpcMethods,
+    onDisconnect?: (error: Error) => void,
+  ): void {
     this.methods = methods;
+    this.onDisconnect = onDisconnect;
     // Re-create birpc with new methods if already connected
     if (this.ws && this.ws.readyState === this.ws.OPEN) {
       this.attachWebSocket(this.ws);
@@ -223,35 +279,68 @@ class ContainerRpcManager {
   }
 
   private attachWebSocket(ws: WebSocket): void {
+    this.detachActiveSocketListeners?.();
+    if (this.rpc && !this.rpc.$closed) {
+      this.rpc.$close(new Error('Container RPC transport reattached'));
+    }
     this.ws = ws;
+    const messageHandlers = new WeakMap<
+      (data: any) => void,
+      (message: any) => void
+    >();
 
     this.rpc = createBirpc<ContainerRpcMethods, HostRpcMethods>(this.methods, {
+      timeout: -1,
       post: (data) => {
         if (ws.readyState === ws.OPEN) {
           ws.send(JSON.stringify(data));
         }
       },
       on: (fn) => {
-        ws.on('message', (message) => {
+        const handler = (message: any) => {
           try {
             const data = JSON.parse(message.toString());
             fn(data);
           } catch {
             // ignore invalid messages
           }
-        });
+        };
+        messageHandlers.set(fn, handler);
+        ws.on('message', handler);
+      },
+      off: (fn) => {
+        const handler = messageHandlers.get(fn);
+        if (!handler) {
+          return;
+        }
+        ws.off('message', handler);
+        messageHandlers.delete(fn);
       },
     });
 
-    ws.on('close', () => {
+    const handleClose = () => {
       // Only clear if this is still the active connection
       // This prevents a race condition when a new connection is established
       // before the old one's close event fires
       if (this.ws === ws) {
         this.ws = null;
-        this.rpc = null;
       }
-    });
+      this.detachActiveSocketListeners?.();
+      this.detachActiveSocketListeners = null;
+      if (this.rpc && !this.rpc.$closed) {
+        const disconnectError = new Error(
+          'Browser UI WebSocket disconnected before reload completed',
+        );
+        this.rpc.$close(disconnectError);
+        this.onDisconnect?.(disconnectError);
+      }
+      this.rpc = null;
+    };
+
+    ws.on('close', handleClose);
+    this.detachActiveSocketListeners = () => {
+      ws.off('close', handleClose);
+    };
   }
 
   /** Check if a container is currently connected */
@@ -278,16 +367,15 @@ class ContainerRpcManager {
   async reloadTestFile(
     testFile: string,
     testNamePattern?: string,
-  ): Promise<void> {
+  ): Promise<ReloadTestFileAck> {
     logger.debug(
       `[Browser UI] reloadTestFile called, rpc: ${this.rpc ? 'exists' : 'null'}, ws: ${this.ws ? 'exists' : 'null'}`,
     );
     if (!this.rpc) {
-      logger.debug('[Browser UI] RPC not available, skipping reloadTestFile');
-      return;
+      throw new Error('Browser UI RPC not available for reloadTestFile');
     }
     logger.debug(`[Browser UI] Calling reloadTestFile: ${testFile}`);
-    await this.rpc.reloadTestFile(testFile, testNamePattern);
+    return this.rpc.reloadTestFile(testFile, testNamePattern);
   }
 }
 
@@ -299,6 +387,7 @@ type BrowserRuntime = {
   rsbuildInstance: RsbuildInstance;
   devServer: RsbuildDevServer;
   browser: BrowserProviderBrowser;
+  browserLaunchOptions: BrowserLaunchOptions;
   port: number;
   wsPort: number;
   manifestPath: string;
@@ -724,6 +813,7 @@ const getBrowserLaunchOptions = (
   headless: project.normalizedConfig.browser.headless,
   port: project.normalizedConfig.browser.port,
   strictPort: project.normalizedConfig.browser.strictPort,
+  providerOptions: getBrowserProviderOptions(project),
 });
 
 const ensureConsistentBrowserLaunchOptions = (
@@ -743,11 +833,12 @@ const ensureConsistentBrowserLaunchOptions = (
       options.browser !== firstOptions.browser ||
       options.headless !== firstOptions.headless ||
       options.port !== firstOptions.port ||
-      options.strictPort !== firstOptions.strictPort
+      options.strictPort !== firstOptions.strictPort ||
+      !isDeepStrictEqual(options.providerOptions, firstOptions.providerOptions)
     ) {
       throw new Error(
         `Browser launch config mismatch between projects "${firstProject.name}" and "${project.name}". ` +
-          'All browser-enabled projects in one run must share provider/browser/headless/port/strictPort.',
+          'All browser-enabled projects in one run must share provider/browser/headless/port/strictPort/providerOptions.',
       );
     }
   }
@@ -782,35 +873,33 @@ const resolveProviderForTestPath = ({
 const collectProjectEntries = async (
   context: Rstest,
 ): Promise<BrowserProjectEntries[]> => {
-  const projectEntries: BrowserProjectEntries[] = [];
-
   // Only collect entries for browser mode projects
   const browserProjects = getBrowserProjects(context);
 
-  for (const project of browserProjects) {
-    const {
-      normalizedConfig: { include, exclude, includeSource, setupFiles },
-    } = project;
-
-    const tests = await getTestEntries({
-      include,
-      exclude: exclude.patterns,
-      includeSource,
-      rootPath: context.rootPath,
-      projectRoot: project.rootPath,
-      fileFilters: context.fileFilters || [],
-    });
-
-    const setup = getSetupFiles(setupFiles, project.rootPath);
+  return Promise.all(
+    browserProjects.map(async (project) => {
+      const {
+        normalizedConfig: { include, exclude, includeSource, setupFiles },
+      } = project;
+
+      const tests = await getTestEntries({
+        include,
+        exclude: exclude.patterns,
+        includeSource,
+        rootPath: context.rootPath,
+        projectRoot: project.rootPath,
+        fileFilters: context.fileFilters || [],
+      });
 
-    projectEntries.push({
-      project,
-      setupFiles: Object.values(setup),
-      testFiles: Object.values(tests),
-    });
-  }
+      const setup = getSetupFiles(setupFiles, project.rootPath);
 
-  return projectEntries;
+      return {
+        project,
+        setupFiles: Object.values(setup),
+        testFiles: Object.values(tests),
+      };
+    }),
+  );
 };
 
 const resolveBrowserFile = (relativePath: string): string => {
@@ -1469,11 +1558,13 @@ const createBrowserRuntime = async ({
     const runtime = await providerImplementation.launchRuntime({
       browserName,
       headless: forceHeadless ?? browserLaunchOptions.headless,
+      providerOptions: browserLaunchOptions.providerOptions,
     });
     return {
       rsbuildInstance,
       devServer,
       browser: runtime.browser,
+      browserLaunchOptions,
       port,
       wsPort,
       manifestPath,
@@ -1802,7 +1893,7 @@ export const runBrowserController = async (
     }
   }
 
-  const { browser, port, wsPort, wss } = runtime;
+  const { browser, browserLaunchOptions, port, wsPort, wss } = runtime;
   const buildTime = Date.now() - buildStart;
 
   // Collect all test files from project entries with project info
@@ -2208,6 +2299,7 @@ export const runBrowserController = async (
 
       const viewport = viewportByProject.get(file.projectName);
       const browserContext = await browser.newContext({
+        providerOptions: browserLaunchOptions.providerOptions,
         viewport: viewport ?? null,
       });
       run.contexts.add(browserContext);
@@ -2673,6 +2765,7 @@ export const runBrowserController = async (
   } else {
     isNewPage = true;
     containerContext = await browser.newContext({
+      providerOptions: browserLaunchOptions.providerOptions,
       viewport: null,
     });
     containerPage = await containerContext.newPage();
@@ -2706,6 +2799,13 @@ export const runBrowserController = async (
 
   const dispatchRouter = createDispatchRouter();
   const headedReloadQueue = createHeadedSerialTaskQueue();
+  const pendingHeadedReloads = new Map<
+    string,
+    {
+      runId: string;
+      deferred: DeferredPromise<void>;
+    }
+  >();
   let enqueueHeadedReload = async (
     _file: TestFileInfo,
     _testNamePattern?: string,
@@ -2713,16 +2813,89 @@ export const runBrowserController = async (
     throw new Error('Headed reload queue is not initialized');
   };
 
+  const rejectPendingHeadedReload = (
+    testPath: string,
+    error: Error,
+    runId?: string,
+  ): void => {
+    const pending = pendingHeadedReloads.get(testPath);
+    if (!pending) {
+      return;
+    }
+    if (runId && pending.runId !== runId) {
+      return;
+    }
+    pendingHeadedReloads.delete(testPath);
+    pending.deferred.reject(error);
+  };
+
+  const rejectAllPendingHeadedReloads = (error: Error): void => {
+    for (const [testPath, pending] of pendingHeadedReloads) {
+      pendingHeadedReloads.delete(testPath);
+      pending.deferred.reject(error);
+    }
+  };
+
+  const registerPendingHeadedReload = (
+    testPath: string,
+    runId: string,
+  ): Promise<void> => {
+    const previousPending = pendingHeadedReloads.get(testPath);
+    if (previousPending) {
+      previousPending.deferred.reject(
+        new Error(
+          `Reload for "${testPath}" was superseded by a newer request.`,
+        ),
+      );
+      pendingHeadedReloads.delete(testPath);
+    }
+
+    const deferred = createDeferredPromise<void>();
+    pendingHeadedReloads.set(testPath, {
+      runId,
+      deferred,
+    });
+
+    return deferred.promise;
+  };
+
+  const resolvePendingHeadedReload = (
+    testPath: string,
+    runId?: string,
+  ): void => {
+    const pending = pendingHeadedReloads.get(testPath);
+    if (!pending) {
+      return;
+    }
+    if (runId && pending.runId !== runId) {
+      logger.debug(
+        `[Browser UI] Ignoring stale file-complete for ${testPath}. current=${pending.runId}, incoming=${runId}`,
+      );
+      return;
+    }
+    pendingHeadedReloads.delete(testPath);
+    pending.deferred.resolve();
+  };
+
   const reloadTestFileWithTimeout = async (
     file: TestFileInfo,
     testNamePattern?: string,
   ): Promise<void> => {
     const timeoutMs = getHeadedPerFileTimeoutMs(file);
     let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let reloadAck: ReloadTestFileAck | undefined;
 
     try {
+      reloadAck = await rpcManager.reloadTestFile(
+        file.testPath,
+        testNamePattern,
+      );
+      const completionPromise = registerPendingHeadedReload(
+        file.testPath,
+        reloadAck.runId,
+      );
       await Promise.race([
-        rpcManager.reloadTestFile(file.testPath, testNamePattern),
+        completionPromise,
         new Promise<never>((_, reject) => {
           timeoutId = setTimeout(() => {
             reject(
@@ -2733,6 +2906,15 @@ export const runBrowserController = async (
           }, timeoutMs);
         }),
       ]);
+    } catch (error) {
+      if (reloadAck?.runId) {
+        rejectPendingHeadedReload(
+          file.testPath,
+          toError(error),
+          reloadAck.runId,
+        );
+      }
+      throw error;
     } finally {
       if (timeoutId) {
         clearTimeout(timeoutId);
@@ -2765,13 +2947,26 @@ export const runBrowserController = async (
     async onTestCaseResult(payload: TestResult) {
       await handleTestCaseResult(payload);
     },
-    async onTestFileComplete(payload: TestFileResult) {
-      await handleTestFileComplete(payload);
+    async onTestFileComplete(payload: HeadedTestFileCompletePayload) {
+      try {
+        await handleTestFileComplete(payload);
+        resolvePendingHeadedReload(payload.testPath, payload.runId);
+      } catch (error) {
+        rejectPendingHeadedReload(
+          payload.testPath,
+          toError(error),
+          payload.runId,
+        );
+        throw error;
+      }
     },
     async onLog(payload: LogPayload) {
       await handleLog(payload);
     },
     async onFatal(payload: FatalPayload) {
+      const error = new Error(payload.message);
+      error.stack = payload.stack;
+      rejectAllPendingHeadedReloads(error);
       await handleFatal(payload);
     },
     async dispatch(request: BrowserDispatchRequest) {
@@ -2786,14 +2981,18 @@ export const runBrowserController = async (
   if (isWatchMode && runtime.rpcManager) {
     rpcManager = runtime.rpcManager;
     // Update methods with new test state (caseResults, completedTests, etc.)
-    rpcManager.updateMethods(createRpcMethods());
+    rpcManager.updateMethods(createRpcMethods(), rejectAllPendingHeadedReloads);
     // Reattach if we have an existing WebSocket
     const existingWs = rpcManager.currentWebSocket;
     if (existingWs) {
       rpcManager.reattach(existingWs);
     }
   } else {
-    rpcManager = new ContainerRpcManager(wss, createRpcMethods());
+    rpcManager = new ContainerRpcManager(
+      wss,
+      createRpcMethods(),
+      rejectAllPendingHeadedReloads,
+    );
 
     if (isWatchMode) {
       runtime.rpcManager = rpcManager;
@@ -3066,7 +3265,7 @@ export const listBrowserTests = async (
     throw error;
   }
 
-  const { browser, port } = runtime;
+  const { browser, browserLaunchOptions, port } = runtime;
 
   // Get browser projects for runtime config
   // Normalize projectRoot to posix format for cross-platform compatibility
@@ -3110,7 +3309,10 @@ export const listBrowserTests = async (
   });
 
   // Create a headless page to run collection
-  const browserContext = await browser.newContext({ viewport: null });
+  const browserContext = await browser.newContext({
+    providerOptions: browserLaunchOptions.providerOptions,
+    viewport: null,
+  });
   const page = await browserContext.newPage();
 
   // Expose dispatch function for browser client to send messages

package/src/index.ts

@@ -10,7 +10,6 @@ import {
 } from './hostController';
 
 export { validateBrowserConfig } from './configValidation';
-
 export {
   BROWSER_VIEWPORT_PRESET_DIMENSIONS,
   BROWSER_VIEWPORT_PRESET_IDS,

package/src/providers/index.ts

@@ -6,6 +6,14 @@ import { playwrightProviderImplementation } from './playwright';
  *
  * When adding a new built-in provider, implement `BrowserProviderImplementation`
  * and register it in `providerImplementations` below.
+ *
+ * Provider-agnostic policy:
+ * - keep shared contracts and behavior provider-neutral
+ * - `browser.providerOptions` stays opaque at the framework boundary
+ * - do not export provider-owned config types from `@rstest/browser`
+ * - do not reference optional peer provider types from public declarations
+ * - keep provider-specific behavior and config decoding inside provider implementations
+ * - prefer direct passthrough to provider APIs over provider-specific translation
  */
 export type BrowserProvider = 'playwright';
 
@@ -50,6 +58,7 @@ export type BrowserProviderBrowser = {
   close: () => Promise<void>;
   newContext: (options: {
     viewport: { width: number; height: number } | null;
+    providerOptions?: Record<string, unknown>;
   }) => Promise<BrowserProviderContext>;
 };
 
@@ -62,6 +71,7 @@ export type BrowserProviderRuntime = {
 export type LaunchBrowserInput = {
   browserName: 'chromium' | 'firefox' | 'webkit';
   headless: boolean | undefined;
+  providerOptions: Record<string, unknown>;
 };
 
 /** Input contract for provider-side browser RPC dispatch. */

package/src/providers/playwright/implementation.ts

@@ -11,10 +11,12 @@ export const playwrightProviderImplementation: BrowserProviderImplementation = {
   async launchRuntime({
     browserName,
     headless,
+    providerOptions,
   }): Promise<BrowserProviderRuntime> {
     return launchPlaywrightBrowser({
       browserName,
       headless,
+      providerOptions,
     });
   },
   async dispatchRpc({

package/src/providers/playwright/runtime.ts

@@ -1,32 +1,54 @@
-import type { BrowserProviderRuntime } from '../index';
-
-type PlaywrightModule = typeof import('playwright');
-type PlaywrightBrowserType = PlaywrightModule['chromium'];
+import type { BrowserProviderContext, BrowserProviderRuntime } from '../index';
 
 export async function launchPlaywrightBrowser({
   browserName,
   headless,
+  providerOptions,
 }: {
   browserName: 'chromium' | 'firefox' | 'webkit';
   headless: boolean | undefined;
+  providerOptions: Record<string, unknown>;
 }): Promise<BrowserProviderRuntime> {
   const playwright = await import('playwright');
-  const browserType = playwright[browserName] as PlaywrightBrowserType;
+  const browserType = playwright[browserName];
+  const launchOptions = providerOptions.launch as
+    | Record<string, unknown>
+    | undefined;
+  const launchArgs = Array.isArray(launchOptions?.args)
+    ? launchOptions.args
+    : browserName === 'chromium'
+      ? [
+          '--disable-popup-blocking',
+          '--no-first-run',
+          '--no-default-browser-check',
+        ]
+      : undefined;
 
   const browser = await browserType.launch({
+    ...launchOptions,
     headless,
-    // Chromium-specific args (ignored by other browsers)
-    args:
-      browserName === 'chromium'
-        ? [
-            '--disable-popup-blocking',
-            '--no-first-run',
-            '--no-default-browser-check',
-          ]
-        : undefined,
+    args: launchArgs,
   });
 
+  const wrappedBrowser: BrowserProviderRuntime['browser'] = {
+    close: async () => browser.close(),
+    newContext: async ({
+      providerOptions: contextProviderOptions,
+      viewport,
+    }) => {
+      const contextOptions = contextProviderOptions?.context as
+        | Record<string, unknown>
+        | undefined;
+      const context = await browser.newContext({
+        ...contextOptions,
+        viewport,
+      });
+
+      return context as unknown as BrowserProviderContext;
+    },
+  };
+
   return {
-    browser: browser as unknown as BrowserProviderRuntime['browser'],
+    browser: wrappedBrowser,
   };
 }

package/dist/browser-container/container-static/js/101.82cdbbe145.js.LICENSE.txt

@@ -1 +0,0 @@
-/*! LICENSE: 101.82cdbbe145.js.LICENSE.txt */

package/dist/browser-container/container-static/js/lib-react.ce60b6aea5.js.LICENSE.txt

@@ -1 +0,0 @@
-/*! LICENSE: lib-react.ce60b6aea5.js.LICENSE.txt */