feat!: implement new defineNetworkFixture api (#36)

Author: kettanaito

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.json

@@ -42,15 +42,15 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "msw": "^2.12.9"
+    "msw": "^2.12.10"
   },
   "devDependencies": {
     "@epic-web/test-server": "^0.1.6",
     "@ossjs/release": "^0.10.1",
     "@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",
@@ -60,4 +60,4 @@
     "@mswjs/interceptors": "^0.41.2",
     "outvariant": "^1.4.3"
   }
-}
+}

pnpm-lock.yaml

@@ -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 {

src/fixture.ts

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

src/index.ts

@@ -4,15 +4,30 @@
  * given Playwright doesn't expose proper means to list route handlers.
  */
 import { test as testBase, expect } from '@playwright/test'
+import type { AnyHandler } from 'msw'
 import { INTERNAL_MATCH_ALL_REG_EXP } from '../../src/fixture.js'
-import { createNetworkFixture, type NetworkFixture } from '../../src/index.js'
+import { defineNetworkFixture, type NetworkFixture } from '../../src/index.js'
 
 interface Fixtures {
+  handlers: Array<AnyHandler>
   network: NetworkFixture
 }
 
 const test = testBase.extend<Fixtures>({
-  network: createNetworkFixture(),
+  handlers: [[], { option: true }],
+  network: [
+    async ({ context, handlers }, use) => {
+      const network = defineNetworkFixture({
+        context,
+        handlers,
+      })
+
+      await network.enable()
+      await use(network)
+      await network.disable()
+    },
+    { auto: true },
+  ],
 })
 
 test('registers a single HTTP route', async ({ context }) => {
@@ -25,7 +40,7 @@ test('unroutes the HTTP route when the fixture is stopped', async ({
   context,
   network,
 }) => {
-  await network.stop()
+  await network.disable()
   expect(Reflect.get(context, '_routes')).toEqual([])
 })
 
@@ -38,7 +53,7 @@ test('preserves user-defined HTTP routes', async ({ context, network }) => {
     expect.objectContaining({ url: INTERNAL_MATCH_ALL_REG_EXP }),
   ])
 
-  await network.stop()
+  await network.disable()
   expect(Reflect.get(context, '_routes')).toEqual([
     expect.objectContaining({ url: '/user-defined', handler: routeHandler }),
   ])
@@ -54,7 +69,7 @@ test('unroutes the WebSocket handler when the fixture is stopped', async ({
   context,
   network,
 }) => {
-  await network.stop()
+  await network.disable()
   expect(Reflect.get(context, '_webSocketRoutes')).toEqual([])
 })
 
@@ -70,7 +85,7 @@ test('preserves user-defined WebSocket routes', async ({
     expect.objectContaining({ url: INTERNAL_MATCH_ALL_REG_EXP }),
   ])
 
-  await network.stop()
+  await network.disable()
   expect(Reflect.get(context, '_webSocketRoutes')).toEqual([
     expect.objectContaining({ url: '/user-defined', handler: routeHandler }),
   ])

tests/internal/routes.test.ts

@@ -1,13 +1,27 @@
 import { test as testBase, expect } from '@playwright/test'
-import { http, HttpResponse, ws } from 'msw'
-import { createNetworkFixture, type NetworkFixture } from '../src/index.js'
+import { http, HttpResponse, ws, type AnyHandler } from 'msw'
+import { defineNetworkFixture, type NetworkFixture } from '../src/index.js'
 
 interface Fixtures {
+  handlers: Array<AnyHandler>
   network: NetworkFixture
 }
 
 const test = testBase.extend<Fixtures>({
-  network: createNetworkFixture(),
+  handlers: [[], { option: true }],
+  network: [
+    async ({ context, handlers }, use) => {
+      const network = defineNetworkFixture({
+        context,
+        handlers,
+      })
+
+      await network.enable()
+      await use(network)
+      await network.disable()
+    },
+    { auto: true },
+  ],
 })
 
 test('intercepts an HTTP request on a programmatically created page', async ({