Learning center

Capture and replay the WebSocket messages behind a realtime bug

A live dashboard shows a number twice, a chat message appears out of order, a notification never arrives. When the data comes over a WebSocket, the HTTP requests in the Network panel show only the connection being opened. The evidence is in the messages. Capture the frames around the failure, then replay them to the page without the server.

Read the frames#

In Chrome DevTools, select the WebSocket request in the Network panel (filter by Socket) and open its Messages tab. It lists every frame with its direction, time and length, and the content for text frames. A filter box narrows the list, which helps on a busy socket. Chrome DevTools: Inspect WebSocket traffic

Copy the frames around the failure, in order, with their times. The order is usually the point: a duplicate, a message before its subscription, an update arriving before the snapshot it updates.

Chrome's HAR export includes WebSocket messages for the socket requests it lists, in a non-standard _webSocketMessages field. Check the export for it before relying on a HAR for socket evidence, and clean it the same way: Share a HAR file.

Capture them from a script#

Playwright reports a page's WebSockets and their frames:

page.on('websocket', ws => {
  ws.on('framesent', f => console.log(Date.now(), 'sent', ws.url(), f.payload));
  ws.on('framereceived', f => console.log(Date.now(), 'recv', ws.url(), f.payload));
  ws.on('close', () => console.log(Date.now(), 'closed', ws.url()));
});

Playwright: WebSocket

Replay them to the page#

Playwright's routeWebSocket replaces the server for a WebSocket URL. The page connects as usual and the script decides what it receives:

await page.routeWebSocket('wss://realtime.example.test/socket', ws => {
  ws.onMessage(message => {
    if (message === 'subscribe:orders') {
      ws.send('{"type":"order","id":1}');
      ws.send('{"type":"order","id":1}'); // the duplicate the reporter received
    }
  });
});

We ran this against a test page in Chromium with no server behind the URL. The page's socket opened, sent subscribe:orders, and received both copies of the message. One thing surprised us: with the socket fully mocked, the page.on('websocket') listener above logged no frames. A mocked socket is not observed as network traffic, so read what the page received from the page itself or from the mock. Playwright: page.routeWebSocket()

A route can also connect to the real server with ws.connectToServer() and pass messages through, changing or holding only the ones the bug needs. That is the WebSocket version of holding one response.

What to put in the report#

  • The socket URL, without tokens in its query string
  • The frames around the failure, in order, with timestamps and direction
  • Whether the connection closed or reconnected nearby, with the close code if shown
  • What the page displayed after the last frame

Worked example: a total that counted one order twice#

This example is fictional. An operations dashboard sometimes shows one more order than the database holds. A tester captures the socket's messages when it happens.

The frames show the socket closing with code 1006, reconnecting, the client sending subscribe:orders again, and the server replaying the last order on resubscription. The client added it a second time. The developer replays the sequence with routeWebSocket: one order, then the same order again after a resubscription. The total is off by one every run. The fix kept a set of seen order IDs on the client.

Questions#

What about Server-Sent Events?

An EventSource stream appears in the Network panel with an EventStream tab listing each event. It is an ordinary HTTP response, so a recorded body can be replayed with route.fulfill().

Can frames hold personal data?

Often. Chat messages, account updates and tokens in subscription messages are common. Replace values with synthetic ones before sharing, keeping the message shapes.

The socket uses a binary protocol. What then?

The Messages tab shows binary frames as base64 or hex. Decode them with the protocol's schema, or capture the decoded objects in the page where the app parses them.

Return to reproducing what someone else saw for the other layers a replay needs.

One month of free code review.

New organizations get one calendar month of hosted code review for private and public GitHub repositories. No card or cloud connection required. Eligibility and fair-use terms.

Start free with GitHub

Related reading