Implementation:Microsoft Playwright WebSocketRouteDispatcher
| Knowledge Sources | |
|---|---|
| Domains | Dispatcher, WebSocket |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Concrete tool for intercepting and routing WebSocket connections over the Playwright RPC protocol provided by the Playwright library.
Description
The `WebSocketRouteDispatcher` class extends `Dispatcher` and implements `channels.WebSocketRouteChannel` to enable WebSocket connection interception and mocking. It installs a mock WebSocket script as an init script and page binding that intercepts `new WebSocket()` calls matching specified URL patterns. The dispatcher tracks connections by ID, dispatches `messageFromPage` and `messageFromServer` events, and provides `send`, `close`, and `connectToServer` methods for controlling the WebSocket connection. It handles frame navigation/detach events to clean up when the execution context is lost. A static map (`_idToDispatcher`) maintains all active WebSocket route dispatchers.
Usage
Use WebSocketRouteDispatcher when implementing `page.routeWebSocket()` or `context.routeWebSocket()` to intercept, mock, or modify WebSocket communications during testing.
Code Reference
Source Location
- Repository: Microsoft_Playwright
- File: packages/playwright-core/src/server/dispatchers/webSocketRouteDispatcher.ts
Signature
export class WebSocketRouteDispatcher extends Dispatcher<SdkObject, channels.WebSocketRouteChannel, PageDispatcher | BrowserContextDispatcher> implements channels.WebSocketRouteChannel {
_type_WebSocketRoute: boolean;
constructor(scope: PageDispatcher | BrowserContextDispatcher, id: string, url: string, frame: Frame);
async send(params: channels.WebSocketRouteSendParams, progress: Progress): Promise<void>;
async close(params: channels.WebSocketRouteCloseParams, progress: Progress): Promise<void>;
async connectToServer(params: channels.WebSocketRouteConnectToServerParams, progress: Progress): Promise<void>;
}
Import
import { WebSocketRouteDispatcher } from '../server/dispatchers/webSocketRouteDispatcher';
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| scope | PageDispatcher or BrowserContextDispatcher | Yes | Parent dispatcher scope |
| id | string | Yes | Unique identifier for this WebSocket route |
| url | string | Yes | The WebSocket URL being intercepted |
| frame | Frame | Yes | The frame where the WebSocket was created |
Outputs
| Name | Type | Description |
|---|---|---|
| (events) | messageFromPage, messageFromServer, closePage, closeServer | WebSocket communication events |
Usage Examples
import { WebSocketRouteDispatcher } from '../server/dispatchers/webSocketRouteDispatcher';
// WebSocket route dispatchers are typically created automatically by routeWebSocket()
// The dispatcher intercepts WebSocket connections and provides control methods:
const wsRoute = new WebSocketRouteDispatcher(pageScope, 'ws-1', 'wss://example.com/ws', frame);
await wsRoute.send({ message: 'mock response', isBase64: false }, progress);
await wsRoute.close({ code: 1000, reason: 'done' }, progress);