Use Playwright Trace Viewer and built-in debugging tools to diagnose and fix flaky tests
domain: playwright.dev · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Enable tracing in `playwright.config.ts` by setting `use: { trace: 'on-first-retry' }` so a trace is captured automatically whenever a test fails and is retried.
After a failing run, open the trace with `npx playwright show-trace path/to/trace.zip` — the Trace Viewer shows a timeline of actions, DOM snapshots before and after each step, network requests, and console logs.
Use `npx playwright test --debug` to run a single test with the Playwright Inspector open; step through actions, observe the live browser, and use the locator picker to identify stable selectors.
Add `await page.pause()` at any point in a test to halt execution and open the Inspector mid-test for interactive exploration.
For flakiness caused by timing, check the action waterfall in the trace for long gaps between actions and correlate with the network panel to find slow API responses; then add explicit `waitForResponse` or assertion retries rather than `waitForTimeout`.
Known gotchas
Traces can be large when recorded for every test (`trace: 'on'`). In CI, prefer `'on-first-retry'` or `'retain-on-failure'` to balance disk usage against debugging utility.
The Trace Viewer DOM snapshots are taken at each action boundary, not continuously. If an element flickers between two actions, the snapshot may not capture the intermediate state — the network and console tabs often reveal the root cause instead.
`--debug` mode forces the test to run in headed mode with a single worker and disables timeouts. Tests that rely on multiple parallel workers or specific timing may behave differently under debug mode than in a normal run.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?