Debugging

CLI Trace inspection — npx playwright trace ... (agent-friendly post-mortem, Playwright 1.59+)

Best when you're driving headless (CI agent, remote SSH, container with no display) or you want to grep across trace contents programmatically.

# Extract the trace for inspection
npx playwright trace open path/to/trace.zip

# List all actions; --grep narrows to a substring
npx playwright trace actions
npx playwright trace actions --grep "expect"

# Drill into one action (use the action number from the listing)
npx playwright trace action 9

# DOM snapshots before / after the action (uses playwright-cli under the hood)
npx playwright trace snapshot 9 --name before
npx playwright trace snapshot 9 --name after

# Network / console / errors / screenshots / attachments
npx playwright trace requests
npx playwright trace console
npx playwright trace errors
npx playwright trace screenshot 9

# Done — clean up the extracted data
npx playwright trace close

This is the same trace data as show-trace, but addressable from the terminal. Switch between GUI and CLI based on context — they're not exclusive.

Playwright Inspector — npm run test:debug (interactive breakpoint stepping)

Best when you suspect logic in your test/page object and want to step through it line-by-line in the GUI Inspector.

• The browser opens with the inspector overlay.
• F10 to step over each action.
• Set breakpoints in code (debugger;) and they trigger.
• Locator highlight in the page makes selector verification trivial.

For agent-driven stepping (no GUI), use npx playwright test --debug=cli instead — Playwright pauses and prints playwright-cli attach <session-id> so an agent can drive playwright-cli --session=<id> step-over / ... snapshot / etc. from the terminal. Same lifecycle, headless-friendly.

Headed mode — npm run test:headed

Best when you need to watch the browser do something specific you can't see in trace replay (animations, async loading races, tooltip behaviour).

Phase 5: Apply the fix at the root cause

Map the diagnosis to a fix in the right place. Do not patch in the test if the bug lives in a page object or schema.

Phase 6: Re-run and confirm stability

A green run after one fix is not enough.

# Re-run the affected file with retries off
npx playwright test tests/app/functional/login.spec.ts --workers=1 --retries=0

# Re-run 5 consecutive times for confidence on flakiness fixes
for i in 1 2 3 4 5; do npx playwright test tests/app/functional/login.spec.ts --workers=1 --retries=0 || break; done

# Then re-run the full affected suite
npm test

Confirm:

• The originally failing test passes.
• No other test in the file was broken by the fix.
• Lint is clean (npx eslint .).
• No test.only(...) left behind (CI's forbidOnly will catch it, but you should catch it first).

Phase 7: Investigate a CI-only failure (red CI, green local)

When the test passes locally but fails in CI, you need CI's artifacts to reproduce.

1. Download the CI artifacts. GitHub Actions: Actions → <run> → Summary → Artifacts → playwright-report (and test-results if separate). Or via gh: gh run download <run-id> -n playwright-report.

2. Open the report locally. Unzip playwright-report.zip; the trace zips for failed tests live under data/.

3. Open the failed trace.

   # GUI -- desktop browser, fastest manual review
   npx playwright show-trace path/to/trace.zip
   
   # CLI -- headless / SSH / agent-driven, scriptable (Playwright 1.59+)
   npx playwright trace open path/to/trace.zip
   npx playwright trace actions
   npx playwright trace action <id>
   npx playwright trace snapshot <id> --name after
   npx playwright trace close

4. Compare environments.

   • Different env file? CI usually has its own env/.env.ci or relies on shell env.
   • Different storage state? Check whether auth.setup.ts ran and produced .auth/app/appStorageState.json.
   • Different viewport / device? playwright.config.ts chromium project uses 1920x1080; if your local default differs, layout-sensitive locators may behave differently.
   • Different browser version? CI installs whatever the Docker image / @playwright/test version brings.

5. Replay the same conditions locally.

   ENVIRONMENT=ci CI=1 npx playwright test <file> --workers=1 --retries=0

6. If still green locally, the failure is genuinely environment-driven (network, timing, state). Add temporary instrumentation (console.log, screenshot, --trace on), commit, run in CI, inspect new artifacts, then remove the instrumentation before merging.

See Also

• api-testing skill — Phase 7 behaviour-mismatch protocol (test.skip + // FIXME:), Phase 6 negative-coverage patterns where the same ZodError types appear.
• refactor-values skill — when a fix involves changing an enum value, an enum key, or a static-data file (cascading updates and verification).
• selectors skill — locator priority, scoping for strict-mode violations, exploration-first workflow when a locator no longer matches.
• page-objects skill — where action methods live; page.waitForResponse(...) belongs there, not in the spec.
• fixtures skill — fixture lifecycle, registration; "fixture is undefined" errors live here.
• helpers skill — auth bootstrap and how process.env.ACCESS_TOKEN is populated; debug undefined token errors here.
• test-standards skill — single-tag rule, destructive cleanup, test independence (Phase 9) — the source of most "passes alone, fails in suite" issues.
• type-safety skill — Zod 4 patterns, expect(Schema.parse(body)).toBeTruthy(); enforcement, zInput vs zOutput confusion behind unexpected ZodErrors.
• config skill — env file selection (ENVIRONMENT), process.env.* correctness, where APP_URL / API_URL are sourced.
• common-tasks skill — Phase 7 (Run tests) routes failures here; verification checklist.
• ai-native-workflow skill — the meta workflow: how to ask, how to escalate, how to commit a fix, and the audit-then-edit pattern that keeps debugging sessions consistent across agents.
• references/examples.md — four worked debug scenarios (action timeout, ZodError contract drift, suite-only failure, CI-only failure).
• references/troubleshooting.md — common debugging pitfalls (missing trace, stale report, committed test.only, UI Mode resource use, timeout bump, suppressed expect, flake diagnosis, destructive leak, cross-browser).