@assertrx/dino 1.0.0

package/skills/playwright-core/websockets-and-realtime.md

@@ -0,0 +1,623 @@
+# 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