Trace Viewer

Trace Viewer is Playwright's killer debug feature — a replayable recording of actions, DOM snapshots, network, console, and source maps for failed tests.

Enabling Traces

Config: trace: 'on-first-retry' for CI efficiency, or 'retain-on-failure' for every fail. Traces save to test-results/ as zip files.

Open with npx playwright show-trace path/to/trace.zip or click link in HTML report.

export default defineConfig({
  use: { trace: 'on-first-retry' },
});

// After failure:
npx playwright show-trace test-results/.../trace.zip

Traces include screenshots per action — no separate screenshot needed for debug.

Trace Modes

'off' | 'on' | 'retain-on-failure' | 'on-first-retry' | 'on-all-retries'

on-first-retry balances storage vs debuggability in CI.
retain-on-failure captures every fail — larger artifacts.
Traces work cross-browser — same viewer for all engines.
Share trace.zip with teammates — self-contained.

Trace Viewer Reference

Workflow and config.

Item	Detail
Enable	`use: { trace: 'on-first-retry' }`
Open local	`npx playwright show-trace trace.zip`
CI artifact	Upload test-results on failure
Timeline	Scrub actions, see before/after DOM
Network tab	Request/response per step
Metadata	Test title, project, errors

Traces in CI

# GitHub Actions upload
- uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-traces
    path: test-results/

Source Tab in Traces

Trace Viewer links each action to spec source lines — click a step to jump to the exact line that ran, even in CI-generated traces.

Common Mistakes

trace: 'off' in CI — no debug info on failure.
Not downloading CI trace artifacts before re-running job.
Huge traces from trace: 'on' for all tests — storage cost.
Ignoring network tab in trace when API caused UI fail.

Key Takeaways

Trace Viewer replays full test context after failure.
on-first-retry is the CI sweet spot.
Upload trace artifacts from CI for async debug.
Timeline + network explain most flaky failures.

Pro Tip

Pin HTML report + trace link in PR comment bot — reviewers reproduce failures without checking out branch.