Tracing
Playwright · Reference cheat sheet
Tracing
Playwright · Reference cheat sheet
📋 Overview
Traces capture DOM snapshots, network, console, and actions for post-mortem debugging. Open with npx playwright show-trace or the HTML report.
🔧 Core concepts
| Mode | Behavior |
|---|---|
off | No traces |
on | Every test |
retain-on-failure | Keep if failed |
on-first-retry | Recommended default |
Trace viewer shows timeline, before/after snapshots, source, and network.
💡 Examples
Config (recommended):
use: {
trace: 'on-first-retry',
},
retries: process.env.CI ? 2 : 0,CLI:
npx playwright test --trace on
npx playwright show-trace test-results/.../trace.zip
npx playwright show-reportProgrammatic:
await browser.startTracing(page, { path: 'trace.json', screenshots: true });
// ... actions
await browser.stopTracing();Prefer context tracing via config over low-level Chrome tracing.
Debug locally:
PWDEBUG=1 npx playwright test
npx playwright test --debug
npx playwright test --uiUI mode includes time-travel and locator picker; traces complement CI failures.
⚠️ Pitfalls
trace: 'on'in large suites → huge artifacts and slow uploads.- Not downloading CI artifacts — traces stay on the runner.
- Comparing traces across different browsers without noting engine differences.
- Expecting traces without retries when using
on-first-retry. - Zipping/custom paths that the HTML reporter cannot find.