Skip to content

testdino-hq/playwright-skill / core

playwright-core

Verified

Battle-tested Playwright patterns for writing and debugging reliable E2E, API, component, visual, accessibility, and security tests. Use when you need locator strategy, assertions, fixtures, network mocking, auth flows, trace debugging, or framework recipes for React, Next.js, Vue, and Angular. TypeScript and JavaScript.

FileKindSize
SKILL.mdskill md5.9 KB
accessibility.mdmarkdown55.4 KB
angular.mdmarkdown39.3 KB
api-testing.mdmarkdown51.7 KB
assertions-and-waiting.mdmarkdown28.5 KB
auth-flows.mdmarkdown36.1 KB
authentication.mdmarkdown49.4 KB
browser-apis.mdmarkdown24.2 KB
browser-extensions.mdmarkdown13.5 KB
canvas-and-webgl.mdmarkdown18.6 KB
clock-and-time-mocking.mdmarkdown17.9 KB
common-pitfalls.mdmarkdown43.9 KB
component-testing.mdmarkdown22.1 KB
configuration.mdmarkdown21.9 KB
crud-testing.mdmarkdown31.3 KB
debugging.mdmarkdown29.6 KB
drag-and-drop.mdmarkdown31.7 KB
dynamic-test-selection.mdmarkdown9.8 KB
electron-testing.mdmarkdown20.7 KB
error-and-edge-cases.mdmarkdown39.4 KB
error-index.mdmarkdown61.7 KB
file-operations.mdmarkdown25.1 KB
file-upload-download.mdmarkdown31.5 KB
fixtures-and-hooks.mdmarkdown33.6 KB
flaky-tests.mdmarkdown34.7 KB
forms-and-validation.mdmarkdown38.0 KB
i18n-and-localization.mdmarkdown23.0 KB
iframes-and-shadow-dom.mdmarkdown20.6 KB
locator-strategy.mdmarkdown19.1 KB
locators.mdmarkdown33.2 KB
mobile-and-responsive.mdmarkdown56.8 KB
multi-context-and-popups.mdmarkdown22.7 KB
multi-user-and-collaboration.mdmarkdown18.6 KB
network-mocking.mdmarkdown45.3 KB
nextjs.mdmarkdown35.4 KB
performance-testing.mdmarkdown21.4 KB
react.mdmarkdown38.3 KB
search-and-filter.mdmarkdown43.6 KB
security-testing.mdmarkdown23.4 KB
service-workers-and-pwa.mdmarkdown18.7 KB
test-agents.mdmarkdown6.0 KB
test-architecture.mdmarkdown23.6 KB
test-data-management.mdmarkdown35.1 KB
test-organization.mdmarkdown29.5 KB
third-party-integrations.mdmarkdown28.4 KB
trace-analysis.mdmarkdown11.1 KB
visual-regression.mdmarkdown37.6 KB
vue.mdmarkdown38.2 KB
webmcp-testing.mdmarkdown10.4 KB
websockets-and-realtime.mdmarkdown21.1 KB
when-to-mock.mdmarkdown25.7 KB

websockets-and-realtime.md

View on GitHub
# WebSockets and Real-Time Testing

> **When to use**: When your application uses WebSockets, Server-Sent Events (SSE), or polling for real-time features -- chat, live dashboards, notifications, collaborative editing, stock tickers, live sports scores.
> **Prerequisites**: [core/assertions-and-waiting.md](assertions-and-waiting.md), [core/fixtures-and-hooks.md](fixtures-and-hooks.md)

## Quick Reference

```typescript
// Listen for WebSocket connections
page.on('websocket', (ws) => {
  console.log('WebSocket opened:', ws.url());

  ws.on('framesent', (frame) => console.log('Sent:', frame.payload));
  ws.on('framereceived', (frame) => console.log('Received:', frame.payload));
  ws.on('close', () => console.log('WebSocket closed'));
});

// Mock a WebSocket via route (Playwright 1.48+)
await page.routeWebSocket('**/ws', (ws) => {
  ws.onMessage((message) => {
    ws.send(JSON.stringify({ echo: message }));
  });
});
```

## Patterns

### Observing WebSocket Traffic

**Use when**: You need to verify that your app sends and receives the correct WebSocket messages without modifying them.
**Avoid when**: You need to intercept or mock the messages. Use `routeWebSocket` instead.

> **Playwright 1.61+**: HAR and trace recordings now include WebSocket requests. For post-mortem debugging you often don't need listener code at all — record a trace and inspect the WS traffic in the Trace Viewer or with `npx playwright trace requests` (see [trace-analysis.md](trace-analysis.md)).

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('chat message is sent over WebSocket', async ({ page }) => {
  const messages: { direction: string; payload: string }[] = [];

  page.on('websocket', (ws) => {
    ws.on('framesent', (frame) => {
      messages.push({ direction: 'sent', payload: String(frame.payload) });
    });
    ws.on('framereceived', (frame) => {
      messages.push({ direction: 'received', payload: String(frame.payload) });
    });
  });

  await page.goto('/chat');
  await page.getByRole('textbox', { name: 'Message' }).fill('Hello!');
  await page.getByRole('button', { name: 'Send' }).click();

  // Wait for the message to appear in UI (confirms round-trip)
  await expect(page.getByText('Hello!')).toBeVisible();

  // Verify WebSocket traffic
  const sentMessage = messages.find(
    (m) => m.direction === 'sent' && m.payload.includes('Hello!')
  );
  expect(sentMessage).toBeDefined();
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('chat message is sent over WebSocket', async ({ page }) => {
  const messages = [];

  page.on('websocket', (ws) => {
    ws.on('framesent', (frame) => {
      messages.push({ direction: 'sent', payload: String(frame.payload) });
    });
    ws.on('framereceived', (frame) => {
      messages.push({ direction: 'received', payload: String(frame.payload) });
    });
  });

  await page.goto('/chat');
  await page.getByRole('textbox', { name: 'Message' }).fill('Hello!');
  await page.getByRole('button', { name: 'Send' }).click();

  await expect(page.getByText('Hello!')).toBeVisible();

  const sentMessage = messages.find(
    (m) => m.direction === 'sent' && m.payload.includes('Hello!')
  );
  expect(sentMessage).toBeDefined();
});
```

### Waiting for a Specific WebSocket Message

**Use when**: Your test depends on a particular server-pushed message before proceeding.
**Avoid when**: The UI already reflects the message. Assert on the UI instead.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('wait for server acknowledgment over WebSocket', async ({ page }) => {
  // Create a promise that resolves when we get the specific message
  const ackPromise = new Promise<void>((resolve) => {
    page.on('websocket', (ws) => {
      ws.on('framereceived', (frame) => {
        const data = JSON.parse(String(frame.payload));
        if (data.type === 'message_ack') {
          resolve();
        }
      });
    });
  });

  await page.goto('/chat');
  await page.getByRole('textbox', { name: 'Message' }).fill('Important update');
  await page.getByRole('button', { name: 'Send' }).click();

  // Wait for server to acknowledge
  await ackPromise;

  // Now verify the message shows a "delivered" checkmark
  await expect(page.getByTestId('message-status').last()).toHaveText('Delivered');
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('wait for server acknowledgment over WebSocket', async ({ page }) => {
  const ackPromise = new Promise((resolve) => {
    page.on('websocket', (ws) => {
      ws.on('framereceived', (frame) => {
        const data = JSON.parse(String(frame.payload));
        if (data.type === 'message_ack') {
          resolve();
        }
      });
    });
  });

  await page.goto('/chat');
  await page.getByRole('textbox', { name: 'Message' }).fill('Important update');
  await page.getByRole('button', { name: 'Send' }).click();

  await ackPromise;
  await expect(page.getByTestId('message-status').last()).toHaveText('Delivered');
});
```

### Mocking WebSocket Messages with `routeWebSocket`

**Use when**: You want to control what the server sends to test specific UI states -- error messages, edge cases, high-volume data -- without a real backend.
**Avoid when**: You need to test actual server behavior. Use a real backend.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('display notification when server pushes an alert', async ({ page }) => {
  const wsRoute = await page.routeWebSocket('**/ws/notifications', (ws) => {
    // Let the app send its initial handshake
    ws.onMessage((message) => {
      const data = JSON.parse(message);
      if (data.type === 'subscribe') {
        ws.send(JSON.stringify({ type: 'subscribed', channel: data.channel }));
      }
    });

    // Push a notification after a short delay
    setTimeout(() => {
      ws.send(JSON.stringify({
        type: 'notification',
        title: 'Server Alert',
        body: 'Deployment completed successfully',
        severity: 'info',
      }));
    }, 500);
  });

  await page.goto('/dashboard');

  // Verify the notification appears in the UI
  await expect(page.getByRole('alert')).toContainText('Deployment completed successfully');
});

test('handle WebSocket server error gracefully', async ({ page }) => {
  await page.routeWebSocket('**/ws', (ws) => {
    // Immediately close with an error code
    ws.close({ code: 1011, reason: 'Internal server error' });
  });

  await page.goto('/chat');

  // App should show a reconnection message, not crash
  await expect(page.getByText('Connection lost. Reconnecting...')).toBeVisible();
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('display notification when server pushes an alert', async ({ page }) => {
  await page.routeWebSocket('**/ws/notifications', (ws) => {
    ws.onMessage((message) => {
      const data = JSON.parse(message);
      if (data.type === 'subscribe') {
        ws.send(JSON.stringify({ type: 'subscribed', channel: data.channel }));
      }
    });

    setTimeout(() => {
      ws.send(JSON.stringify({
        type: 'notification',
        title: 'Server Alert',
        body: 'Deployment completed successfully',
        severity: 'info',
      }));
    }, 500);
  });

  await page.goto('/dashboard');
  await expect(page.getByRole('alert')).toContainText('Deployment completed successfully');
});

test('handle WebSocket server error gracefully', async ({ page }) => {
  await page.routeWebSocket('**/ws', (ws) => {
    ws.close({ code: 1011, reason: 'Internal server error' });
  });

  await page.goto('/chat');
  await expect(page.getByText('Connection lost. Reconnecting...')).toBeVisible();
});
```

#### Inspecting Requested Subprotocols (`webSocketRoute.protocols()`, Playwright 1.60+)

**Use when**: Your client negotiates a WebSocket subprotocol (e.g. `graphql-transport-ws`, `wamp`, a versioned protocol string) and you want to assert it sent the right one, or branch your mock based on it.
**Avoid when**: Your app doesn't use subprotocols — there's nothing to inspect.

Playwright 1.60 adds `webSocketRoute.protocols()`, returning the array of subprotocols the client requested during the handshake.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('client requests the graphql-ws subprotocol', async ({ page }) => {
  await page.routeWebSocket('**/graphql', (ws) => {
    // Assert the client negotiated the expected subprotocol
    expect(ws.protocols()).toContain('graphql-transport-ws');

    ws.onMessage((message) => {
      const data = JSON.parse(message);
      if (data.type === 'connection_init') {
        ws.send(JSON.stringify({ type: 'connection_ack' }));
      }
    });
  });

  await page.goto('/explorer');
  await expect(page.getByText('Connected')).toBeVisible();
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('client requests the graphql-ws subprotocol', async ({ page }) => {
  await page.routeWebSocket('**/graphql', (ws) => {
    expect(ws.protocols()).toContain('graphql-transport-ws');
    ws.onMessage((message) => {
      const data = JSON.parse(message);
      if (data.type === 'connection_init') {
        ws.send(JSON.stringify({ type: 'connection_ack' }));
      }
    });
  });

  await page.goto('/explorer');
  await expect(page.getByText('Connected')).toBeVisible();
});
```

### Forwarding with Modification (Man-in-the-Middle)

**Use when**: You want to connect to the real server but intercept, modify, or inject messages.
**Avoid when**: Full mocking (`routeWebSocket` without `connectToServer`) is sufficient.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('inject a fake high-priority message into real stream', async ({ page }) => {
  await page.routeWebSocket('**/ws/feed', (ws) => {
    const server = ws.connectToServer();

    // Forward all messages from server to client, but inject extras
    server.onMessage((message) => {
      ws.send(message); // Forward the real message
    });

    // Forward all client messages to server
    ws.onMessage((message) => {
      server.send(message);
    });

    // Inject a synthetic message after 1 second
    setTimeout(() => {
      ws.send(JSON.stringify({
        type: 'alert',
        priority: 'high',
        text: 'Injected test alert',
      }));
    }, 1000);
  });

  await page.goto('/live-feed');
  await expect(page.getByText('Injected test alert')).toBeVisible();
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('inject a fake high-priority message into real stream', async ({ page }) => {
  await page.routeWebSocket('**/ws/feed', (ws) => {
    const server = ws.connectToServer();

    server.onMessage((message) => {
      ws.send(message);
    });

    ws.onMessage((message) => {
      server.send(message);
    });

    setTimeout(() => {
      ws.send(JSON.stringify({
        type: 'alert',
        priority: 'high',
        text: 'Injected test alert',
      }));
    }, 1000);
  });

  await page.goto('/live-feed');
  await expect(page.getByText('Injected test alert')).toBeVisible();
});
```

### Server-Sent Events (SSE) Testing

**Use when**: Your app uses `EventSource` for server-to-client streaming (live logs, progress updates, news feeds).
**Avoid when**: The app uses WebSockets. SSE is HTTP-based and intercepted differently.

SSE responses are standard HTTP -- intercept them with `page.route()` and return a streaming response.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('SSE live log stream displays entries', async ({ page }) => {
  // Intercept the SSE endpoint and return controlled events
  await page.route('**/api/logs/stream', async (route) => {
    const events = [
      'data: {"level":"info","message":"Server started"}\n\n',
      'data: {"level":"warn","message":"High memory usage"}\n\n',
      'data: {"level":"error","message":"Connection timeout"}\n\n',
    ];

    await route.fulfill({
      status: 200,
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
      body: events.join(''),
    });
  });

  await page.goto('/admin/logs');

  await expect(page.getByText('Server started')).toBeVisible();
  await expect(page.getByText('High memory usage')).toBeVisible();
  await expect(page.getByText('Connection timeout')).toBeVisible();
});

test('SSE reconnection on connection drop', async ({ page }) => {
  let requestCount = 0;

  await page.route('**/api/events', async (route) => {
    requestCount++;
    if (requestCount === 1) {
      // First request: send one event then close abruptly
      await route.fulfill({
        status: 200,
        headers: { 'Content-Type': 'text/event-stream' },
        body: 'data: {"msg":"first"}\n\n',
      });
    } else {
      // Reconnection: send the next event
      await route.fulfill({
        status: 200,
        headers: { 'Content-Type': 'text/event-stream' },
        body: 'data: {"msg":"reconnected"}\n\n',
      });
    }
  });

  await page.goto('/live');
  await expect(page.getByText('first')).toBeVisible();
  // EventSource auto-reconnects; verify the app handles it
  await expect(page.getByText('reconnected')).toBeVisible({ timeout: 10000 });
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('SSE live log stream displays entries', async ({ page }) => {
  await page.route('**/api/logs/stream', async (route) => {
    const events = [
      'data: {"level":"info","message":"Server started"}\n\n',
      'data: {"level":"warn","message":"High memory usage"}\n\n',
      'data: {"level":"error","message":"Connection timeout"}\n\n',
    ];

    await route.fulfill({
      status: 200,
      headers: {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
      },
      body: events.join(''),
    });
  });

  await page.goto('/admin/logs');

  await expect(page.getByText('Server started')).toBeVisible();
  await expect(page.getByText('High memory usage')).toBeVisible();
  await expect(page.getByText('Connection timeout')).toBeVisible();
});
```

### Polling-Based Real-Time Testing

**Use when**: Your app uses HTTP polling (setInterval + fetch) instead of WebSockets or SSE.
**Avoid when**: The app uses WebSockets or SSE -- use the patterns above.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('polling updates dashboard data every interval', async ({ page }) => {
  let callCount = 0;

  await page.route('**/api/dashboard/stats', async (route) => {
    callCount++;
    const data = callCount === 1
      ? { activeUsers: 100, revenue: 5000 }
      : { activeUsers: 142, revenue: 5250 };

    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify(data),
    });
  });

  await page.goto('/dashboard');

  // First poll result
  await expect(page.getByTestId('active-users')).toHaveText('100');

  // Wait for the second poll to update the UI
  await expect(page.getByTestId('active-users')).toHaveText('142', { timeout: 15000 });

  // Verify at least 2 requests were made
  expect(callCount).toBeGreaterThanOrEqual(2);
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('polling updates dashboard data every interval', async ({ page }) => {
  let callCount = 0;

  await page.route('**/api/dashboard/stats', async (route) => {
    callCount++;
    const data = callCount === 1
      ? { activeUsers: 100, revenue: 5000 }
      : { activeUsers: 142, revenue: 5250 };

    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify(data),
    });
  });

  await page.goto('/dashboard');
  await expect(page.getByTestId('active-users')).toHaveText('100');
  await expect(page.getByTestId('active-users')).toHaveText('142', { timeout: 15000 });
  expect(callCount).toBeGreaterThanOrEqual(2);
});
```

### WebSocket Connection Lifecycle

**Use when**: You need to verify that your app handles connection, disconnection, and reconnection properly.
**Avoid when**: Connection lifecycle is not user-visible.

**TypeScript**
```typescript
import { test, expect } from '@playwright/test';

test('app reconnects after WebSocket drops', async ({ page }) => {
  let connectionCount = 0;

  await page.routeWebSocket('**/ws', (ws) => {
    connectionCount++;

    if (connectionCount === 1) {
      // First connection: close after a brief moment
      setTimeout(() => ws.close({ code: 1006, reason: 'Abnormal closure' }), 500);
    } else {
      // Second connection (reconnect): stay open and respond
      ws.onMessage((message) => {
        ws.send(JSON.stringify({ type: 'pong' }));
      });
    }
  });

  await page.goto('/app');

  // App detects disconnect and shows status
  await expect(page.getByText('Reconnecting...')).toBeVisible();

  // App reconnects and status returns to normal
  await expect(page.getByText('Connected')).toBeVisible({ timeout: 10000 });

  expect(connectionCount).toBe(2);
});
```

**JavaScript**
```javascript
const { test, expect } = require('@playwright/test');

test('app reconnects after WebSocket drops', async ({ page }) => {
  let connectionCount = 0;

  await page.routeWebSocket('**/ws', (ws) => {
    connectionCount++;

    if (connectionCount === 1) {
      setTimeout(() => ws.close({ code: 1006, reason: 'Abnormal closure' }), 500);
    } else {
      ws.onMessage((message) => {
        ws.send(JSON.stringify({ type: 'pong' }));
      });
    }
  });

  await page.goto('/app');
  await expect(page.getByText('Reconnecting...')).toBeVisible();
  await expect(page.getByText('Connected')).toBeVisible({ timeout: 10000 });
  expect(connectionCount).toBe(2);
});
```

## Decision Guide

| Scenario | Approach | Why |
|---|---|---|
| Verify app sends correct WS message | `page.on('websocket')` + `ws.on('framesent')` | Observe without intercepting |
| Verify app handles server push | `page.routeWebSocket()` with mock server | Full control over what the "server" sends |
| Test with real server but inject messages | `routeWebSocket` + `connectToServer()` | Man-in-the-middle: forward real traffic plus inject extras |
| Test SSE endpoint | `page.route()` with `text/event-stream` content type | SSE is HTTP -- standard route interception works |
| Test HTTP polling | `page.route()` with changing responses per call | Increment a counter; return different data each call |
| Verify reconnection logic | `routeWebSocket` that closes the first connection | Simulate server failure, verify the app retries |
| Test binary WebSocket data | `ws.on('framereceived')`, check `frame.payload` as Buffer | Binary frames arrive as `Buffer` in Node.js |

## Anti-Patterns

| Don't Do This | Problem | Do This Instead |
|---|---|---|
| `page.waitForTimeout(3000)` to wait for WS message | Arbitrary delay; flaky and slow | `await expect(page.getByText('msg')).toBeVisible()` or wait on a Promise |
| Directly construct `WebSocket` in `page.evaluate` | You lose Playwright's observation and routing capabilities | Let the app create its own WebSocket; intercept via `routeWebSocket` |
| Ignore WebSocket close codes in mocks | App may behave differently for 1000 (normal) vs 1006 (abnormal) | Use the correct close code: `ws.close({ code: 1000 })` |
| Test real-time features against live third-party servers | Flaky, slow, and may incur costs | Mock the WebSocket or SSE endpoint |
| Assert on raw WebSocket frame content in every test | Couples tests to wire protocol; breaks on payload format changes | Assert on the UI -- that is what users see |
| Forget to handle binary vs text frames | `frame.payload` can be `string` or `Buffer` | Check frame type or use `String(frame.payload)` consistently |

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `page.on('websocket')` never fires | WebSocket connects before the listener is attached | Register the listener before `page.goto()` |
| `routeWebSocket` does not intercept | URL pattern does not match the actual WebSocket URL | Check the URL in DevTools Network tab; update the glob pattern |
| SSE mock returns all events at once | `route.fulfill` sends the body synchronously | For true streaming, use the real server or chunk the response with pauses via `page.evaluate` |
| WebSocket messages arrive but UI does not update | App processes messages asynchronously; assertion runs too early | Use `await expect(...).toBeVisible()` which auto-retries |
| Binary frames show as garbled text | `String(frame.payload)` on binary data produces garbage | Treat `frame.payload` as `Buffer` and decode appropriately |
| Reconnection test is flaky | App has exponential backoff; timeout too short | Increase assertion timeout: `toBeVisible({ timeout: 15000 })` |

## Related

- [core/multi-user-and-collaboration.md](multi-user-and-collaboration.md) -- multi-user tests that rely on WebSocket for real-time sync
- [core/assertions-and-waiting.md](assertions-and-waiting.md) -- auto-retrying assertions for async UI updates
- [core/when-to-mock.md](when-to-mock.md) -- deciding when to mock WebSocket vs use real server
- [core/debugging.md](debugging.md) -- tracing WebSocket frames in Playwright traces
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall