@msw/playwright 0.4.5 → 0.6.0

package/README.md

@@ -37,11 +37,24 @@ interface Fixtures {
   network: NetworkFixture
 }
 
-export const test = testBase.extend<Fixtures>({
-  // Create a fixture that will control the network in your tests.
-  network: createNetworkFixture({
-    initialHandlers: handlers,
-  }),
+const test = testBase.extend<Fixtures>({
+  // Initial list of the network handlers.
+  handlers: [[], { option: true }],
+
+  // A fixture you use to control the network in your tests.
+  network: [
+    async ({ context, handlers }, use) => {
+      const network = defineNetworkFixture({
+        context,
+        handlers,
+      })
+
+      await network.enable()
+      await use(network)
+      await network.disable()
+    },
+    { auto: true },
+  ],
 })
 ```
 
@@ -66,6 +79,10 @@ test('displays the user dashboard', async ({ network, page }) => {
 })
 ```
 
+## Limitations
+
+- Since `context.routeWebSocket()` provides no means of knowing which page triggered a WebSocket connection, relative WebSocket URLs in `ws.link(url)` will be resolved against the _latest_ created page in the browser context.
+
 ## Comparison
 
 ### `playwright-msw`

package/build/index.d.ts

@@ -1,54 +1,30 @@
-import { LifeCycleEventsMap, RequestHandler, SetupApi, UnhandledRequestStrategy, WebSocketHandler } from "msw";
-import { Page, PlaywrightTestArgs, PlaywrightWorkerArgs, TestFixture } from "@playwright/test";
+import { AnyHandler, LifeCycleEventsMap, SetupApi, UnhandledRequestStrategy } from "msw";
+import { BrowserContext } from "@playwright/test";
 
 //#region src/fixture.d.ts
-interface CreateNetworkFixtureArgs {
-  initialHandlers?: Array<RequestHandler | WebSocketHandler>;
+interface NetworkFixtureOptions {
+  context: BrowserContext;
+  handlers?: Array<AnyHandler>;
   onUnhandledRequest?: UnhandledRequestStrategy;
+  /**
+   * Skip common asset requests (e.g. `*.html`, `*.css`, `*.js`, etc).
+   * This improves performance for certian projects.
+   * @default true
+   *
+   * @see https://mswjs.io/docs/api/is-common-asset-request
+   */
+  skipAssetRequests?: boolean;
 }
-/**
- * Creates a fixture that controls the network in your tests.
- *
- * @note The returned fixture already has the `auto` option set to `true`.
- *
- * **Usage**
- * ```ts
- * import { test as testBase } from '@playwright/test'
- * import { createNetworkFixture, type WorkerFixture } from '@msw/playwright'
- *
- * interface Fixtures {
- *  network: WorkerFixture
- * }
- *
- * export const test = testBase.extend<Fixtures>({
- *   network: createNetworkFixture()
- * })
- * ```
- */
-declare function createNetworkFixture(args?: CreateNetworkFixtureArgs): [TestFixture<NetworkFixture, PlaywrightTestArgs & PlaywrightWorkerArgs>, {
-  auto: boolean;
-}];
+type NetworkFixture = Omit<SetupApi<LifeCycleEventsMap>, 'dispose'> & {
+  enable: () => Promise<void>;
+  disable: () => Promise<void>;
+};
+declare function defineNetworkFixture(options: NetworkFixtureOptions): NetworkFixture;
 /**
  * @note Use a match-all RegExp with an optional group as the predicate
  * for the `page.route()`/`page.unroute()` calls. Playwright treats given RegExp
  * as the handler ID, which allows us to remove only those handlers introduces by us
  * without carrying the reference to the handler function around.
  */
-
-declare class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
-  protected args: {
-    page: Page;
-    initialHandlers: Array<RequestHandler | WebSocketHandler>;
-    onUnhandledRequest?: UnhandledRequestStrategy;
-  };
-  constructor(args: {
-    page: Page;
-    initialHandlers: Array<RequestHandler | WebSocketHandler>;
-    onUnhandledRequest?: UnhandledRequestStrategy;
-  });
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  private getPageUrl;
-}
 //#endregion
-export { CreateNetworkFixtureArgs, NetworkFixture, createNetworkFixture };
+export { NetworkFixture, NetworkFixtureOptions, defineNetworkFixture };

package/build/index.js

@@ -1,38 +1,15 @@
 import { invariant } from "outvariant";
-import { RequestHandler, SetupApi, WebSocketHandler, handleRequest } from "msw";
+import { RequestHandler, SetupApi, WebSocketHandler, handleRequest, isCommonAssetRequest } from "msw";
 import { CancelableCloseEvent, CancelableMessageEvent } from "@mswjs/interceptors/WebSocket";
 
 //#region src/fixture.ts
-/**
-* Creates a fixture that controls the network in your tests.
-*
-* @note The returned fixture already has the `auto` option set to `true`.
-*
-* **Usage**
-* ```ts
-* import { test as testBase } from '@playwright/test'
-* import { createNetworkFixture, type WorkerFixture } from '@msw/playwright'
-*
-* interface Fixtures {
-*  network: WorkerFixture
-* }
-*
-* export const test = testBase.extend<Fixtures>({
-*   network: createNetworkFixture()
-* })
-* ```
-*/
-function createNetworkFixture(args) {
-	return [async ({ page }, use) => {
-		const worker = new NetworkFixture({
-			page,
-			initialHandlers: args?.initialHandlers || [],
-			onUnhandledRequest: args?.onUnhandledRequest
-		});
-		await worker.start();
-		await use(worker);
-		await worker.stop();
-	}, { auto: true }];
+function defineNetworkFixture(options) {
+	return new SetupPlaywrightApi({
+		context: options.context,
+		initialHandlers: options.handlers || [],
+		onUnhandledRequest: options.onUnhandledRequest,
+		skipAssetRequests: options.skipAssetRequests ?? true
+	});
 }
 /**
 * @note Use a match-all RegExp with an optional group as the predicate
@@ -41,68 +18,76 @@ function createNetworkFixture(args) {
 * without carrying the reference to the handler function around.
 */
 const INTERNAL_MATCH_ALL_REG_EXP = /.+(__MSW_PLAYWRIGHT_PREDICATE__)?/;
-var NetworkFixture = class extends SetupApi {
-	constructor(args) {
-		super(...args.initialHandlers);
-		this.args = args;
+var SetupPlaywrightApi = class extends SetupApi {
+	constructor(options) {
+		super(...options.initialHandlers);
+		this.options = options;
 	}
-	async start() {
-		await this.args.page.route(INTERNAL_MATCH_ALL_REG_EXP, async (route, request) => {
+	async enable() {
+		await this.options.context.route(INTERNAL_MATCH_ALL_REG_EXP, async (route, request) => {
 			const fetchRequest = new Request(request.url(), {
 				method: request.method(),
 				headers: new Headers(await request.allHeaders()),
 				body: request.postDataBuffer()
 			});
+			/**
+			* @note Skip common asset requests (default).
+			* Playwright seems to experience performance degradation when routing all
+			* requests through the matching logic below.
+			* @see https://github.com/mswjs/playwright/issues/13
+			*/
+			if (this.options.skipAssetRequests && isCommonAssetRequest(fetchRequest)) return route.continue();
 			const handlers = this.handlersController.currentHandlers().filter((handler) => {
 				return handler instanceof RequestHandler;
 			});
+			const baseUrl = request.headers().referer ? new URL(request.headers().referer).origin : void 0;
 			/**
 			* @note Use `handleRequest` instead of `getResponse` so we can pass
 			* the `onUnhandledRequest` option as-is and benefit from MSW's default behaviors.
 			*/
-			const response = await handleRequest(fetchRequest, crypto.randomUUID(), handlers, { onUnhandledRequest: this.args.onUnhandledRequest || "bypass" }, this.emitter, { resolutionContext: {
+			const response = await handleRequest(fetchRequest, crypto.randomUUID(), handlers, { onUnhandledRequest: this.options.onUnhandledRequest || "bypass" }, this.emitter, { resolutionContext: {
 				quiet: true,
-				baseUrl: this.getPageUrl()
+				baseUrl
 			} });
 			if (response) {
-				if (response.status === 0) {
-					route.abort();
-					return;
-				}
-				route.fulfill({
+				if (response.status === 0) return route.abort();
+				return route.fulfill({
 					status: response.status,
 					headers: Object.fromEntries(response.headers),
 					body: response.body ? Buffer.from(await response.arrayBuffer()) : void 0
 				});
-				return;
 			}
-			route.continue();
+			return route.continue();
 		});
-		await this.args.page.routeWebSocket(INTERNAL_MATCH_ALL_REG_EXP, async (ws) => {
+		await this.options.context.routeWebSocket(INTERNAL_MATCH_ALL_REG_EXP, async (route) => {
 			const allWebSocketHandlers = this.handlersController.currentHandlers().filter((handler) => {
 				return handler instanceof WebSocketHandler;
 			});
 			if (allWebSocketHandlers.length === 0) {
-				ws.connectToServer();
+				route.connectToServer();
 				return;
 			}
-			const client = new PlaywrightWebSocketClientConnection(ws);
-			const server = new PlaywrightWebSocketServerConnection(ws);
+			const client = new PlaywrightWebSocketClientConnection(route);
+			const server = new PlaywrightWebSocketServerConnection(route);
+			const pages = this.options.context.pages();
+			const lastPage = pages[pages.length - 1];
+			const baseUrl = lastPage ? this.getPageUrl(lastPage) : void 0;
 			for (const handler of allWebSocketHandlers) await handler.run({
 				client,
 				server,
 				info: { protocols: [] }
-			}, { baseUrl: this.getPageUrl() });
+			}, { baseUrl });
 		});
 	}
-	async stop() {
+	async disable() {
 		super.dispose();
-		await this.args.page.unroute(INTERNAL_MATCH_ALL_REG_EXP);
-		await unrouteWebSocket(this.args.page, INTERNAL_MATCH_ALL_REG_EXP);
+		await this.options.context.unroute(INTERNAL_MATCH_ALL_REG_EXP);
+		await unrouteWebSocket(this.options.context, INTERNAL_MATCH_ALL_REG_EXP);
 	}
-	getPageUrl() {
-		const url = this.args.page.url();
-		return url !== "about:blank" ? url : void 0;
+	getPageUrl(page) {
+		const url = page.url();
+		if (url === "about:blank") return;
+		return decodeURI(new URL(encodeURI(url)).origin);
 	}
 };
 var PlaywrightWebSocketClientConnection = class {
@@ -248,13 +233,13 @@ var PlaywrightWebSocketServerConnection = class {
 * Custom implementation of the missing `page.unrouteWebSocket()` to remove
 * WebSocket route handlers from the page. Loosely inspired by `page.unroute()`.
 */
-async function unrouteWebSocket(page, url, handler) {
-	if (!("_webSocketRoutes" in page && Array.isArray(page._webSocketRoutes))) return;
-	for (let i = page._webSocketRoutes.length - 1; i >= 0; i--) {
-		const route = page._webSocketRoutes[i];
-		if (route.url === url && (handler != null ? route.handler === handler : true)) page._webSocketRoutes.splice(i, 1);
+async function unrouteWebSocket(target, url, handler) {
+	if (!("_webSocketRoutes" in target && Array.isArray(target._webSocketRoutes))) return;
+	for (let i = target._webSocketRoutes.length - 1; i >= 0; i--) {
+		const route = target._webSocketRoutes[i];
+		if (route.url === url && (handler != null ? route.handler === handler : true)) target._webSocketRoutes.splice(i, 1);
 	}
 }
 
 //#endregion
-export { createNetworkFixture };
+export { defineNetworkFixture };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@msw/playwright",
-  "version": "0.4.5",
+  "version": "0.6.0",
   "description": "Mock Service Worker binding for Playwright",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -33,22 +33,22 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "msw": "^2.10.3"
+    "msw": "^2.12.10"
   },
   "devDependencies": {
     "@epic-web/test-server": "^0.1.6",
     "@ossjs/release": "^0.10.1",
-    "@playwright/test": "^1.57.0",
+    "@playwright/test": "^1.58.1",
     "@types/node": "^22.15.29",
     "@types/sinon": "^21.0.0",
-    "msw": "^2.12.7",
+    "msw": "^2.12.10",
     "sinon": "^21.0.1",
     "tsdown": "^0.12.7",
     "typescript": "^5.9.3",
     "vite": "^7.3.1"
   },
   "dependencies": {
-    "@mswjs/interceptors": "^0.40.0",
+    "@mswjs/interceptors": "^0.41.2",
     "outvariant": "^1.4.3"
   },
   "scripts": {

package/src/fixture.ts

@@ -1,20 +1,19 @@
 import { invariant } from 'outvariant'
 import type {
+  BrowserContext,
   Page,
-  PlaywrightTestArgs,
-  PlaywrightWorkerArgs,
-  Request,
+  Request as PlaywrightRequest,
   Route,
-  TestFixture,
   WebSocketRoute,
 } from '@playwright/test'
+import { WebSocketHandler } from 'msw'
 import {
-  type LifeCycleEventsMap,
-  type UnhandledRequestStrategy,
   SetupApi,
-  RequestHandler,
-  WebSocketHandler,
   handleRequest,
+  isCommonAssetRequest,
+  type AnyHandler,
+  type LifeCycleEventsMap,
+  type UnhandledRequestStrategy,
 } from 'msw'
 import {
   type WebSocketClientEventMap,
@@ -25,51 +24,43 @@ import {
   WebSocketClientConnectionProtocol,
   WebSocketServerConnectionProtocol,
 } from '@mswjs/interceptors/WebSocket'
+import { RequestHandler } from 'msw'
 
-export interface CreateNetworkFixtureArgs {
-  initialHandlers?: Array<RequestHandler | WebSocketHandler>
+export interface NetworkFixtureOptions {
+  context: BrowserContext
+  handlers?: Array<AnyHandler>
   onUnhandledRequest?: UnhandledRequestStrategy
+  /**
+   * Skip common asset requests (e.g. `*.html`, `*.css`, `*.js`, etc).
+   * This improves performance for certian projects.
+   * @default true
+   *
+   * @see https://mswjs.io/docs/api/is-common-asset-request
+   */
+  skipAssetRequests?: boolean
 }
 
-/**
- * Creates a fixture that controls the network in your tests.
- *
- * @note The returned fixture already has the `auto` option set to `true`.
- *
- * **Usage**
- * ```ts
- * import { test as testBase } from '@playwright/test'
- * import { createNetworkFixture, type WorkerFixture } from '@msw/playwright'
- *
- * interface Fixtures {
- *  network: WorkerFixture
- * }
- *
- * export const test = testBase.extend<Fixtures>({
- *   network: createNetworkFixture()
- * })
- * ```
- */
-export function createNetworkFixture(
-  args?: CreateNetworkFixtureArgs,
-): [
-  TestFixture<NetworkFixture, PlaywrightTestArgs & PlaywrightWorkerArgs>,
-  { auto: boolean },
-] {
-  return [
-    async ({ page }, use) => {
-      const worker = new NetworkFixture({
-        page,
-        initialHandlers: args?.initialHandlers || [],
-        onUnhandledRequest: args?.onUnhandledRequest,
-      })
+export type NetworkFixture = Omit<SetupApi<LifeCycleEventsMap>, 'dispose'> & {
+  enable: () => Promise<void>
+  disable: () => Promise<void>
+}
+
+export function defineNetworkFixture(
+  options: NetworkFixtureOptions,
+): NetworkFixture {
+  return new SetupPlaywrightApi({
+    context: options.context,
+    initialHandlers: options.handlers || [],
+    onUnhandledRequest: options.onUnhandledRequest,
+    skipAssetRequests: options.skipAssetRequests ?? true,
+  })
+}
 
-      await worker.start()
-      await use(worker)
-      await worker.stop()
-    },
-    { auto: true },
-  ]
+interface SetupPlaywrightOptions {
+  context: BrowserContext
+  initialHandlers: Array<AnyHandler>
+  onUnhandledRequest?: UnhandledRequestStrategy
+  skipAssetRequests?: boolean
 }
 
 /**
@@ -80,34 +71,45 @@ export function createNetworkFixture(
  */
 export const INTERNAL_MATCH_ALL_REG_EXP = /.+(__MSW_PLAYWRIGHT_PREDICATE__)?/
 
-export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
-  constructor(
-    protected args: {
-      page: Page
-      initialHandlers: Array<RequestHandler | WebSocketHandler>
-      onUnhandledRequest?: UnhandledRequestStrategy
-    },
-  ) {
-    super(...args.initialHandlers)
+class SetupPlaywrightApi extends SetupApi<LifeCycleEventsMap> {
+  constructor(private readonly options: SetupPlaywrightOptions) {
+    super(...options.initialHandlers)
   }
 
-  public async start(): Promise<void> {
+  public async enable(): Promise<void> {
     // Handle HTTP requests.
-    await this.args.page.route(
+    await this.options.context.route(
       INTERNAL_MATCH_ALL_REG_EXP,
-      async (route: Route, request: Request) => {
+      async (route: Route, request: PlaywrightRequest) => {
         const fetchRequest = new Request(request.url(), {
           method: request.method(),
           headers: new Headers(await request.allHeaders()),
-          body: request.postDataBuffer(),
+          body: request.postDataBuffer() as ArrayBuffer | null,
         })
 
+        /**
+         * @note Skip common asset requests (default).
+         * Playwright seems to experience performance degradation when routing all
+         * requests through the matching logic below.
+         * @see https://github.com/mswjs/playwright/issues/13
+         */
+        if (
+          this.options.skipAssetRequests &&
+          isCommonAssetRequest(fetchRequest)
+        ) {
+          return route.continue()
+        }
+
         const handlers = this.handlersController
           .currentHandlers()
           .filter((handler) => {
             return handler instanceof RequestHandler
           })
 
+        const baseUrl = request.headers().referer
+          ? new URL(request.headers().referer).origin
+          : undefined
+
         /**
          * @note Use `handleRequest` instead of `getResponse` so we can pass
          * the `onUnhandledRequest` option as-is and benefit from MSW's default behaviors.
@@ -117,41 +119,39 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
           crypto.randomUUID(),
           handlers,
           {
-            onUnhandledRequest: this.args.onUnhandledRequest || 'bypass',
+            onUnhandledRequest: this.options.onUnhandledRequest || 'bypass',
           },
           this.emitter,
           {
             resolutionContext: {
               quiet: true,
-              baseUrl: this.getPageUrl(),
+              baseUrl,
             },
           },
         )
 
         if (response) {
           if (response.status === 0) {
-            route.abort()
-            return
+            return route.abort()
           }
 
-          route.fulfill({
+          return route.fulfill({
             status: response.status,
             headers: Object.fromEntries(response.headers),
             body: response.body
               ? Buffer.from(await response.arrayBuffer())
               : undefined,
           })
-          return
         }
 
-        route.continue()
+        return route.continue()
       },
     )
 
     // Handle WebSocket connections.
-    await this.args.page.routeWebSocket(
+    await this.options.context.routeWebSocket(
       INTERNAL_MATCH_ALL_REG_EXP,
-      async (ws) => {
+      async (route) => {
         const allWebSocketHandlers = this.handlersController
           .currentHandlers()
           .filter((handler) => {
@@ -159,12 +159,16 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
           })
 
         if (allWebSocketHandlers.length === 0) {
-          ws.connectToServer()
+          route.connectToServer()
           return
         }
 
-        const client = new PlaywrightWebSocketClientConnection(ws)
-        const server = new PlaywrightWebSocketServerConnection(ws)
+        const client = new PlaywrightWebSocketClientConnection(route)
+        const server = new PlaywrightWebSocketServerConnection(route)
+
+        const pages = this.options.context.pages()
+        const lastPage = pages[pages.length - 1]
+        const baseUrl = lastPage ? this.getPageUrl(lastPage) : undefined
 
         for (const handler of allWebSocketHandlers) {
           await handler.run(
@@ -174,7 +178,7 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
               info: { protocols: [] },
             },
             {
-              baseUrl: this.getPageUrl(),
+              baseUrl,
             },
           )
         }
@@ -182,21 +186,25 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
     )
   }
 
-  public async stop(): Promise<void> {
+  public async disable(): Promise<void> {
     super.dispose()
-    await this.args.page.unroute(INTERNAL_MATCH_ALL_REG_EXP)
-    await unrouteWebSocket(this.args.page, INTERNAL_MATCH_ALL_REG_EXP)
+    await this.options.context.unroute(INTERNAL_MATCH_ALL_REG_EXP)
+    await unrouteWebSocket(this.options.context, INTERNAL_MATCH_ALL_REG_EXP)
   }
 
-  private getPageUrl(): string | undefined {
-    const url = this.args.page.url()
-    return url !== 'about:blank' ? url : undefined
+  private getPageUrl(page: Page): string | undefined {
+    const url = page.url()
+
+    if (url === 'about:blank') {
+      return
+    }
+
+    // Encode/decode to preserve escape characters.
+    return decodeURI(new URL(encodeURI(url)).origin)
   }
 }
 
-class PlaywrightWebSocketClientConnection
-  implements WebSocketClientConnectionProtocol
-{
+class PlaywrightWebSocketClientConnection implements WebSocketClientConnectionProtocol {
   public id: string
   public url: URL
 
@@ -298,9 +306,7 @@ class PlaywrightWebSocketClientConnection
   }
 }
 
-class PlaywrightWebSocketServerConnection
-  implements WebSocketServerConnectionProtocol
-{
+class PlaywrightWebSocketServerConnection implements WebSocketServerConnectionProtocol {
   #server?: WebSocketRoute
   #bufferedEvents: Array<
     Parameters<WebSocketServerConnectionProtocol['addEventListener']>
@@ -411,22 +417,24 @@ interface InternalWebSocketRoute {
  * WebSocket route handlers from the page. Loosely inspired by `page.unroute()`.
  */
 async function unrouteWebSocket(
-  page: Page,
+  target: BrowserContext,
   url: InternalWebSocketRoute['url'],
   handler?: InternalWebSocketRoute['handler'],
 ): Promise<void> {
-  if (!('_webSocketRoutes' in page && Array.isArray(page._webSocketRoutes))) {
+  if (
+    !('_webSocketRoutes' in target && Array.isArray(target._webSocketRoutes))
+  ) {
     return
   }
 
-  for (let i = page._webSocketRoutes.length - 1; i >= 0; i--) {
-    const route = page._webSocketRoutes[i] as InternalWebSocketRoute
+  for (let i = target._webSocketRoutes.length - 1; i >= 0; i--) {
+    const route = target._webSocketRoutes[i] as InternalWebSocketRoute
 
     if (
       route.url === url &&
       (handler != null ? route.handler === handler : true)
     ) {
-      page._webSocketRoutes.splice(i, 1)
+      target._webSocketRoutes.splice(i, 1)
     }
   }
 }

package/src/index.ts

@@ -1,5 +1,5 @@
 export {
-  type CreateNetworkFixtureArgs,
+  defineNetworkFixture,
   type NetworkFixture,
-  createNetworkFixture,
+  type NetworkFixtureOptions,
 } from './fixture.js'