@msw/playwright 0.3.1 → 0.4.1

package/README.md

@@ -13,7 +13,7 @@ await page.evaluate(() => {
   // functions from the `msw` package you want to use since
   // you cannot reference them in `page.evaluate` directly.
   const { worker, http, graphql } = window.msw
-  worker.use(...)
+  worker.use(...overrides)
 })
 ```
 
@@ -30,16 +30,16 @@ npm i msw @msw/playwright
 ```ts
 // playwright.setup.ts
 import { test as testBase } from '@playwright/test'
-import { createWorkerFixture, type WorkerFixture } from '@msw/playwright'
+import { createNetworkFixture, type NetworkFixture } from '@msw/playwright'
 import { handlers } from '../mocks/handlers.js'
 
 interface Fixtures {
-  worker: WorkerFixture
+  network: NetworkFixture
 }
 
 export const test = testBase.extend<Fixtures>({
-  // Create your worker fixture to access in tests.
-  worker: createWorkerFixture({
+  // Create a fixture that will control the network in your tests.
+  network: createNetworkFixture({
     initialHandlers: handlers,
   }),
 })
@@ -49,10 +49,10 @@ export const test = testBase.extend<Fixtures>({
 import { http, HttpResponse } from 'msw'
 import { test } from './playwright.setup.js'
 
-test('displays the user dashboard', async ({ worker, page }) => {
-  // Access and use the worker as you normally would!
+test('displays the user dashboard', async ({ network, page }) => {
+  // Access the network fixture and use it as the `setupWorker()` API.
   // No more disrupted context between processes.
-  worker.use(
+  network.use(
     http.get('/user', () => {
       return HttpResponse.json({
         id: 'abc-123',
@@ -65,3 +65,17 @@ test('displays the user dashboard', async ({ worker, page }) => {
   await page.goto('/dashboard')
 })
 ```
+
+## Comparison
+
+### `playwright-msw`
+
+[`playwright-msw`](https://github.com/valendres/playwright-msw) is a community package that, just like `@msw/playwright`, aims to provide a better experience when mocking APIs in your Playwright tests.
+
+> While `playwright-msw` is a fantastic tool and a huge inspiration for this package to exist, I believe it approaches the idea at a rather complex angle. That introduces a layer of abstraction that is subjected to the "left behind" problem as it needs to map to any MSW changes explicitly.
+
+|                | `playwright-msw`                                                                      | `@msw/playwright`                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Initialization | `createWorkerFixture()` is used as a _part_ of your custom fixture.                   | `createNetworkFixture()` creates _the entire_ fixture for you, pre-configured.                     |
+| Implementation | Uses a custom router to match handlers and a custom wrapper around `SetupWorker` API. | Uses MSW directly. Uses `page.route()` as the source of the network to route through the handlers. |
+| Feature set    | Supports `http` and `graphql` namespaces.                                             | Supports all namespaces (`http`, `graphql`, `ws`, any other APIs exposed by MSW in the future).    |

package/build/index.d.ts

@@ -1,14 +1,33 @@
 import { LifeCycleEventsMap, RequestHandler, SetupApi, WebSocketHandler } from "msw";
-import { Page, TestFixture } from "@playwright/test";
+import { Page, PlaywrightTestArgs, PlaywrightWorkerArgs, TestFixture } from "@playwright/test";
 
 //#region src/index.d.ts
-interface CreateWorkerFixtureArgs {
+interface CreateNetworkFixtureArgs {
   initialHandlers: Array<RequestHandler | WebSocketHandler>;
 }
-declare function createWorkerFixture(args?: CreateWorkerFixtureArgs): [TestFixture<WorkerFixture, any>, {
+/**
+ * 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;
 }];
-declare class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
+declare class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
   #private;
   constructor(args: {
     page: Page;
@@ -18,4 +37,4 @@ declare class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
   stop(): Promise<void>;
 }
 //#endregion
-export { CreateWorkerFixtureArgs, WorkerFixture, createWorkerFixture };
+export { CreateNetworkFixtureArgs, NetworkFixture, createNetworkFixture };

package/build/index.js

@@ -3,9 +3,28 @@ import { RequestHandler, SetupApi, WebSocketHandler, getResponse } from "msw";
 import { CancelableCloseEvent, CancelableMessageEvent } from "@mswjs/interceptors/WebSocket";
 
 //#region src/index.ts
-function createWorkerFixture(args) {
+/**
+* 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 WorkerFixture({
+		const worker = new NetworkFixture({
 			page,
 			initialHandlers: args?.initialHandlers || []
 		});
@@ -14,7 +33,7 @@ function createWorkerFixture(args) {
 		await worker.stop();
 	}, { auto: true }];
 }
-var WorkerFixture = class extends SetupApi {
+var NetworkFixture = class extends SetupApi {
 	#page;
 	constructor(args) {
 		super(...args.initialHandlers);
@@ -31,6 +50,10 @@ var WorkerFixture = class extends SetupApi {
 				return handler instanceof RequestHandler;
 			}), fetchRequest);
 			if (response) {
+				if (response.status === 0) {
+					route.abort();
+					return;
+				}
 				route.fulfill({
 					status: response.status,
 					headers: Object.fromEntries(response.headers),
@@ -203,4 +226,4 @@ var PlaywrightWebSocketServerConnection = class {
 };
 
 //#endregion
-export { WorkerFixture, createWorkerFixture };
+export { NetworkFixture, createNetworkFixture };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@msw/playwright",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Mock Service Worker binding for Playwright",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",

package/src/index.ts

@@ -1,5 +1,11 @@
 import { invariant } from 'outvariant'
-import type { Page, TestFixture, WebSocketRoute } from '@playwright/test'
+import type {
+  Page,
+  PlaywrightTestArgs,
+  PlaywrightWorkerArgs,
+  TestFixture,
+  WebSocketRoute,
+} from '@playwright/test'
 import {
   type LifeCycleEventsMap,
   SetupApi,
@@ -17,17 +23,39 @@ import {
   WebSocketServerConnectionProtocol,
 } from '@mswjs/interceptors/WebSocket'
 
-export interface CreateWorkerFixtureArgs {
+export interface CreateNetworkFixtureArgs {
   initialHandlers: Array<RequestHandler | WebSocketHandler>
 }
 
-export function createWorkerFixture(
-  args?: CreateWorkerFixtureArgs,
+/**
+ * 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,
   /** @todo `onUnhandledRequest`? */
-): [TestFixture<WorkerFixture, any>, { auto: boolean }] {
+): [
+  TestFixture<NetworkFixture, PlaywrightTestArgs & PlaywrightWorkerArgs>,
+  { auto: boolean },
+] {
   return [
     async ({ page }, use) => {
-      const worker = new WorkerFixture({
+      const worker = new NetworkFixture({
         page,
         initialHandlers: args?.initialHandlers || [],
       })
@@ -40,7 +68,7 @@ export function createWorkerFixture(
   ]
 }
 
-export class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
+export class NetworkFixture extends SetupApi<LifeCycleEventsMap> {
   #page: Page
 
   constructor(args: {
@@ -68,6 +96,11 @@ export class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
       )
 
       if (response) {
+        if (response.status === 0) {
+          route.abort()
+          return
+        }
+
         route.fulfill({
           status: response.status,
           headers: Object.fromEntries(response.headers),