1# Debugging & Troubleshooting
2 
3## Table of Contents
4 
51. [Debug Tools](#debug-tools)
62. [Trace Viewer](#trace-viewer)
73. [Identifying Flaky Tests](#identifying-flaky-tests)
84. [Debugging Network Issues](#debugging-network-issues)
95. [Debugging in CI](#debugging-in-ci)
106. [Debugging Authentication](#debugging-authentication)
117. [Debugging Screenshots](#debugging-screenshots)
128. [Common Issues](#common-issues)
139. [Logging](#logging)
14 
15## Debug Tools
16 
17### Playwright Inspector
18 
19```bash
20# Run with inspector
21PWDEBUG=1 npx playwright test
22# Or specific test
23PWDEBUG=1 npx playwright test login.spec.ts
24```
25 
26Features:
27 
28- Step through test actions
29- Pick locators visually
30- Inspect DOM state
31- Edit and re-run
32 
33### Headed Mode
34 
35```bash
36# Run with visible browser
37npx playwright test --headed
38 
39# Interactive debugging (headed, paused, step-through)
40npx playwright test --debug
41```
42 
43You can also set `slowMo` to add an `N` ms delay per action, making test execution easier to follow while debugging.
44 
45```typescript
46// playwright.config.ts
47export default defineConfig({
48  use: {
49    launchOptions: {
50      slowMo: 500,
51    },
52  },
53});
54```
55 
56### UI Mode
57 
58```bash
59# Interactive test runner
60npx playwright test --ui
61```
62 
63Features:
64 
65- Watch mode
66- Test timeline
67- DOM snapshots
68- Network logs
69- Console logs
70 
71### Debug in Code
72 
73```typescript
74test("debug example", async ({ page }) => {
75  await page.goto("/");
76 
77  // Pause and open inspector
78  await page.pause();
79 
80  // Continue test...
81  await page.click("button");
82});
83```
84 
85## Trace Viewer
86 
87### Enable Traces
88 
89```typescript
90// playwright.config.ts
91export default defineConfig({
92  use: {
93    trace: "on-first-retry", // Record on retry
94    // trace: 'on',                 // Always record
95    // trace: 'retain-on-failure',  // Keep only failures
96  },
97});
98```
99 
100### View Traces
101 
102```bash
103# Open trace file
104npx playwright show-trace trace.zip
105 
106# From test-results
107npx playwright show-trace test-results/test-name/trace.zip
108```
109 
110### Trace Contents
111 
112- Screenshots at each action
113- DOM snapshots
114- Network requests/responses
115- Console logs
116- Action timeline
117- Source code
118 
119### Programmatic Traces
120 
121```typescript
122test("manual trace", async ({ page, context }) => {
123  await context.tracing.start({ screenshots: true, snapshots: true });
124 
125  await page.goto("/");
126  await page.click("button");
127 
128  await context.tracing.stop({ path: "trace.zip" });
129});
130```
131 
132## Identifying Flaky Tests
133 
134If a test fails intermittently, it's likely flaky. Quick checks:
135 
136| Behavior                               | Likely Cause                  | Next Step                              |
137| -------------------------------------- | ----------------------------- | -------------------------------------- |
138| Fails sometimes, passes other times    | Flaky - timing/race condition | [flaky-tests.md](flaky-tests.md)       |
139| Fails only with multiple workers       | Flaky - parallelism/isolation | [flaky-tests.md](flaky-tests.md)       |
140| Fails only in CI                       | Environment difference        | [CI Debugging](#debugging-in-ci) below |
141| Always fails                           | Bug in test or app            | Debug with tools above                 |
142| Always passes locally, always fails CI | CI-specific issue             | [ci-cd.md](../infrastructure-ci-cd/ci-cd.md)                   |
143 
144> **For flaky test detection commands, root cause analysis, and fixing strategies**, see [flaky-tests.md](flaky-tests.md).
145 
146## Debugging Network Issues
147 
148### Monitor All Requests
149 
150```typescript
151test("debug network", async ({ page }) => {
152  const requests: string[] = [];
153  const failures: string[] = [];
154 
155  page.on("request", (req) => requests.push(`>> ${req.method()} ${req.url()}`));
156  page.on("requestfinished", (req) => {
157    const resp = req.response();
158    requests.push(`<< ${resp?.status()} ${req.url()}`);
159  });
160  page.on("requestfailed", (req) => {
161    failures.push(`FAILED: ${req.url()} - ${req.failure()?.errorText}`);
162  });
163 
164  await page.goto("/dashboard");
165 
166  // Log summary
167  console.log("Requests:", requests.length);
168  if (failures.length) console.log("Failures:", failures);
169});
170```
171 
172### Wait for Specific API Response
173 
174When debugging network-dependent issues, wait for specific API responses instead of arbitrary timeouts.
175 
176```typescript
177// Start waiting BEFORE triggering the request
178const responsePromise = page.waitForResponse(
179  (resp) => resp.url().includes("/api/data") && resp.status() === 200,
180);
181await page.getByRole("button", { name: "Load" }).click();
182const response = await responsePromise;
183console.log("Status:", response.status());
184```
185 
186> **For comprehensive waiting patterns** (navigation, element state, network, polling), see [assertions-waiting.md](../core/assertions-waiting.md#waiting-strategies).
187 
188### Debug Slow Requests
189 
190```typescript
191test("find slow requests", async ({ page }) => {
192  page.on("requestfinished", (request) => {
193    const timing = request.timing();
194    const total = timing.responseEnd - timing.requestStart;
195    if (total > 1000) {
196      console.log(`SLOW (${total}ms): ${request.url()}`);
197    }
198  });
199 
200  await page.goto("/");
201});
202```
203 
204## Debugging in CI
205 
206### Simulate CI Locally
207 
208```bash
209# Run in headless mode like CI
210CI=true npx playwright test
211 
212# Match CI browser versions
213npx playwright install --with-deps
214 
215# Run in Docker (same as CI)
216docker run --rm -v $(pwd):/work -w /work \
217  mcr.microsoft.com/playwright:v1.40.0-jammy \
218  npx playwright test
219```
220 
221### CI-Specific Configuration
222 
223```typescript
224// playwright.config.ts
225export default defineConfig({
226  // More artifacts in CI for debugging
227  use: {
228    trace: process.env.CI ? "on-first-retry" : "off",
229    video: process.env.CI ? "retain-on-failure" : "off",
230    screenshot: process.env.CI ? "only-on-failure" : "off",
231  },
232 
233  // More retries in CI (but investigate failures!)
234  retries: process.env.CI ? 2 : 0,
235});
236```
237 
238### Debug CI Environment
239 
240```typescript
241test("CI environment check", async ({ page }, testInfo) => {
242  console.log("CI:", process.env.CI);
243  console.log("Project:", testInfo.project.name);
244  console.log("Worker:", testInfo.workerIndex);
245  console.log("Retry:", testInfo.retry);
246  console.log("Base URL:", testInfo.project.use.baseURL);
247 
248  // Check viewport
249  const viewport = page.viewportSize();
250  console.log("Viewport:", viewport);
251});
252```
253 
254## Debugging Authentication
255 
256```typescript
257test("debug auth", async ({ page, context }) => {
258  // Inspect current storage state
259  const storage = await context.storageState();
260  console.log(
261    "Cookies:",
262    storage.cookies.map((c) => c.name),
263  );
264 
265  // Check if auth cookies are present
266  const cookies = await context.cookies();
267  const authCookie = cookies.find((c) => c.name.includes("session"));
268  console.log("Auth cookie:", authCookie ? "present" : "MISSING");
269 
270  await page.goto("/protected");
271 
272  // Check if redirected to login (auth failed)
273  if (page.url().includes("/login")) {
274    console.error("Auth failed - redirected to login");
275    // Save state for inspection
276    await context.storageState({ path: "debug-auth.json" });
277  }
278});
279```
280 
281## Debugging Screenshots
282 
283### Compare Visual State
284 
285```typescript
286test("visual debug", async ({ page }, testInfo) => {
287  await page.goto("/");
288 
289  // Screenshot before action
290  await page.screenshot({
291    path: testInfo.outputPath("before.png"),
292    fullPage: true,
293  });
294 
295  await page.getByRole("button", { name: "Open Menu" }).click();
296 
297  // Screenshot after action
298  await page.screenshot({
299    path: testInfo.outputPath("after.png"),
300    fullPage: true,
301  });
302 
303  // Attach to report
304  await testInfo.attach("before", {
305    path: testInfo.outputPath("before.png"),
306    contentType: "image/png",
307  });
308});
309```
310 
311### Screenshot Specific Element
312 
313```typescript
314test("element screenshot", async ({ page }) => {
315  await page.goto("/");
316 
317  const element = page.getByTestId("problem-area");
318 
319  // Screenshot just the element
320  await element.screenshot({ path: "element-debug.png" });
321 
322  // Highlight element in full page screenshot
323  await element.evaluate((el) => (el.style.border = "3px solid red"));
324  await page.screenshot({ path: "highlighted.png" });
325});
326```
327 
328## Common Issues
329 
330### Element Not Found
331 
332```typescript
333// Debug: Check if element exists
334console.log(await page.getByRole("button").count());
335 
336// Debug: Log all buttons
337const buttons = await page.getByRole("button").all();
338for (const button of buttons) {
339  console.log(await button.textContent());
340}
341 
342// Debug: Screenshot before action
343await page.screenshot({ path: "debug.png" });
344await page.getByRole("button").click();
345```
346 
347### Timeout Issues
348 
349```typescript
350// Increase timeout for slow operations
351await expect(page.getByText("Loaded")).toBeVisible({ timeout: 30000 });
352 
353// Global timeout increase
354test.setTimeout(60000);
355 
356// Check what's blocking
357test("debug timeout", async ({ page }) => {
358  await page.goto("/slow-page");
359 
360  // Log network activity
361  page.on("request", (request) => console.log(">>", request.url()));
362  page.on("response", (response) =>
363    console.log("<<", response.url(), response.status()),
364  );
365});
366```
367 
368### Selector Issues
369 
370```typescript
371// Debug: Highlight element
372await page.getByRole("button").highlight();
373 
374// Debug: Evaluate selector in browser console
375// Run in Inspector console:
376// playwright.locator('button').first().highlight()
377 
378// Debug: Get element info
379const element = page.getByRole("button");
380console.log("Count:", await element.count());
381console.log("Visible:", await element.isVisible());
382console.log("Enabled:", await element.isEnabled());
383```
384 
385### Frame Issues
386 
387```typescript
388// Debug: List all frames
389for (const frame of page.frames()) {
390  console.log("Frame:", frame.url());
391}
392 
393// Debug: Check if element is in iframe
394const frame = page.frameLocator("iframe").first();
395console.log(await frame.getByRole("button").count());
396```
397 
398## Logging
399 
400### Capture Browser Console
401 
402```typescript
403test("with logging", async ({ page }) => {
404  page.on("console", (msg) => console.log("Browser:", msg.text()));
405  page.on("pageerror", (error) => console.log("Page error:", error.message));
406  await page.goto("/");
407});
408```
409 
410> **For comprehensive console error handling** (fail on errors, allowed patterns, fixtures), see [console-errors.md](console-errors.md).
411 
412### Custom Test Attachments
413 
414```typescript
415test("with attachments", async ({ page }, testInfo) => {
416  // Attach screenshot to report
417  const screenshot = await page.screenshot();
418  await testInfo.attach("screenshot", {
419    body: screenshot,
420    contentType: "image/png",
421  });
422 
423  // Attach logs or data
424  await testInfo.attach("logs", {
425    body: "Custom log data",
426    contentType: "text/plain",
427  });
428 
429  // Use testInfo for output paths
430  const outputPath = testInfo.outputPath("debug-file.json");
431});
432```
433 
434## Troubleshooting Checklist
435 
436### By Symptom
437 
438| Symptom                                       | Common Causes                                                | Quick Fixes                                                         | Reference                                                                  |
439| --------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------- | -------------------------------------------------------------------------- |
440| **Element not found**                         | Wrong selector, element not visible, in iframe, timing issue | Check locator with Inspector, wait for visibility, use frameLocator | [locators.md](../core/locators.md), [assertions-waiting.md](../core/assertions-waiting.md) |
441| **Timeout errors**                            | Slow network, heavy page load, waiting for wrong condition   | Increase timeout, wait for specific response, check network tab     | [assertions-waiting.md](../core/assertions-waiting.md)                             |
442| **Flaky tests**                               | Race conditions, shared state, timing dependencies           | See comprehensive flaky test guide                                  | [flaky-tests.md](flaky-tests.md)                                           |
443| **Tests pass locally, fail in CI**            | Environment differences, missing dependencies, timing        | Simulate CI locally, check CI logs, verify environment vars         | [ci-cd.md](../infrastructure-ci-cd/ci-cd.md), [flaky-tests.md](flaky-tests.md)                     |
444| **Slow test execution**                       | Not parallelized, heavy network calls, unnecessary waits     | Enable parallelization, mock APIs, optimize waits                   | [performance.md](../infrastructure-ci-cd/performance.md)                                           |
445| **Selector works in browser but not in test** | Element not attached, wrong context, dynamic content         | Use auto-waiting, check iframe, verify element state                | [locators.md](../core/locators.md)                                                 |
446| **Test fails on retry**                       | Non-deterministic data, external dependencies                | Use test data fixtures, mock external services                      | [fixtures-hooks.md](../core/fixtures-hooks.md)                                     |
447 
448### Step-by-Step Debugging Process
449 
4501. **Reproduce the issue**
451 
452   ```bash
453   # Run with trace enabled
454   npx playwright test tests/failing.spec.ts --trace on
455 
456   # If intermittent, run multiple times
457   npx playwright test --repeat-each=10
458   ```
459 
4602. **Inspect the failure**
461 
462   ```bash
463   # View trace
464   npx playwright show-trace test-results/path-to-trace.zip
465 
466   # Run in headed mode to watch
467   npx playwright test --headed
468 
469   # Use inspector for step-by-step
470   PWDEBUG=1 npx playwright test
471   ```
472 
4733. **Isolate the problem**
474 
475   ```typescript
476   // Add debugging points
477   await page.pause();
478 
479   // Log element state
480   console.log("Element count:", await page.getByRole("button").count());
481   console.log("Element visible:", await page.getByRole("button").isVisible());
482 
483   // Take screenshot at failure point
484   await page.screenshot({ path: "debug.png" });
485   ```
486 
4874. **Check related areas**
488   - Network requests: Are API calls completing? (see [Debugging Network Issues](#debugging-network-issues))
489   - Timing: Is auto-waiting working correctly?
490   - State: Is the test isolated? (see [flaky-tests.md](flaky-tests.md))
491   - Environment: Does it work locally but fail in CI? (see [Debugging in CI](#debugging-in-ci))
492 
4935. **Apply fix and verify**
494   - Fix the root cause (not just symptoms)
495   - Run multiple times to confirm stability: `--repeat-each=10`
496   - Check related tests aren't affected
497 
498## Related References
499 
500- **Flaky tests**: See [flaky-tests.md](flaky-tests.md) for comprehensive flaky test guide
501- **Locator issues**: See [locators.md](../core/locators.md) for selector strategies
502- **Waiting problems**: See [assertions-waiting.md](../core/assertions-waiting.md) for waiting patterns
503- **Test isolation**: See [fixtures-hooks.md](../core/fixtures-hooks.md) for fixtures and isolation
504- **CI issues**: See [ci-cd.md](../infrastructure-ci-cd/ci-cd.md) for CI configuration
505