@msw/playwright 0.2.0 → 0.3.1

package/build/index.d.ts

@@ -1,16 +1,18 @@
-import { LifeCycleEventsMap, RequestHandler, SetupApi } from "msw";
+import { LifeCycleEventsMap, RequestHandler, SetupApi, WebSocketHandler } from "msw";
 import { Page, TestFixture } from "@playwright/test";
 
 //#region src/index.d.ts
 interface CreateWorkerFixtureArgs {
-  initialHandlers: Array<RequestHandler>;
+  initialHandlers: Array<RequestHandler | WebSocketHandler>;
 }
-declare function createWorkerFixture(args?: CreateWorkerFixtureArgs): TestFixture<WorkerFixture, any>;
+declare function createWorkerFixture(args?: CreateWorkerFixtureArgs): [TestFixture<WorkerFixture, any>, {
+  auto: boolean;
+}];
 declare class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
   #private;
   constructor(args: {
     page: Page;
-    initialHandlers: Array<RequestHandler>;
+    initialHandlers: Array<RequestHandler | WebSocketHandler>;
   });
   start(): Promise<void>;
   stop(): Promise<void>;

package/build/index.js

@@ -1,8 +1,10 @@
-import { RequestHandler, SetupApi, getResponse } from "msw";
+import { invariant } from "outvariant";
+import { RequestHandler, SetupApi, WebSocketHandler, getResponse } from "msw";
+import { CancelableCloseEvent, CancelableMessageEvent } from "@mswjs/interceptors/WebSocket";
 
 //#region src/index.ts
 function createWorkerFixture(args) {
-	return async ({ page }, use) => {
+	return [async ({ page }, use) => {
 		const worker = new WorkerFixture({
 			page,
 			initialHandlers: args?.initialHandlers || []
@@ -10,7 +12,7 @@ function createWorkerFixture(args) {
 		await worker.start();
 		await use(worker);
 		await worker.stop();
-	};
+	}, { auto: true }];
 }
 var WorkerFixture = class extends SetupApi {
 	#page;
@@ -38,12 +40,167 @@ var WorkerFixture = class extends SetupApi {
 			}
 			route.continue();
 		});
+		await this.#page.routeWebSocket(/.+/, async (ws) => {
+			const allWebSocketHandlers = this.handlersController.currentHandlers().filter((handler) => {
+				return handler instanceof WebSocketHandler;
+			});
+			if (allWebSocketHandlers.length === 0) {
+				ws.connectToServer();
+				return;
+			}
+			const client = new PlaywrightWebSocketClientConnection(ws);
+			const server = new PlaywrightWebSocketServerConnection(ws);
+			for (const handler of allWebSocketHandlers) await handler.run({
+				client,
+				server,
+				info: { protocols: [] }
+			});
+		});
 	}
 	async stop() {
 		super.dispose();
 		await this.#page.unroute(/.+/);
 	}
 };
+var PlaywrightWebSocketClientConnection = class {
+	id;
+	url;
+	constructor(ws) {
+		this.ws = ws;
+		this.id = crypto.randomUUID();
+		this.url = new URL(ws.url());
+	}
+	send(data) {
+		if (data instanceof Blob) {
+			/**
+			* @note Playwright does not support sending Blob data.
+			* Read the blob as buffer, then send the buffer instead.
+			*/
+			data.bytes().then((bytes) => {
+				this.ws.send(Buffer.from(bytes));
+			});
+			return;
+		}
+		if (typeof data === "string") {
+			this.ws.send(data);
+			return;
+		}
+		this.ws.send(
+			/**
+			* @note Forcefully cast all data to Buffer because Playwright
+			* has trouble digesting ArrayBuffer and Blob directly.
+			*/
+			Buffer.from(
+				/**
+				* @note Playwright type definitions are tailored to Node.js
+				* while MSW describes all data types that can be sent over
+				* the WebSocket protocol, like ArrayBuffer and Blob.
+				*/
+				data
+			)
+		);
+	}
+	close(code, reason) {
+		const resolvedCode = code ?? 1e3;
+		this.ws.close({
+			code: resolvedCode,
+			reason
+		});
+	}
+	addEventListener(type, listener, options) {
+		/**
+		* @note Playwright does not expose the actual WebSocket reference.
+		*/
+		const target = {};
+		switch (type) {
+			case "message": {
+				this.ws.onMessage((data) => {
+					listener.call(target, new CancelableMessageEvent("message", { data }));
+				});
+				break;
+			}
+			case "close": {
+				this.ws.onClose((code, reason) => {
+					listener.call(target, new CancelableCloseEvent("close", {
+						code,
+						reason
+					}));
+				});
+				break;
+			}
+		}
+	}
+	removeEventListener(event, listener, options) {
+		console.warn("@msw/playwright: WebSocketRoute does not support removing event listeners");
+	}
+};
+var PlaywrightWebSocketServerConnection = class {
+	#server;
+	#bufferedEvents;
+	#bufferedData;
+	constructor(ws) {
+		this.ws = ws;
+		this.#bufferedEvents = [];
+		this.#bufferedData = [];
+	}
+	connect() {
+		this.#server = this.ws.connectToServer();
+		/**
+		* @note Playwright does not support event buffering.
+		* Manually add event listeners that might have been registered
+		* before `connect()` was called.
+		*/
+		for (const [type, listener, options] of this.#bufferedEvents) this.addEventListener(type, listener, options);
+		this.#bufferedEvents.length = 0;
+		for (const data of this.#bufferedData) this.send(data);
+		this.#bufferedData.length = 0;
+	}
+	send(data) {
+		if (this.#server == null) {
+			this.#bufferedData.push(data);
+			return;
+		}
+		this.#server.send(data);
+	}
+	close(code, reason) {
+		invariant(this.#server, "Failed to close connection to the actual WebSocket server: connection not established. Did you forget to call `connect()`?");
+		this.#server.close({
+			code,
+			reason
+		});
+	}
+	addEventListener(type, listener, options) {
+		if (this.#server == null) {
+			this.#bufferedEvents.push([
+				type,
+				listener,
+				options
+			]);
+			return;
+		}
+		const target = {};
+		switch (type) {
+			case "message": {
+				this.#server.onMessage((data) => {
+					listener.call(target, new CancelableMessageEvent("message", { data }));
+				});
+				break;
+			}
+			case "close": {
+				this.#server.onClose((code, reason) => {
+					listener.call(target, new CancelableCloseEvent("close", {
+						code,
+						reason
+					}));
+				});
+				break;
+			}
+		}
+	}
+	removeEventListener(type, listener, options) {
+		console.warn("@msw/playwright: WebSocketRoute does not support removing event listeners");
+	}
+};
 
 //#endregion
 export { WorkerFixture, createWorkerFixture };

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@msw/playwright",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Mock Service Worker binding for Playwright",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -34,16 +34,21 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "msw": "^2.9.0"
+    "msw": "^2.10.1"
   },
   "devDependencies": {
+    "@epic-web/test-server": "^0.1.6",
     "@ossjs/release": "^0.8.1",
     "@playwright/test": "^1.52.0",
     "@types/node": "^22.15.29",
-    "msw": "^2.9.0",
+    "msw": "^2.10.1",
     "tsdown": "^0.12.7",
     "typescript": "^5.8.3"
   },
+  "dependencies": {
+    "@mswjs/interceptors": "^0.39.2",
+    "outvariant": "^1.4.3"
+  },
   "scripts": {
     "dev": "tsdown --watch",
     "test": "playwright test",

package/src/index.ts

@@ -1,40 +1,58 @@
-import type { Page, TestFixture } from '@playwright/test'
+import { invariant } from 'outvariant'
+import type { Page, TestFixture, WebSocketRoute } from '@playwright/test'
 import {
   type LifeCycleEventsMap,
   SetupApi,
   RequestHandler,
+  WebSocketHandler,
   getResponse,
 } from 'msw'
+import {
+  type WebSocketClientEventMap,
+  type WebSocketData,
+  type WebSocketServerEventMap,
+  CancelableMessageEvent,
+  CancelableCloseEvent,
+  WebSocketClientConnectionProtocol,
+  WebSocketServerConnectionProtocol,
+} from '@mswjs/interceptors/WebSocket'
 
 export interface CreateWorkerFixtureArgs {
-  initialHandlers: Array<RequestHandler>
+  initialHandlers: Array<RequestHandler | WebSocketHandler>
 }
 
 export function createWorkerFixture(
   args?: CreateWorkerFixtureArgs,
   /** @todo `onUnhandledRequest`? */
-): TestFixture<WorkerFixture, any> {
-  return async ({ page }, use) => {
-    const worker = new WorkerFixture({
-      page,
-      initialHandlers: args?.initialHandlers || [],
-    })
+): [TestFixture<WorkerFixture, any>, { auto: boolean }] {
+  return [
+    async ({ page }, use) => {
+      const worker = new WorkerFixture({
+        page,
+        initialHandlers: args?.initialHandlers || [],
+      })
 
-    await worker.start()
-    await use(worker)
-    await worker.stop()
-  }
+      await worker.start()
+      await use(worker)
+      await worker.stop()
+    },
+    { auto: true },
+  ]
 }
 
 export class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
   #page: Page
 
-  constructor(args: { page: Page; initialHandlers: Array<RequestHandler> }) {
+  constructor(args: {
+    page: Page
+    initialHandlers: Array<RequestHandler | WebSocketHandler>
+  }) {
     super(...args.initialHandlers)
     this.#page = args.page
   }
 
   public async start() {
+    // Handle HTTP requests.
     await this.#page.route(/.+/, async (route, request) => {
       const fetchRequest = new Request(request.url(), {
         method: request.method(),
@@ -62,6 +80,31 @@ export class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
 
       route.continue()
     })
+
+    // Handle WebSocket connections.
+    await this.#page.routeWebSocket(/.+/, async (ws) => {
+      const allWebSocketHandlers = this.handlersController
+        .currentHandlers()
+        .filter((handler) => {
+          return handler instanceof WebSocketHandler
+        })
+
+      if (allWebSocketHandlers.length === 0) {
+        ws.connectToServer()
+        return
+      }
+
+      const client = new PlaywrightWebSocketClientConnection(ws)
+      const server = new PlaywrightWebSocketServerConnection(ws)
+
+      for (const handler of allWebSocketHandlers) {
+        await handler.run({
+          client,
+          server,
+          info: { protocols: [] },
+        })
+      }
+    })
   }
 
   public async stop() {
@@ -69,3 +112,210 @@ export class WorkerFixture extends SetupApi<LifeCycleEventsMap> {
     await this.#page.unroute(/.+/)
   }
 }
+
+class PlaywrightWebSocketClientConnection
+  implements WebSocketClientConnectionProtocol
+{
+  public id: string
+  public url: URL
+
+  constructor(protected readonly ws: WebSocketRoute) {
+    this.id = crypto.randomUUID()
+    this.url = new URL(ws.url())
+  }
+
+  public send(data: WebSocketData): void {
+    if (data instanceof Blob) {
+      /**
+       * @note Playwright does not support sending Blob data.
+       * Read the blob as buffer, then send the buffer instead.
+       */
+      data.bytes().then((bytes) => {
+        this.ws.send(Buffer.from(bytes))
+      })
+      return
+    }
+
+    if (typeof data === 'string') {
+      this.ws.send(data)
+      return
+    }
+
+    this.ws.send(
+      /**
+       * @note Forcefully cast all data to Buffer because Playwright
+       * has trouble digesting ArrayBuffer and Blob directly.
+       */
+      Buffer.from(
+        /**
+         * @note Playwright type definitions are tailored to Node.js
+         * while MSW describes all data types that can be sent over
+         * the WebSocket protocol, like ArrayBuffer and Blob.
+         */
+        data as any,
+      ),
+    )
+  }
+
+  public close(code?: number, reason?: string): void {
+    const resolvedCode = code ?? 1000
+    this.ws.close({ code: resolvedCode, reason })
+  }
+
+  public addEventListener<EventType extends keyof WebSocketClientEventMap>(
+    type: EventType,
+    listener: (
+      this: WebSocket,
+      event: WebSocketClientEventMap[EventType],
+    ) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void {
+    /**
+     * @note Playwright does not expose the actual WebSocket reference.
+     */
+    const target = {} as WebSocket
+
+    switch (type) {
+      case 'message': {
+        this.ws.onMessage((data) => {
+          listener.call(
+            target,
+            new CancelableMessageEvent('message', {
+              data,
+            }) as any,
+          )
+        })
+        break
+      }
+
+      case 'close': {
+        this.ws.onClose((code, reason) => {
+          listener.call(
+            target,
+            new CancelableCloseEvent('close', {
+              code,
+              reason,
+            }) as any,
+          )
+        })
+        break
+      }
+    }
+  }
+
+  public removeEventListener<EventType extends keyof WebSocketClientEventMap>(
+    event: EventType,
+    listener: (
+      this: WebSocket,
+      event: WebSocketClientEventMap[EventType],
+    ) => void,
+    options?: EventListenerOptions | boolean,
+  ): void {
+    console.warn(
+      '@msw/playwright: WebSocketRoute does not support removing event listeners',
+    )
+  }
+}
+
+class PlaywrightWebSocketServerConnection
+  implements WebSocketServerConnectionProtocol
+{
+  #server?: WebSocketRoute
+  #bufferedEvents: Array<
+    Parameters<WebSocketServerConnectionProtocol['addEventListener']>
+  >
+  #bufferedData: Array<WebSocketData>
+
+  constructor(protected readonly ws: WebSocketRoute) {
+    this.#bufferedEvents = []
+    this.#bufferedData = []
+  }
+
+  public connect(): void {
+    this.#server = this.ws.connectToServer()
+
+    /**
+     * @note Playwright does not support event buffering.
+     * Manually add event listeners that might have been registered
+     * before `connect()` was called.
+     */
+    for (const [type, listener, options] of this.#bufferedEvents) {
+      this.addEventListener(type, listener, options)
+    }
+    this.#bufferedEvents.length = 0
+
+    // Same for the buffered data.
+    for (const data of this.#bufferedData) {
+      this.send(data)
+    }
+    this.#bufferedData.length = 0
+  }
+
+  public send(data: WebSocketData): void {
+    if (this.#server == null) {
+      this.#bufferedData.push(data)
+      return
+    }
+
+    this.#server.send(data as any)
+  }
+
+  public close(code?: number, reason?: string): void {
+    invariant(
+      this.#server,
+      'Failed to close connection to the actual WebSocket server: connection not established. Did you forget to call `connect()`?',
+    )
+
+    this.#server.close({ code, reason })
+  }
+
+  public addEventListener<EventType extends keyof WebSocketServerEventMap>(
+    type: EventType,
+    listener: (
+      this: WebSocket,
+      event: WebSocketServerEventMap[EventType],
+    ) => void,
+    options?: AddEventListenerOptions | boolean,
+  ): void {
+    if (this.#server == null) {
+      this.#bufferedEvents.push([type, listener as any, options])
+      return
+    }
+
+    const target = {} as WebSocket
+    switch (type) {
+      case 'message': {
+        this.#server.onMessage((data) => {
+          listener.call(
+            target,
+            new CancelableMessageEvent('message', { data }) as any,
+          )
+        })
+        break
+      }
+
+      case 'close': {
+        this.#server.onClose((code, reason) => {
+          listener.call(
+            target,
+            new CancelableCloseEvent('close', { code, reason }) as any,
+          )
+        })
+        break
+      }
+    }
+  }
+
+  public removeEventListener<EventType extends keyof WebSocketServerEventMap>(
+    type: EventType,
+    listener: (
+      this: WebSocket,
+      event: WebSocketServerEventMap[EventType],
+    ) => void,
+    options?: EventListenerOptions | boolean,
+  ): void {
+    console.warn(
+      '@msw/playwright: WebSocketRoute does not support removing event listeners',
+    )
+  }
+}