1# WebSocket & Real-Time Testing
2 
3## Table of Contents
4 
51. [WebSocket Basics](#websocket-basics)
62. [Mocking WebSocket Messages](#mocking-websocket-messages)
73. [Testing Real-Time Features](#testing-real-time-features)
84. [Server-Sent Events](#server-sent-events)
95. [Reconnection Testing](#reconnection-testing)
10 
11## WebSocket Basics
12 
13### Wait for WebSocket Connection
14 
15```typescript
16test("chat connects via websocket", async ({ page }) => {
17  // Listen for WebSocket connection
18  const wsPromise = page.waitForEvent("websocket");
19 
20  await page.goto("/chat");
21 
22  const ws = await wsPromise;
23  expect(ws.url()).toContain("/ws/chat");
24 
25  // Wait for connection to be established
26  await ws.waitForEvent("framesent");
27});
28```
29 
30### Monitor WebSocket Messages
31 
32```typescript
33test("receives real-time updates", async ({ page }) => {
34  const messages: string[] = [];
35 
36  // Set up listener before navigation
37  page.on("websocket", (ws) => {
38    ws.on("framereceived", (frame) => {
39      messages.push(frame.payload as string);
40    });
41  });
42 
43  await page.goto("/dashboard");
44 
45  // Wait for some messages
46  await expect.poll(() => messages.length).toBeGreaterThan(0);
47 
48  // Verify message format
49  const data = JSON.parse(messages[0]);
50  expect(data).toHaveProperty("type");
51});
52```
53 
54### Capture Sent Messages
55 
56```typescript
57test("sends correct message format", async ({ page }) => {
58  const sentMessages: string[] = [];
59 
60  page.on("websocket", (ws) => {
61    ws.on("framesent", (frame) => {
62      sentMessages.push(frame.payload as string);
63    });
64  });
65 
66  await page.goto("/chat");
67  await page.getByLabel("Message").fill("Hello!");
68  await page.getByRole("button", { name: "Send" }).click();
69 
70  // Verify sent message
71  await expect.poll(() => sentMessages.length).toBeGreaterThan(0);
72 
73  const sent = JSON.parse(sentMessages[sentMessages.length - 1]);
74  expect(sent).toEqual({
75    type: "message",
76    content: "Hello!",
77  });
78});
79```
80 
81## Mocking WebSocket Messages
82 
83### Inject Messages via Page Evaluate
84 
85```typescript
86test("displays incoming chat message", async ({ page }) => {
87  await page.goto("/chat");
88 
89  // Wait for WebSocket to be ready
90  await page.waitForFunction(
91    () => (window as any).chatSocket?.readyState === 1,
92  );
93 
94  // Simulate incoming message
95  await page.evaluate(() => {
96    const event = new MessageEvent("message", {
97      data: JSON.stringify({
98        type: "message",
99        from: "Alice",
100        content: "Hello there!",
101      }),
102    });
103    (window as any).chatSocket.dispatchEvent(event);
104  });
105 
106  await expect(page.getByText("Alice: Hello there!")).toBeVisible();
107});
108```
109 
110### Mock WebSocket with Route Handler
111 
112```typescript
113test("mock websocket entirely", async ({ page, context }) => {
114  // Intercept the WebSocket upgrade
115  await context.route("**/ws/**", async (route) => {
116    // For WebSocket routes, we can't fulfill directly
117    // Instead, use page.evaluate to mock the client-side
118  });
119 
120  // Alternative: Mock at application level
121  await page.addInitScript(() => {
122    const OriginalWebSocket = window.WebSocket;
123    (window as any).WebSocket = function (url: string) {
124      const ws = {
125        readyState: 1,
126        send: (data: string) => {
127          console.log("WS Send:", data);
128        },
129        close: () => {},
130        addEventListener: () => {},
131        removeEventListener: () => {},
132      };
133      setTimeout(() => ws.onopen?.(), 100);
134      return ws;
135    };
136  });
137 
138  await page.goto("/chat");
139});
140```
141 
142### WebSocket Mock Fixture
143 
144```typescript
145// fixtures/websocket.fixture.ts
146import { test as base, Page } from "@playwright/test";
147 
148type WsMessage = { type: string; [key: string]: any };
149 
150type WebSocketFixtures = {
151  mockWebSocket: {
152    injectMessage: (message: WsMessage) => Promise<void>;
153    getSentMessages: () => Promise<WsMessage[]>;
154  };
155};
156 
157export const test = base.extend<WebSocketFixtures>({
158  mockWebSocket: async ({ page }, use) => {
159    const sentMessages: WsMessage[] = [];
160 
161    // Capture sent messages
162    await page.addInitScript(() => {
163      (window as any).__wsSent = [];
164      const OriginalWebSocket = window.WebSocket;
165      window.WebSocket = function (url: string) {
166        const ws = new OriginalWebSocket(url);
167        const originalSend = ws.send.bind(ws);
168        ws.send = (data: string) => {
169          (window as any).__wsSent.push(JSON.parse(data));
170          originalSend(data);
171        };
172        (window as any).__ws = ws;
173        return ws;
174      } as any;
175    });
176 
177    await use({
178      injectMessage: async (message) => {
179        await page.evaluate((msg) => {
180          const event = new MessageEvent("message", {
181            data: JSON.stringify(msg),
182          });
183          (window as any).__ws?.dispatchEvent(event);
184        }, message);
185      },
186      getSentMessages: async () => {
187        return page.evaluate(() => (window as any).__wsSent || []);
188      },
189    });
190  },
191});
192 
193// Usage
194test("chat with mocked websocket", async ({ page, mockWebSocket }) => {
195  await page.goto("/chat");
196 
197  // Inject incoming message
198  await mockWebSocket.injectMessage({
199    type: "message",
200    from: "Bob",
201    content: "Hi!",
202  });
203 
204  await expect(page.getByText("Bob: Hi!")).toBeVisible();
205 
206  // Send a reply
207  await page.getByLabel("Message").fill("Hello Bob!");
208  await page.getByRole("button", { name: "Send" }).click();
209 
210  // Verify sent message
211  const sent = await mockWebSocket.getSentMessages();
212  expect(sent).toContainEqual(
213    expect.objectContaining({ content: "Hello Bob!" }),
214  );
215});
216```
217 
218## Testing Real-Time Features
219 
220### Live Notifications
221 
222```typescript
223test("displays live notification", async ({ page }) => {
224  await page.goto("/dashboard");
225 
226  // Simulate notification via WebSocket
227  await page.evaluate(() => {
228    const event = new MessageEvent("message", {
229      data: JSON.stringify({
230        type: "notification",
231        title: "New Order",
232        message: "Order #123 received",
233      }),
234    });
235    (window as any).notificationSocket.dispatchEvent(event);
236  });
237 
238  await expect(page.getByRole("alert")).toContainText("Order #123 received");
239});
240```
241 
242### Live Data Updates
243 
244```typescript
245test("updates stock price in real-time", async ({ page }) => {
246  await page.goto("/stocks/AAPL");
247 
248  const priceElement = page.getByTestId("stock-price");
249  const initialPrice = await priceElement.textContent();
250 
251  // Simulate price update
252  await page.evaluate(() => {
253    const event = new MessageEvent("message", {
254      data: JSON.stringify({
255        type: "price_update",
256        symbol: "AAPL",
257        price: 150.25,
258      }),
259    });
260    (window as any).stockSocket.dispatchEvent(event);
261  });
262 
263  await expect(priceElement).not.toHaveText(initialPrice!);
264  await expect(priceElement).toContainText("150.25");
265});
266```
267 
268### Collaborative Editing
269 
270```typescript
271test("shows collaborator cursor", async ({ page }) => {
272  await page.goto("/document/123");
273 
274  // Simulate another user's cursor position
275  await page.evaluate(() => {
276    const event = new MessageEvent("message", {
277      data: JSON.stringify({
278        type: "cursor",
279        userId: "user-456",
280        userName: "Alice",
281        position: { x: 100, y: 200 },
282      }),
283    });
284    (window as any).docSocket.dispatchEvent(event);
285  });
286 
287  await expect(page.getByTestId("cursor-user-456")).toBeVisible();
288  await expect(page.getByText("Alice")).toBeVisible();
289});
290```
291 
292## Server-Sent Events
293 
294### Test SSE Updates
295 
296```typescript
297test("receives SSE updates", async ({ page }) => {
298  // Mock SSE endpoint
299  await page.route("**/api/events", (route) => {
300    route.fulfill({
301      status: 200,
302      headers: {
303        "Content-Type": "text/event-stream",
304        "Cache-Control": "no-cache",
305        Connection: "keep-alive",
306      },
307      body: `data: {"type":"update","value":42}\n\n`,
308    });
309  });
310 
311  await page.goto("/live-data");
312 
313  await expect(page.getByTestId("value")).toHaveText("42");
314});
315```
316 
317### Simulate Multiple SSE Events
318 
319```typescript
320test("handles multiple SSE events", async ({ page }) => {
321  await page.route("**/api/events", async (route) => {
322    const encoder = new TextEncoder();
323    const events = [
324      `data: {"count":1}\n\n`,
325      `data: {"count":2}\n\n`,
326      `data: {"count":3}\n\n`,
327    ];
328 
329    route.fulfill({
330      status: 200,
331      headers: { "Content-Type": "text/event-stream" },
332      body: events.join(""),
333    });
334  });
335 
336  await page.goto("/counter");
337 
338  // Should receive all events
339  await expect(page.getByTestId("count")).toHaveText("3");
340});
341```
342 
343## Reconnection Testing
344 
345### Test Connection Loss
346 
347```typescript
348test("handles connection loss gracefully", async ({ page }) => {
349  await page.goto("/chat");
350 
351  // Simulate connection close
352  await page.evaluate(() => {
353    (window as any).chatSocket.close();
354  });
355 
356  // Should show disconnected state
357  await expect(page.getByText("Reconnecting...")).toBeVisible();
358});
359```
360 
361### Test Reconnection
362 
363```typescript
364test("reconnects after connection loss", async ({ page }) => {
365  await page.goto("/chat");
366 
367  // Simulate disconnect
368  await page.evaluate(() => {
369    (window as any).chatSocket.close();
370  });
371 
372  await expect(page.getByText("Reconnecting...")).toBeVisible();
373 
374  // Simulate reconnection
375  await page.evaluate(() => {
376    const event = new Event("open");
377    (window as any).chatSocket = { readyState: 1 };
378    (window as any).chatSocket.dispatchEvent?.(event);
379  });
380 
381  // Force component to re-check connection
382  await page.evaluate(() => {
383    window.dispatchEvent(new Event("online"));
384  });
385 
386  await expect(page.getByText("Connected")).toBeVisible();
387});
388```
389 
390## Anti-Patterns to Avoid
391 
392| Anti-Pattern                          | Problem                       | Solution                           |
393| ------------------------------------- | ----------------------------- | ---------------------------------- |
394| Not waiting for WebSocket ready       | Messages sent too early       | Wait for `readyState === 1`        |
395| Testing against real WebSocket server | Flaky, timing-dependent       | Mock WebSocket messages            |
396| Ignoring connection state             | Tests pass but feature broken | Test connected/disconnected states |
397| No cleanup of listeners               | Memory leaks in tests         | Clean up event listeners           |
398 
399## Related References
400 
401- **Network**: See [network-advanced.md](../advanced/network-advanced.md) for HTTP mocking patterns
402- **Assertions**: See [assertions-waiting.md](../core/assertions-waiting.md) for polling patterns
403- **Multi-User**: See [multi-user.md](../advanced/multi-user.md) for real-time collaboration testing with multiple users
404