Use Playwright Trace Viewer to replay a test’s recorded actions and inspect what the browser showed before, during, and after a failure. For a local run, record a trace with npx playwright test --trace on, then open the resulting trace.zip with npx playwright show-trace path/to/trace.zip. For CI, configure retries and trace: 'on-first-retry' so failed tests retain a trace without routinely recording every passing test.
Record a trace for the failure you need to debug
Local debugging: capture on demand
From your Playwright project directory, run:
npx playwright test --trace onThis records traces for the run. When it finishes, open the HTML report with npx playwright show-report and choose the test’s trace, or open an archive directly:
npx playwright show-trace path/to/trace.zipReplace path/to/trace.zip with the path to the saved archive. Trace Viewer is a GUI for examining a trace after the script has run; it is not a live view of the test.
CI debugging: record a failed test’s first retry
In a Playwright Test configuration file, enable retries and set the trace mode:
Free tools Windows power users keep installed
One-click scans. No signup required.
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: 1,
use: {
trace: 'on-first-retry',
},
});With this configuration, a test that fails is retried once, and its first retry is traced. After the run, open the trace from the HTML report or use show-trace on its archive.
Choose a mode for the debugging situation
| Situation | Approach |
|---|---|
| Reproduce and inspect a local problem | npx playwright test --trace on |
| Capture intermittent CI failures with retries | Set retries and trace: 'on-first-retry' |
| Keep traces for failures when retries are not enabled | Use trace: 'retain-on-failure' |
| Capture on every test routinely | Avoid as the default; Playwright warns this is performance heavy. |
Playwright Test also documents on-all-retries and off. The CLI reference lists additional modes, including retain-on-first-failure and retain-on-failure-and-retries; check the documentation for your installed Playwright version before adopting those less common choices. The documented modes and recommendation are in the Trace Viewer guide and Best Practices.
Find the failing action in Trace Viewer
Start with Actions and the timeline
Select the suspicious or failed entry in the Actions list. The timeline helps place it in the run, while the selected action connects the event to its locator and source location. Use the Before, Action, and After DOM snapshots to compare page state around the interaction. The source panel points to the associated test code.
Do not assume the locator is wrong just because the action failed. First establish what the page contained and what Playwright was waiting for at that step.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Read the action log and call details
Inspect the action log for the sequence Playwright performed. It can show preparatory work such as scrolling and waiting for an element to become visible, enabled, or stable before the action. Call details can include duration, locator, strict-mode status, and a key used. These details help distinguish a locator that matched unexpectedly from an action that was waiting on a changing page.
Compare DOM snapshots and screenshots
Use the DOM snapshots to see the page structure before, during, and after the action; the Action snapshot can help establish where a click landed. When screenshot capture is enabled, the film strip provides visual context along the timeline. Select a time range to focus related actions and console or network entries on that period.
Follow errors back to test source
Use the Errors tab and the red timeline marker to locate the failure, then follow the highlighted source location to the relevant test line. Compare that line with the action log and snapshots before changing a locator or application behavior.
Correlate console and network evidence
- Console: Review browser and test console output. Selecting an action or timeline range filters messages to that period.
- Network: Filter requests by status, method, type, content type, duration, or size. Select a request to inspect its request and response headers and bodies; use the timeline to restrict requests to the relevant period.
- Metadata and attachments: Check browser, viewport, duration, and other test metadata. Attachments may include visual-regression expected and actual images or diffs.
Use these views together to form a cause-and-effect hypothesis, then verify it against the test or application. For example, a click that timed out could reflect an element that never became visible, a request that failed, or a page state that differed from what the test expected; the trace provides evidence to investigate, not an automatic diagnosis.
Recommended Free Tools
Use UI Mode or the HTML report for local investigation
For interactive local debugging, run:
npx playwright test --uiUI Mode lets you step through tests and inspect what happened before, during, and after each step. The HTML report is another useful entry point: run npx playwright show-report and open the trace attached to the relevant test. These workflows are described in the Running Tests guide.
Rank #4
Choose Playwright Test tracing when assertion context matters
For Playwright Test suites, prefer the test-runner trace configuration when debugging failures that involve assertions. The lower-level browserContext.tracing API can record browser operations and network activity, but it does not record test assertions such as expect calls. If using that API, start tracing before the actions you want to capture and stop tracing to export the archive. Playwright says test-runner tracing provides a more complete trace for debugging test failures; see the Tracing API documentation.
Performance, reliability, and trace handling
- Use traces selectively in routine runs. Playwright warns that
trace: 'on'records every test and is performance heavy. Prefer on-demand local traces or failure-focused CI modes. - Keep a trace associated with its test run. Open the archive produced for the run or select the trace attached to that test’s report entry; use the source location and metadata to orient yourself.
- For remote viewing, account for browser access rules. The official guide says trace.playwright.dev loads a trace entirely in the browser and does not transmit it externally. A remote trace must be reachable at its URL, and browser CORS rules may apply.
- Check the installed version’s CLI reference for less common modes. Trace modes and available options can vary by version; use the documentation matching the Playwright version in your project.
Troubleshooting Trace Viewer
The archive does not open
Confirm that the path passed to npx playwright show-trace points to the actual trace archive and that the test run recorded a trace. If the test was run with tracing off, rerun locally with --trace on or configure a failure-retention mode.
The CI failure has no trace
Check that the Playwright Test configuration has retries enabled when using on-first-retry, and confirm the failing test reached a retry. If you need traces without retries, use retain-on-failure. Make sure you are opening the report or archive from the same CI run as the failure.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Clear out junk files and repair common Windows errors3Scan for outdated or missing drivers - takes under a minuteBest Value
The trace has no assertion details
If tracing was started with the lower-level browserContext.tracing API, the absence of test assertions is expected. Configure tracing through Playwright Test for assertion context.
A remote trace URL fails to load
Verify that the URL is accessible to the browser and that its server permits the request under applicable CORS rules. As an alternative, download the archive and open it locally with npx playwright show-trace path/to/trace.zip.
The trace is hard to interpret
Select the failed action first, then narrow the timeline to the moment of interest. Compare the snapshots and call details with source, console messages, and network activity for the same period instead of treating any one panel as conclusive.
Or skip the browser setup
If what you need is a screenshot of a webpage rather than a Playwright test trace, ScreenshotNeo offers a one-request screenshot API and MCP server. It accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents.
For example, this cURL request saves a WebP shot; create an API key and see the ScreenshotNeo API documentation for request options:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpThe Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo to start with the free monthly allowance.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
