Playwright Test WebSocket Reconnection Logic: A Practical Tutorial

TL;DR

Route the WebSocket before navigation, close the first connection after subscription, and count the next route callback. Assert that the client resubscribes, the UI recovers, and replayed events do not create duplicates.

Key Takeaways

• Register page.routeWebSocket before navigation so every connection attempt is controlled.
• Close the first connection after a meaningful protocol event such as subscription.
• Prove both transport recovery and restoration of logical subscriptions.
• Use expect.poll and locator assertions instead of fixed sleeps.
• Replay a stable event ID to verify duplicate prevention after recovery.
• Unit test exact backoff timing and keep browser timing assertions broad.

To playwright test websocket reconnection logic, register page.routeWebSocket() before navigation, close the first established socket, and assert a second connection without sleeping for a guessed delay. A complete test proves the offline transition, retry, restored subscription, recovered UI, and replay safety.

Use the Playwright WebSocket testing complete guide for the broader strategy. This focused tutorial gives you a paste-ready TypeScript project and a repeatable reconnection workflow.

You will build a small notification page, force a controlled disconnect, count consecutive connections, verify resubscription, replay a message, and attach sanitized recovery evidence to the Playwright report.

TL;DR

Register listeners and routes before the action that creates the socket, usually before page.goto(). Parse JSON payloads before comparing them. Use Playwright locators and web-first assertions for UI results, and avoid fixed delays.

What You Will Build

By the end of this guide, you will have:

• A tiny browser application that connects to a WebSocket endpoint and displays connection state, notifications, and acknowledgments.
• An observation test that records connection URLs and incoming and outgoing frames.
• A mocked WebSocket test that runs without a live real-time backend.
• A reconnection test that forces a disconnect and verifies recovery.
• Reusable helpers for waiting on parsed frames and reporting sanitized diagnostics.

The sample is intentionally small. The same techniques apply to chat, collaborative editing, trading screens, job status monitors, multiplayer features, and any UI driven by persistent bidirectional connections.

Prerequisites

Use Node.js 20 or newer and a current Playwright Test release. Create an empty project and install the runner:

mkdir playwright-ws-guide
cd playwright-ws-guide
npm init -y
npm install -D @playwright/test@latest
npx playwright install chromium

Add these scripts to package.json if you want short commands:

{
  "scripts": {
    "test": "playwright test",
    "test:ws": "playwright test tests/websocket.spec.ts --project=chromium"
  }
}

You should be comfortable with TypeScript, async functions, JSON, locators, and basic WebSocket lifecycle events. You do not need a separate WebSocket package for the mocked tests because Playwright controls the browser connection directly. For deeper test organization, see the Playwright testing complete guide.

Verify the installation with npx playwright --version. Then run npx playwright test --list; an empty project may list no tests, but the command should load without a missing-browser or module error.

Step 1: Set Up Playwright Test WebSocket Reconnection Logic

Create playwright.config.ts so each test starts a local static server. The server command will use a small Node script added in the next step.

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  timeout: 30_000,
  expect: { timeout: 5_000 },
  use: {
    baseURL: 'http://127.0.0.1:4173',
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure'
  },
  webServer: {
    command: 'node server.mjs',
    url: 'http://127.0.0.1:4173',
    reuseExistingServer: !process.env.CI
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } }
  ]
});

The suite begins with Chromium to keep the tutorial focused. Once the behavior is stable, add Firefox and WebKit projects. A browser matrix is valuable, but it should not multiply nondeterministic backend dependencies. Mocked browser integration tests are a good first cross-browser layer.

Verify the step: run npx playwright test --list. Playwright should read the configuration and start looking under tests. If it reports that server.mjs is missing only when a test runs, continue to Step 2.

Step 2: Build a Page That Opens a WebSocket

Create server.mjs. It serves one HTML document and deliberately points the browser at ws://127.0.0.1:4173/ws. Playwright will intercept that URL, so this tutorial needs no real socket server.

import http from 'node:http';

const html = `<!doctype html>
<html lang="en">
  <body>
    <h1>Notification Center</h1>
    <p data-testid="status">connecting</p>
    <span data-testid="count">0</span>
    <ul data-testid="notifications"></ul>
    <button data-testid="subscribe">Subscribe</button>
    <script>
      const status = document.querySelector('[data-testid=status]');
      const count = document.querySelector('[data-testid=count]');
      const list = document.querySelector('[data-testid=notifications]');
      let socket;
      let retry;
      let seen = new Set();
      let subscribed = false;
      window.statusHistory = [];

      function setStatus(value) {
        status.textContent = value;
        window.statusHistory.push(value);
      }

      function connect() {
        setStatus('connecting');
        socket = new WebSocket('ws://127.0.0.1:4173/ws');
        socket.addEventListener('open', () => {
          setStatus('online');
          socket.send(JSON.stringify({ type: 'hello', client: 'web' }));
          if (subscribed) socket.send(JSON.stringify({ type: 'subscribe', channel: 'jobs' }));
        });
        socket.addEventListener('message', event => {
          const message = JSON.parse(event.data);
          if (message.type === 'notification' && !seen.has(message.id)) {
            seen.add(message.id);
            const item = document.createElement('li');
            item.textContent = message.text;
            list.appendChild(item);
            count.textContent = String(seen.size);
          }
          if (message.type === 'subscribed') setStatus('subscribed');
        });
        socket.addEventListener('close', () => {
          setStatus('offline');
          clearTimeout(retry);
          retry = setTimeout(connect, 100);
        });
        socket.addEventListener('error', () => {
          setStatus('error');
        });
      }

      document.querySelector('[data-testid=subscribe]').addEventListener('click', () => {
        subscribed = true;
        socket.send(JSON.stringify({ type: 'subscribe', channel: 'jobs' }));
      });
      connect();
    </script>
  </body>
</html>`;

http.createServer((request, response) => {
  response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });
  response.end(html);
}).listen(4173, '127.0.0.1');

This page models the important states: connecting, online, subscribed, offline, and error. It remembers the logical subscription, sends it again after a new transport opens, records status history, and deduplicates notifications by ID. Production code should use capped exponential backoff with jitter instead of a fixed 100 ms retry. The short interval keeps this isolated example fast.

Verify the step: run node server.mjs, visit http://127.0.0.1:4173, and confirm the heading appears. The status will move to offline or error because no real server accepts the WebSocket. Stop the server before Playwright starts it automatically.

Step 3: Observe the First WebSocket Connection

Before mocking, learn the observation API. Create tests/websocket.spec.ts with a frame collector. The route supplies deterministic traffic while the page-level listener records what the browser sees.

import { test, expect, type Page } from '@playwright/test';

type Frame = { direction: 'sent' | 'received'; payload: string | Buffer };

function observeWebSockets(page: Page) {
  const urls: string[] = [];
  const frames: Frame[] = [];
  const errors: string[] = [];

  page.on('websocket', socket => {
    urls.push(socket.url());
    socket.on('framesent', event => {
      frames.push({ direction: 'sent', payload: event.payload });
    });
    socket.on('framereceived', event => {
      frames.push({ direction: 'received', payload: event.payload });
    });
    socket.on('socketerror', error => errors.push(error));
  });

  return { urls, frames, errors };
}

test('observes the connection and frames', async ({ page }) => {
  const traffic = observeWebSockets(page);

  await page.routeWebSocket('**/ws', ws => {
    ws.onMessage(message => {
      const parsed = JSON.parse(String(message));
      if (parsed.type === 'hello') {
        ws.send(JSON.stringify({ type: 'notification', id: 'n-1', text: 'Build passed' }));
      }
    });
  });

  await page.goto('/');
  await expect(page.getByText('Build passed')).toBeVisible();

  expect(traffic.urls).toContain('ws://127.0.0.1:4173/ws');
  expect(traffic.frames.some(frame => frame.direction === 'sent')).toBe(true);
  expect(traffic.frames.some(frame => frame.direction === 'received')).toBe(true);
  expect(traffic.errors).toEqual([]);
});

page.on('websocket') fires when the page creates a WebSocket. The framesent and framereceived events expose payloads as strings or buffers. Convert deliberately rather than assuming every frame is JSON text. Binary protocols require schema-aware decoding. The socketerror listener is diagnostic evidence, not a replacement for a product assertion.

Register the observer before page.goto(). Otherwise, a socket created during application startup may escape the listener. For a detailed inspection workflow, use inspect Playwright WebSocket frames step by step.

Verify the step: run npm run test:ws. The test should pass, and the page should display Build passed. Temporarily change n-1 to an invalid shape to confirm the visible assertion catches the contract problem.

Step 4: Wait for a Subscription Before Disconnecting

Direct array assertions can race with asynchronous traffic. Create a promise before the triggering action and resolve it only for the expected frame. Add this helper and test:

import type { WebSocket as PlaywrightWebSocket } from '@playwright/test';

function waitForJsonFrame<T>(
  socket: PlaywrightWebSocket,
  direction: 'framesent' | 'framereceived',
  predicate: (value: T) => boolean
): Promise<T> {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => reject(new Error('Timed out waiting for frame')), 5_000);
    socket.on(direction, event => {
      try {
        const value = JSON.parse(String(event.payload)) as T;
        if (predicate(value)) {
          clearTimeout(timer);
          resolve(value);
        }
      } catch {
        // Ignore non-JSON frames when this helper targets a JSON protocol.
      }
    });
  });
}

test('sends a channel subscription frame', async ({ page }) => {
  let browserSocket!: PlaywrightWebSocket;
  page.on('websocket', socket => { browserSocket = socket; });
  await page.routeWebSocket('**/ws', () => {});
  await page.goto('/');
  await expect(page.getByTestId('status')).toHaveText('online');

  const subscription = waitForJsonFrame<{ type: string; channel: string }>(
    browserSocket,
    'framesent',
    frame => frame.type === 'subscribe'
  );
  await page.getByTestId('subscribe').click();

  await expect(subscription).resolves.toEqual({ type: 'subscribe', channel: 'jobs' });
});

The promise is created before the click, so a fast frame cannot be missed. The predicate ignores unrelated heartbeat or hello messages. The helper also owns its timeout, producing a targeted error rather than leaving the test pending until the global timeout. In a large suite, include the expected message type in the timeout error.

Verify the step: run the test with --grep "channel subscription". It should pass. Change the predicate to frame.type === 'missing'; the test should fail after about five seconds with Timed out waiting for frame, proving the failure is localized.

Step 5: Playwright Test WebSocket Reconnection Logic End to End

Now close an established connection and prove that the application creates another one. Add this test to tests/websocket.spec.ts:

test('reconnects and restores the jobs subscription', async ({ page }) => {
  let connectionCount = 0;
  const messagesByConnection: Array<Array<Record<string, unknown>>> = [];

  await page.routeWebSocket('**/ws', ws => {
    const connection = connectionCount++;
    messagesByConnection[connection] = [];
    ws.onMessage(message => {
      const parsed = JSON.parse(String(message)) as Record<string, unknown>;
      messagesByConnection[connection].push(parsed);
      if (parsed.type !== 'subscribe') return;

      ws.send(JSON.stringify({ type: 'subscribed', channel: 'jobs' }));
      if (connection === 0) {
        ws.send(JSON.stringify({ type: 'notification', id: 'job-1', text: 'First delivery' }));
        ws.close();
      } else {
        ws.send(JSON.stringify({ type: 'notification', id: 'job-2', text: 'Recovered delivery' }));
      }
    });
  });

  await page.goto('/');
  await expect(page.getByTestId('status')).toHaveText('online');
  await page.getByTestId('subscribe').click();

  await expect.poll(() => connectionCount).toBe(2);
  await expect.poll(() => page.evaluate(() =>
    (window as Window & { statusHistory: string[] }).statusHistory
  )).toContain('offline');
  await expect(page.getByTestId('status')).toHaveText('subscribed');
  await expect(page.getByText('Recovered delivery')).toBeVisible();
  expect(messagesByConnection[1]).toContainEqual({ type: 'subscribe', channel: 'jobs' });
});

The route handler runs once per connection, so connectionCount proves a retry happened inside the same browser session. This differs from a Playwright test retry, which restarts the entire test. The first mock accepts the subscription, sends one event, and closes the transport. The second stays open and returns a recovery event after the client resubscribes.

The assertions prove four separate facts: the client observed an offline transition, opened a second transport, restored the jobs subscription, and rendered new data. Keep those checks separate because an open socket alone does not mean rooms, filters, cursors, or authentication state were restored. See the Playwright real-time notification examples for more UI checks.

Verify the step: run npx playwright test --project=chromium --grep "reconnects and restores". It should pass. Remove the if (subscribed) statement from the application and run again. The transport reconnects, but the resubscription and recovery assertions fail.

Step 6: Verify Replay Safety After Reconnection

Servers often replay the last acknowledged event after a reconnect. This prevents data loss, but it can duplicate rows, badges, or alerts unless the client uses stable event IDs.

test('does not render a replayed notification twice', async ({ page }) => {
  let connectionCount = 0;
  await page.routeWebSocket('**/ws', ws => {
    const connection = connectionCount++;
    ws.onMessage(message => {
      const parsed = JSON.parse(String(message));
      if (parsed.type !== 'subscribe') return;
      ws.send(JSON.stringify({ type: 'subscribed', channel: 'jobs' }));
      ws.send(JSON.stringify({
        type: 'notification', id: 'stable-42', text: 'Build completed'
      }));
      if (connection === 0) ws.close();
    });
  });

  await page.goto('/');
  await page.getByTestId('subscribe').click();
  await expect.poll(() => connectionCount).toBe(2);
  await expect(page.getByText('Build completed')).toHaveCount(1);
  await expect(page.getByTestId('count')).toHaveText('1');
});

Both connections send the same event ID. The page-level seen set accepts the first delivery and rejects the replay, so the list and count remain stable. Assert more than visible text in a real product. Rendering might hide a duplicate while an unread badge or analytics counter still increments.

If your protocol uses a resume cursor, record the last processed cursor and assert that the second connection sends it. If it uses sequence numbers, test an overlap at the boundary followed by a genuinely new event. The invariant is stable: replayed data is idempotent and new data still arrives.

Verify the step: run npx playwright test --project=chromium --grep "replayed notification". It should pass with one item and a count of one. Remove the seen.has(message.id) check from server.mjs; the test should fail with two items.

Step 7: Attach Sanitized Reconnection Diagnostics

Frame logs are helpful, but raw payloads may contain authorization data, personal details, or private messages. Sanitize structured payloads and attach a bounded transcript only on failure.

function sanitize(payload: string | Buffer): unknown {
  if (Buffer.isBuffer(payload)) return { binaryBytes: payload.length };
  try {
    const value = JSON.parse(payload);
    if (value.token) value.token = '[redacted]';
    if (value.email) value.email = '[redacted]';
    return value;
  } catch {
    return payload.slice(0, 200);
  }
}

test('attaches sanitized socket traffic', async ({ page }, testInfo) => {
  const transcript: unknown[] = [];
  page.on('websocket', socket => {
    socket.on('framesent', event => transcript.push({ sent: sanitize(event.payload) }));
    socket.on('framereceived', event => transcript.push({ received: sanitize(event.payload) }));
  });

  await page.routeWebSocket('**/ws', ws => {
    ws.onMessage(() => ws.send(JSON.stringify({
      type: 'notification', id: 'safe-1', text: 'Profile updated'
    })));
  });
  await page.goto('/');
  await expect(page.getByText('Profile updated')).toBeVisible();

  await testInfo.attach('websocket-transcript', {
    body: Buffer.from(JSON.stringify(transcript.slice(-50), null, 2)),
    contentType: 'application/json'
  });
});

Centralize redaction for your schema. Field-name filtering is only a starting point because secrets can appear in nested structures or unstructured strings. Bound the transcript by frame count and payload length so a busy stream does not exhaust memory or overwhelm a report. Traces, screenshots, console messages, and network evidence together usually explain whether the failure sits in transport, parsing, state, or rendering.

Verify the step: run the test, then open the HTML report with npx playwright show-report. The test attachment should contain sent and received objects, with a maximum of 50 frames. Add a token property locally and confirm the attachment shows [redacted].

Designing a Reliable Test Strategy

Do not put every WebSocket requirement into browser end-to-end tests. Use layers with distinct jobs:

Mocked routes give speed and deterministic edge cases. Real-backend tests reveal proxy configuration, cookies, authentication, TLS, load balancers, and deployment issues that mocks cannot. Keep a small real integration smoke suite and a broader mocked behavior suite. API setup can reduce browser work, as described in Playwright API testing patterns.

Name tests after product behavior, such as restores job subscription after reconnect, rather than implementation details such as websocket test 3. Tag or group them so CI can run mocked tests on every change and real-environment tests where stable infrastructure exists.

Troubleshooting

The route never intercepts the socket -> Register page.routeWebSocket() before page.goto() or before the click that opens the connection. Confirm the glob matches the full WebSocket URL, including its path.

The WebSocket event listener sees no frames -> Attach page.on('websocket') before the socket is created, then attach frame listeners inside that callback immediately. Check whether the application uses WebTransport, server-sent events, or polling instead.

The test passes locally but times out in CI -> Remove arbitrary waits, use locator assertions, and wait for an explicit application state. Confirm the CI proxy permits WebSocket upgrades if the test uses a real backend.

JSON parsing throws for some frames -> Inspect whether the protocol includes heartbeats, plain text, or binary messages. Branch by payload type and message envelope before decoding.

Reconnect creates duplicate messages -> Deduplicate by a stable event ID and test a replayed message after reconnection. Also verify that old subscriptions and listeners are disposed.

The mocked test drifts from production -> Validate fixtures against the owned schema and keep a small real-backend contract or smoke suite. Review protocol changes with both client and service owners.

Common Mistakes and Best Practices

• Do register observers and routes before the connection starts. Do not add them after navigation and assume startup traffic will wait.
• Do assert the visible state caused by a frame. Do not stop at counting transport events.
• Do parse and compare meaningful fields. Do not compare large serialized JSON strings when property order is irrelevant.
• Do wait for a targeted message or web-first UI state. Do not use waitForTimeout() to guess when the stream is ready.
• Do cover closure, malformed data, replay, and reconnection. Do not test only the first successful notification.
• Do preserve one or two real service journeys. Do not assume interception validates authentication, infrastructure, or gateway upgrades.
• Do redact and bound diagnostics. Do not attach unlimited raw customer traffic to CI artifacts.
• Do keep message fixtures readable and schema-aligned. Do not bury protocol intent in giant opaque payloads.

Where To Go Next

You now have a focused observer that captures socket URLs, both frame directions, errors, and close events without guessing about timing. Return to the complete Playwright WebSocket testing guide to place this technique in a layered test strategy.

Next, use the Playwright mock WebSocket server responses tutorial when you need deterministic message branches. Use the step-by-step WebSocket frame inspection guide to diagnose unexpected traffic, then apply the real-time notification assertion examples to badges, ordering, and accessible announcements.

Interview Questions and Answers

Q: How do you inspect WebSocket messages in Playwright?

Listen for the page websocket event, then subscribe to framesent and framereceived on each socket. Parse payloads according to the real protocol and register listeners before the connection begins. Use frame evidence for diagnosis, then assert the resulting application behavior.

Q: How do you mock a WebSocket server in Playwright?

Call page.routeWebSocket() before navigation with a URL pattern and handler. Inside the handler, use ws.onMessage() to read client messages and ws.send() to provide server messages. Use ws.close() when the scenario requires a disconnect.

Q: Why are UI assertions still necessary when frame assertions pass?

A valid frame can be dropped by a parser, reducer, state store, or component. UI assertions prove the user received the intended value. Frame assertions narrow the cause when that outcome fails.

Q: How should a reconnection test avoid flakiness?

Control closure through a mocked route, assert explicit offline and online states, and use retrying assertions such as expect.poll. Avoid narrow elapsed-time assertions and fixed sleeps. Verify restored subscriptions and duplicate protection as separate outcomes.

Q: What can mocked WebSocket tests not prove?

They cannot fully prove production authentication, TLS, reverse-proxy upgrades, load balancer behavior, or service deployment compatibility. Keep a small real-backend smoke or contract layer for those risks.

Q: How do you test binary WebSocket frames?

Treat payloads as buffers and decode them with the real protocol schema. Assert semantic fields after decoding. Never convert arbitrary bytes to text merely to make an assertion convenient.

Q: What is the biggest observability risk in frame logging?

Payloads can expose tokens, personal data, or private content. Redact based on the owned schema, limit stored frames and payload size, and restrict artifact retention and access.

Conclusion

Effective playwright test websocket reconnection logic combines deterministic disconnect control, transport visibility, restored subscriptions, and user-centered assertions. Observe sockets and frames to understand the protocol, use page.routeWebSocket() to exercise hard-to-create states, and prove that the UI handles messages, errors, replays, and reconnects correctly.

Treat each test as evidence for a specific risk. A frame-focused check protects the message contract, a routed scenario protects browser behavior under controlled conditions, and a real-environment smoke test protects the deployment boundary. When a failure occurs, this separation tells you where to investigate first.

Build the mocked happy path first, add disconnection and malformed-data cases, then preserve a small real-backend smoke suite. That layered approach gives fast, explainable tests while still covering the infrastructure that browser mocks cannot reproduce.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Playwright Assert Realtime Notifications Examples: A Practical Tutorial
• Playwright Axe Scan Specific Components Examples: A Practical Tutorial
• Test AI Agent Loop Termination: A Practical Tutorial
• Test MCP Server Secret Leakage: A Practical Security Tutorial
• Appium 3 Driver Version Management: A Practical Tutorial
• Debug Java Test Automation Race Conditions: A Practical Guide