What Is Playwright Trace Viewer? – Definition and How to Use It
Learn what a Playwright trace records, how the viewer reconstructs a run, and why it is the fastest way to diagnose a headless failure.
Trace Viewer replays a recorded Playwright run: every action, the DOM before and after it, network activity, console output, and screenshots. It turns "it failed on the server" into something you can inspect.
1. Recording a Trace
context.tracing.start(screenshots=True, snapshots=True, sources=True)
try:
collect(page)
finally:
context.tracing.stop(path="trace.zip")
The output is a single archive. Opening it locally shows the whole run, regardless of where it executed.
2. What a Trace Contains
| Element | Use |
|---|---|
| Action timeline | What ran, in order, with durations |
| DOM snapshots | The page before and after each action |
| Screenshots | What it looked like at each step |
| Network log | Every request and response |
| Console output | Page errors and logs |
| Source locations | Which line issued each action |
The DOM snapshots are the distinguishing feature: they are inspectable, so selectors can be tested against the state at the moment of failure.
3. Why It Matters for Headless Runs
A headless failure on a server offers a stack trace and nothing else. The question is always the same — what did the page actually look like — and only a trace answers it.
That is why recording on failure is worth the overhead: the alternative is reproducing a failure that may not reproduce.
4. Diagnosing With It
- Find the failing action on the timeline.
- Inspect the DOM snapshot at that moment — did the element exist?
- Look at the screenshot — was an overlay covering it?
- Check the network log — did the data request succeed?
- Read the console — did a page error break rendering?
That sequence resolves most failures without a single re-run.
5. Recording Selectively
Tracing costs time and produces sizeable archives, so recording every run is usually wasteful.
The practical pattern is to record on retry: run normally, and if a task fails, run it again with tracing enabled and keep that archive. Failures become diagnosable without paying the cost on every success.
6. Store Traces With the Failure
A trace is only useful if it is retained with the record of what failed. Uploading the archive alongside the error, keyed by task identifier, is what makes a later investigation possible.
Traces containing authenticated sessions should be treated as sensitive — they record cookies and page content.
7. Beyond Debugging
Traces also document behaviour: a recorded run shows exactly what a collector did on a site, which is useful for review and for explaining a process to someone who did not write it.
8. Summary
Trace Viewer replays a Playwright run from a recorded archive, including action timeline, DOM snapshots, screenshots, network, and console output.
It is the fastest route from a headless failure to an understood cause, best recorded selectively on retry, and stored with the failure record — while remembering that traces of authenticated sessions are sensitive.