@msw/playwright 0.5.0 → 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 },
+  ],
 })
 ```
 

package/build/index.d.ts

@@ -1,9 +1,10 @@
-import { LifeCycleEventsMap, RequestHandler, SetupApi, UnhandledRequestStrategy, WebSocketHandler } from "msw";
-import { BrowserContext, 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).
@@ -14,51 +15,16 @@ interface CreateNetworkFixtureArgs {
    */
   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: {
-    context: BrowserContext;
-    skipAssetRequests: boolean;
-    initialHandlers: Array<RequestHandler | WebSocketHandler>;
-    onUnhandledRequest?: UnhandledRequestStrategy;
-  };
-  constructor(args: {
-    context: BrowserContext;
-    skipAssetRequests: boolean;
-    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

@@ -3,37 +3,13 @@ import { RequestHandler, SetupApi, WebSocketHandler, handleRequest, isCommonAsse
 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 ({ context }, use) => {
-		const worker = new NetworkFixture({
-			context,
-			skipAssetRequests: args?.skipAssetRequests ?? true,
-			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
@@ -42,13 +18,13 @@ 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.context.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()),
@@ -60,7 +36,7 @@ var NetworkFixture = class extends SetupApi {
 			* requests through the matching logic below.
 			* @see https://github.com/mswjs/playwright/issues/13
 			*/
-			if (this.args.skipAssetRequests && isCommonAssetRequest(fetchRequest)) return route.continue();
+			if (this.options.skipAssetRequests && isCommonAssetRequest(fetchRequest)) return route.continue();
 			const handlers = this.handlersController.currentHandlers().filter((handler) => {
 				return handler instanceof RequestHandler;
 			});
@@ -69,7 +45,7 @@ var NetworkFixture = class extends SetupApi {
 			* @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
 			} });
@@ -83,7 +59,7 @@ var NetworkFixture = class extends SetupApi {
 			}
 			return route.continue();
 		});
-		await this.args.context.routeWebSocket(INTERNAL_MATCH_ALL_REG_EXP, async (route) => {
+		await this.options.context.routeWebSocket(INTERNAL_MATCH_ALL_REG_EXP, async (route) => {
 			const allWebSocketHandlers = this.handlersController.currentHandlers().filter((handler) => {
 				return handler instanceof WebSocketHandler;
 			});
@@ -93,7 +69,7 @@ var NetworkFixture = class extends SetupApi {
 			}
 			const client = new PlaywrightWebSocketClientConnection(route);
 			const server = new PlaywrightWebSocketServerConnection(route);
-			const pages = this.args.context.pages();
+			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({
@@ -103,10 +79,10 @@ var NetworkFixture = class extends SetupApi {
 			}, { baseUrl });
 		});
 	}
-	async stop() {
+	async disable() {
 		super.dispose();
-		await this.args.context.unroute(INTERNAL_MATCH_ALL_REG_EXP);
-		await unrouteWebSocket(this.args.context, 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(page) {
 		const url = page.url();
@@ -266,4 +242,4 @@ async function unrouteWebSocket(target, url, handler) {
 }
 
 //#endregion
-export { createNetworkFixture };
+export { defineNetworkFixture };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@msw/playwright",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Mock Service Worker binding for Playwright",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -33,7 +33,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "msw": "^2.12.9"
+    "msw": "^2.12.10"
   },
   "devDependencies": {
     "@epic-web/test-server": "^0.1.6",
@@ -41,7 +41,7 @@
     "@playwright/test": "^1.58.1",
     "@types/node": "^22.15.29",
     "@types/sinon": "^21.0.0",
-    "msw": "^2.12.9",
+    "msw": "^2.12.10",
     "sinon": "^21.0.1",
     "tsdown": "^0.12.7",
     "typescript": "^5.9.3",

package/src/fixture.ts

@@ -2,21 +2,18 @@ import { invariant } from 'outvariant'
 import type {
   BrowserContext,
   Page,
-  PlaywrightTestArgs,
-  PlaywrightWorkerArgs,
   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,
@@ -27,9 +24,11 @@ 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).
@@ -41,46 +40,27 @@ export interface CreateNetworkFixtureArgs {
   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 ({ context }, use) => {
-      const worker = new NetworkFixture({
-        context,
-        skipAssetRequests: args?.skipAssetRequests ?? true,
-        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
 }
 
 /**
@@ -91,21 +71,14 @@ export function createNetworkFixture(
  */
 export const INTERNAL_MATCH_ALL_REG_EXP = /.+(__MSW_PLAYWRIGHT_PREDICATE__)?/
 
-export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
-  constructor(
-    protected args: {
-      context: BrowserContext
-      skipAssetRequests: boolean
-      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.context.route(
+    await this.options.context.route(
       INTERNAL_MATCH_ALL_REG_EXP,
       async (route: Route, request: PlaywrightRequest) => {
         const fetchRequest = new Request(request.url(), {
@@ -120,7 +93,10 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
          * requests through the matching logic below.
          * @see https://github.com/mswjs/playwright/issues/13
          */
-        if (this.args.skipAssetRequests && isCommonAssetRequest(fetchRequest)) {
+        if (
+          this.options.skipAssetRequests &&
+          isCommonAssetRequest(fetchRequest)
+        ) {
           return route.continue()
         }
 
@@ -143,7 +119,7 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
           crypto.randomUUID(),
           handlers,
           {
-            onUnhandledRequest: this.args.onUnhandledRequest || 'bypass',
+            onUnhandledRequest: this.options.onUnhandledRequest || 'bypass',
           },
           this.emitter,
           {
@@ -173,7 +149,7 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
     )
 
     // Handle WebSocket connections.
-    await this.args.context.routeWebSocket(
+    await this.options.context.routeWebSocket(
       INTERNAL_MATCH_ALL_REG_EXP,
       async (route) => {
         const allWebSocketHandlers = this.handlersController
@@ -190,7 +166,7 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
         const client = new PlaywrightWebSocketClientConnection(route)
         const server = new PlaywrightWebSocketServerConnection(route)
 
-        const pages = this.args.context.pages()
+        const pages = this.options.context.pages()
         const lastPage = pages[pages.length - 1]
         const baseUrl = lastPage ? this.getPageUrl(lastPage) : undefined
 
@@ -210,10 +186,10 @@ export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
     )
   }
 
-  public async stop(): Promise<void> {
+  public async disable(): Promise<void> {
     super.dispose()
-    await this.args.context.unroute(INTERNAL_MATCH_ALL_REG_EXP)
-    await unrouteWebSocket(this.args.context, 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(page: Page): string | undefined {

package/src/index.ts

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