🎯 What You Will Learn
Record the smallest failing flow, inspect actions and snapshots, and turn intermittent failures into reproducible evidence.
- Record a focused CLI trace
- Open and inspect a Playwright Test trace
- Use before, action, and after snapshots to find the failure
- Choose practical trace retention settings
Use a Trace as a Timeline
A trace records browser actions, timing, DOM snapshots, network activity, and screenshots. It lets another developer inspect what the page looked like around each action.
Reduce the Failing Flow First
Record the smallest sequence that still fails. A two-minute trace with one relevant click is harder to diagnose than a ten-second trace focused on the problem.
- Start from a known URL and account state.
- Remove unrelated navigation.
- Keep the action that triggers the failure.
- Record one successful and one failing run when possible.
Record a CLI Trace
Start tracing immediately before the suspicious action and stop after the expected or failed result appears.
"$PWCLI" -s=debug open https://example.com --headed
"$PWCLI" -s=debug snapshot
"$PWCLI" -s=debug tracing-start
"$PWCLI" -s=debug click eACTION
"$PWCLI" -s=debug snapshot
"$PWCLI" -s=debug tracing-stopRecord a Test-runner Trace
For a committed test, the trace flag captures assertions and runner context in addition to browser operations.
npx playwright test tests/checkout.spec.ts --trace onOpen Trace Viewer
Open the reported trace zip locally. The viewer presents actions, source, call details, console, network, and DOM snapshots.
npx playwright show-trace path/to/trace.zipInspect Before, Action, and After
Select the failing action and compare its snapshots. Check which locator resolved, what received the click, and whether navigation or a network response completed.
| View | Question |
|---|---|
| Before | Was the intended element visible and enabled? |
| Action | Where did Playwright actually click or type? |
| After | Did the page reach the expected state? |
| Network | Did a request fail, stall, or return unexpected data? |
Retain Useful Traces in the Test Config
Recording every test can be expensive. Retain failures or record on the first retry to balance evidence and artifact size.
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: process.env.CI ? 2 : 0,
use: {
trace: 'on-first-retry',
},
});Know What the Trace Cannot Prove
A trace shows browser state, but it may not include server logs, database state, or third-party outages. Correlate timestamps and request IDs with backend observability.
Sensitive data: Traces can contain page content, headers, and screenshots. Store and share them according to the same policy as test data.
Recap
- Record the smallest failing sequence.
- Use Trace Viewer to compare state around each action.
- Prefer on-first-retry or retain-on-failure policies in larger suites.
- Correlate browser evidence with server-side logs.
Checkpoint: You have completed the workflow and have a repeatable reference for your next Playwright project.