Workflow:Microsoft Playwright Trace recording and debugging
| Knowledge Sources | |
|---|---|
| Domains | Test_Debugging, Trace_Analysis, Test_Automation |
| Last Updated | 2026-02-11 22:00 GMT |
Overview
End-to-end process for recording execution traces during test runs and analyzing them in the Trace Viewer to debug test failures.
Description
This workflow covers Playwright's trace system, which records comprehensive execution traces including DOM snapshots, screenshots, network activity, console logs, and action timelines. Traces are captured as zip archives during test execution and can be opened in the Trace Viewer for visual, step-by-step analysis of what happened during the test. The trace system supports multiple collection strategies (always, on failure, on first retry) and integrates with the HTML reporter for seamless debugging of CI failures.
Usage
Execute this workflow when tests fail intermittently or in CI environments and you need to understand exactly what happened during execution. Also useful when debugging complex multi-step test flows, investigating timing issues, or verifying that tests interact with the correct elements. Particularly valuable for failures that are hard to reproduce locally.
Execution Steps
Step 1: Configure trace collection
Set the trace collection strategy in playwright.config.ts under the use section. The strategy determines when traces are recorded: always, never, only on failure, or on first retry. Configure additional trace options such as including screenshots, snapshots, and source code.
Key considerations:
- trace: 'on-first-retry' is the recommended default (traces on retry only)
- trace: 'on' records every test but increases execution time and storage
- trace: 'retain-on-failure' keeps traces only for failed tests
- Screenshots and DOM snapshots can be independently toggled
- Traces add overhead; use selective strategies in CI
Step 2: Run tests with tracing enabled
Execute the test suite with the configured tracing strategy. Playwright automatically starts and stops trace recording around each test according to the configuration. Trace files are saved as zip archives in the test results directory.
Key considerations:
- Trace files are stored in the test-results/ directory by default
- Each test produces its own trace archive
- Override configuration at runtime with --trace=on CLI flag
- Traces can also be started/stopped programmatically via the context.tracing API
Step 3: Capture trace data
During test execution, the trace system captures multiple types of data at each action: DOM snapshots (full page state), screenshots (visual state), network requests and responses, console messages, and the action call stack. The snapshotter injects scripts into the page to faithfully serialize the entire DOM tree including shadow DOM, iframes, and computed styles.
Key considerations:
- DOM snapshots capture the full document tree with inline styles
- Network data includes request/response headers and bodies
- Console messages and errors are correlated with actions
- Trace format is versioned (currently V8) for forward compatibility
Step 4: Open Trace Viewer
Launch the Trace Viewer using npx playwright show-trace <trace-file> or through the HTML report. The Trace Viewer opens as a web application (or standalone Chromium app) that provides a timeline of all test actions with interactive playback.
Key considerations:
- Trace Viewer can be opened from the HTML report by clicking a failed test
- Use npx playwright show-trace for direct trace file viewing
- The viewer supports both local files and remote URLs
- Multiple traces can be compared side by side
Step 5: Analyze test execution
Step through the recorded trace action by action, examining the DOM snapshot, screenshot, network activity, and console output at each point. Identify the exact moment and cause of failure by comparing expected versus actual page state. Use the source tab to see which line of test code corresponds to each action.
Key considerations:
- Click on any action in the timeline to jump to that point
- The DOM snapshot shows the exact page state before and after each action
- Network tab reveals failed requests, slow responses, or missing resources
- Source tab highlights the test code line for each action
- Use the before/after toggle to see how each action changed the page