Published
Playwright Trace Viewer: Record, Open, Read Traces
Short answer
Playwright Trace Viewer is a GUI that replays a recorded test action by action, with a DOM snapshot, network log, console output and source line for each step. Set trace: 'on-first-retry' in your config, let CI produce a trace.zip for a failing test, then open it with npx playwright show-trace trace.zip or by dropping the file onto trace.playwright.dev.
Last updated: 2026-11-08
What is the Playwright Trace Viewer?
The Trace Viewer is a tool that lets you explore a recorded Playwright trace after the test has finished. You step backward and forward through each action and see what the page looked like before and after it. Playwright's own docs describe traces as a good way to debug tests that fail on CI, where you cannot watch the browser.
A trace is a trace.zip file. It holds screenshots, DOM snapshots, the action log, console messages and network requests for one test.
How do I record a trace?
For local work, add the --trace flag:
npx playwright test --trace on
For CI, set the option in your config. The Playwright docs recommend recording on the first retry of a failed test:
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 1,
use: {
trace: 'on-first-retry',
},
});
The trace option takes these values:
| Value | What it records |
|---|---|
'on-first-retry' | A trace only when a test is retried for the first time |
'on-all-retries' | A trace for every retry |
'retain-on-failure' | A trace for each test, deleted if the test passes |
'on' | A trace for every test. The docs say this is not recommended because it is performance heavy |
'off' | No trace |
If you do not use retries but still want traces for failed tests, use 'retain-on-failure'. The default config that npm init playwright generates uses on-first-retry with retries set to 2 on CI and 0 locally, so a trace appears on the first retry but not on the first run or the second retry.
If you drive Playwright as a library instead of the test runner, use the browserContext.tracing API: call context.tracing.start({ screenshots: true, snapshots: true }) before you navigate, and context.tracing.stop({ path: 'trace.zip' }) when you are done.
How do I open a trace?
There are three routes.
From the HTML report. Run npx playwright show-report, click a failed test, and click the trace icon next to the test name. This is the quickest path for a local run.
From the command line. Pass the path to the zip file:
npx playwright show-trace path/to/trace.zip
The same command accepts a URL, so you can open a trace stored as a CI artifact without downloading it first:
npx playwright show-trace https://example.com/trace.zip
In the browser. Go to trace.playwright.dev and drag the file onto the page, or use the Select file button. The Playwright docs state that this hosted viewer loads the trace entirely in your browser and does not transmit any data externally. You can also pass a trace URL as a query parameter, for example https://trace.playwright.dev/?trace=<url>, though CORS rules may apply to where the file is hosted.
What do the Trace Viewer tabs show?
Click an action in the left sidebar and the right-hand panels update to that moment.
- Actions. The locator each step used and how long it took. Hover an action to see the DOM change. The Before and After tabs show the page on either side of the action.
- Snapshots. Playwright keeps a Before, an Action and an After DOM snapshot. The Action snapshot highlights the element and the exact click position, which helps when a click lands on the wrong thing.
- Source. The line of your test code for the selected action.
- Call. Duration, locator, and whether strict mode applied.
- Log. What Playwright did behind the scenes, such as scrolling the element into view and waiting for it to be visible, enabled and stable.
- Errors. The error message for a failed test, with a red line on the timeline at the point of failure.
- Console. Logs from the browser and from the test file, with different icons for each.
- Network. Every request, sortable by status, method, content type, duration and size. Click one to see headers and bodies.
- Metadata. Browser, viewport size, test duration and similar details.
- Attachments. For visual comparison tests, the expected image, the actual image and the diff, with a slider to lay one over the other.
Double-click an action and the Console and Network tabs filter to that action. Drag across the timeline to select a range of actions and both tabs filter to that range. Click Show all to clear the filter.
How do I debug a failed CI test with a trace?
- Make sure the config records a trace on retry, and that your CI job uploads the
test-resultsfolder or the HTML report as an artifact. - Download the artifact, or note its URL, and open the failing test's
trace.zipwithshow-trace. - Jump to the red marker on the timeline. Check the Errors tab for the message and the Source tab for the line.
- Look at the Before snapshot of the failing action. Is the element missing, covered, or in a different state than the test expected?
- Open Network and filter to that action. A 4xx or 5xx response, or a request that never returned, usually explains a timeout.
- Check Console for application errors that fired just before the failure.
If the same test passes on retry, the trace of the retry will not help much. Compare the failed attempt's trace with a passing one and look for a difference in network timing or in data the page loaded. Our guides on parallel Playwright runs on GitHub Actions and hardcoded test data that flakes in CI cover two common causes.
What a trace does not tell you
A trace explains one run of one test. It cannot tell you whether the test checks the right thing, whether anyone reviewed it, or what your suite leaves uncovered. When a coding agent writes and repairs your tests, those questions matter more, because a test can be green and still assert very little.
TestChimp works above the trace. It links each Playwright test to a written scenario in your repo, shows coverage against those scenarios, and flags agent-edited tests for human review. Use the Trace Viewer to find out why a test failed, and use TestChimp to see which tests are worth trusting. For the review side, see How to trust AI-written tests.
Frequently asked questions
What is the Playwright Trace Viewer?
It is a GUI tool for exploring a recorded Playwright trace after a test has run. You step through each action and see DOM snapshots, the action log, console output, network requests and the source line.
How do I open a Playwright trace file?
Run npx playwright show-trace path/to/trace.zip, click the trace icon in the HTML report, or drag the zip onto trace.playwright.dev. The hosted viewer loads the trace in your browser and does not send data externally.
How do I enable tracing in Playwright?
Run tests with --trace on for local work, or set trace to on-first-retry in the use section of playwright.config.ts for CI. Use retain-on-failure if you do not use retries but want traces for failed tests.
Why is trace on not recommended?
The Playwright docs say recording a trace for every test is performance heavy. On-first-retry or retain-on-failure keep the cost down while still capturing failures.
Can I open a trace from a CI artifact without downloading it?
Yes. npx playwright show-trace accepts a URL, and trace.playwright.dev accepts a trace query parameter pointing to an accessible location. CORS rules may apply to the hosting location.
Does the Trace Viewer tell me whether my tests are good?
No. It explains how a single run behaved. Judging coverage, review status and which tests matter needs a layer above the runner, which is what TestChimp provides.
Know which Playwright tests are worth trusting
Use traces to debug a failure. Use TestChimp to link tests to scenarios, see coverage, and flag agent-edited tests for review. 14-day free trial, no credit card.