Interface WebSocketRoute

Whenever a WebSocket route is set up with page.routeWebSocket(url, handler) or browserContext.routeWebSocket(url, handler), the WebSocketRoute object allows to handle the WebSocket, like an actual server would do.

Mocking

By default, the routed WebSocket will not connect to the server. This way, you can mock entire communcation over the WebSocket. Here is an example that responds to a "request" with a "response".

await page.routeWebSocket('wss://example.com/ws', ws => {
  ws.onMessage(message => {
    if (message === 'request')
      ws.send('response');
  });
});
Copy

Since we do not call webSocketRoute.connectToServer() inside the WebSocket route handler, Playwright assumes that WebSocket will be mocked, and opens the WebSocket inside the page automatically.

Here is another example that handles JSON messages:

await page.routeWebSocket('wss://example.com/ws', ws => {
  ws.onMessage(message => {
    const json = JSON.parse(message);
    if (json.request === 'question')
      ws.send(JSON.stringify({ response: 'answer' }));
  });
});
Copy

Intercepting

Alternatively, you may want to connect to the actual server, but intercept messages in-between and modify or block them. Calling webSocketRoute.connectToServer() returns a server-side WebSocketRoute instance that you can send messages to, or handle incoming messages.

Below is an example that modifies some messages sent by the page to the server. Messages sent from the server to the page are left intact, relying on the default forwarding.

await page.routeWebSocket('/ws', ws => {
  const server = ws.connectToServer();
  ws.onMessage(message => {
    if (message === 'request')
      server.send('request2');
    else
      server.send(message);
  });
});
Copy

After connecting to the server, all messages are forwarded between the page and the server by default.

However, if you call webSocketRoute.onMessage(handler) on the original route, messages from the page to the server will not be forwarded anymore, but should instead be handled by the handler.

Similarly, calling webSocketRoute.onMessage(handler) on the server-side WebSocket will stop forwarding messages from the server to the page, and handler should take care of them.

The following example blocks some messages in both directions. Since it calls webSocketRoute.onMessage(handler) in both directions, there is no automatic forwarding at all.

await page.routeWebSocket('/ws', ws => {
  const server = ws.connectToServer();
  ws.onMessage(message => {
    if (message !== 'blocked-from-the-page')
      server.send(message);
  });
  server.onMessage(message => {
    if (message !== 'blocked-from-the-server')
      ws.send(message);
  });
});
Copy