Playwright Trace Viewer: Debug Failed Runs

When a browser script fails on a server at three in the morning, the error message rarely tells the whole story. "Timeout waiting for locator" could mean the page never loaded, a cookie banner covered the button, the site changed its layout or the network call behind the page failed. Reproducing the problem locally can take hours, and sometimes the failure never happens on your machine at all. The Playwright trace viewer solves much of this by letting you replay a recorded run step by step: what the script did, what the page looked like before and after each action, and which network requests and console messages appeared along the way. This guide explains how to record traces, how to read them and how to handle trace files safely.

What the Playwright trace viewer shows

The Playwright documentation describes the trace viewer as a GUI tool for exploring recorded Playwright traces after a script has run (Playwright: Trace viewer). A trace is a zip file containing a record of the run. Opening it shows:

• An actions list, with the locator used for every action and how long each one took
• DOM snapshots captured before an action, at the moment of input and after it, with the exact click position highlighted
• Screenshots along a timeline, so you can scrub through the run visually
• Network requests and console logs, which can be filtered to the actions you select
• The source code location of each action

Together these usually answer the key question quickly: was the problem in the script, in the page or in the network?

Record traces where failures happen

Tracing is switched on per browser context. In a plain script, you start tracing on the context before opening pages, choosing whether to capture screenshots, snapshots and sources, and stop it at the end with a path for the zip file. The documentation includes examples of exactly this pattern.

For test suites, Playwright offers options that record traces only when they are useful. The documentation for the pytest plugin lists modes such as recording a trace for each test, or recording each test but removing traces from successful runs. For CI, the Node.js version of the documentation recommends recording traces on the first retry of a failed test. The aim is the same in each case: keep traces for failures, without filling storage with traces of runs that worked.

For scheduled automation outside a test framework, a simple approach is to start tracing for every run, then save the trace file only when the run fails and discard it otherwise.

Open and read a trace

You can open a saved trace with the Playwright command-line tool or by dragging it into the hosted viewer at trace.playwright.dev. The documentation states that the hosted viewer loads the trace entirely in your browser and does not transmit any data externally, which matters when traces contain business data.

A practical reading order:

1. Find the failed action in the actions list and note the error.
2. Look at the before and after snapshots for that action. Is the element visible? Is something covering it? Is the page the one you expected?
3. Step back through earlier actions to see where the page first diverged from what the script assumed.
4. Check network requests around the failure for errors, redirects or slow responses.
5. Check console messages for script errors on the page.

Many failures turn out to be a different page state than expected: a consent dialog, a login page after a session expired, or an empty-state message when there was no data.

Worked example: hypothetical failure triage

The table below shows hypothetical findings from traces of a nightly report download and the fixes they point to. It illustrates how to use traces, not results from real runs.

Symptom in error logWhat the trace showedLikely fixTimeout clicking ExportCookie banner covering the button in the before snapshotHandle the banner explicitly at the startTimeout waiting for report tableLogin page in the after snapshot of the navigationDetect expired session and sign in againWrong file downloadedClick landed on a newly added button with similar textUse a more specific role and name locatorTable emptyNetwork response for the data call returned an errorRetry later, alert if it persistsIntermittent failureData request finished after the script checked the tableWait for the expected content, not a fixed time

Store trace files safely

Traces capture what the browser saw. That can include personal data on pages, values typed into forms, cookies and request headers. Treat trace files as sensitive:

• Store them in a location with restricted access, not in a public bucket or a shared chat
• Set a retention period and delete old traces automatically
• Avoid tracing login steps where possible, or make sure credentials are not typed in a way the trace records
• Do not attach traces to tickets in systems with broad access; link to a secure location instead

Make traces part of monitoring

Traces are most useful when they are easy to reach from an alert. When a run fails, include a link to the saved trace, the failed step and the target URL in the alert message. Our guide to web scraping monitoring explains how to design alerts that catch breaks early. Review traces from repeated failures together; a pattern across several runs often reveals a site change that a single trace might not.

Use traces to improve scripts

Beyond fixing individual failures, traces show where scripts are slow or fragile. Long waits on particular actions, repeated retries or locators that sometimes match the wrong element are all visible in the actions list. Fix these proactively. If you recorded the script with the test generator, our guide to Playwright codegen covers how to refine recorded locators into ones that last.

Know the limits

A trace records one run of one browser context. It will not show what happened on the server you were calling, and it cannot tell you why a site decided to show a different page. For that, combine traces with your own logs, response codes and run history. Tracing also captures extra data on every run, so check the effect on run time and storage before turning on full tracing for very large jobs.

Frequently Asked Questions

What is the Playwright trace viewer?

It is a tool for replaying a recorded Playwright run, showing each action, DOM snapshots before and after it, screenshots, network requests and console logs.

Should I record traces for every run?

Usually not. Record traces for failures, for example by tracing every run and keeping the file only when a run fails, or by using the test runner's options for failed or retried tests.

Is it safe to open traces at trace.playwright.dev?

The Playwright documentation states that the hosted viewer loads traces entirely in your browser and does not transmit data externally. Still store and share trace files carefully, because they can contain sensitive data.

What do traces not show?

They do not show what happened on the remote server. Combine them with response codes, your own logs and run history.

Debug browser automation faster

We set up tracing, alerting and triage for browser automations so failures are understood and fixed quickly. See our B2B lead mining and prospect verification service, or talk to us about the Playwright trace viewer.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.