Playwright Trace Viewer

Playwright Trace Viewer is a powerful debugging tool that allows you to analyze test execution after it has completed. This guide covers how to use the Trace Viewer effectively in your testing workflow.

What is Trace Viewer?

Trace Viewer is a web-based tool provided by Playwright that allows you to:

• Review the exact sequence of actions performed during a test
• See screenshots of the browser at each step
• Inspect the DOM state at any point
• View network requests and responses
• Examine console logs and errors
• Debug test failures after they occur

Configuring Trace Collection

To use Trace Viewer, you first need to configure your Playwright tests to collect traces during execution. This is done in your playwright.config.ts file:

use: {
  trace: 'on', // Always capture traces
  // Other options:
  // 'off' - Don't capture traces
  // 'on-first-retry' - Capture only on first retry of failed tests
  // 'retain-on-failure' - Capture and retain only for failed tests
}

Configuration options:

Option	Description
'on'	Capture traces for all tests
'off'	Don't capture any traces
'on-first-retry'	Capture traces only when retrying a failed test
'retain-on-failure'	Capture traces for all tests but retain only for failed tests

In our project, we typically use:

trace: isCI ? 'off' : 'on',

This enables traces in local development but disables them in CI to improve performance.

Viewing Collected Traces

After running tests with trace collection enabled, trace files (.zip) are saved in the test-results directory. To view these traces:

# View the last test run trace
npx playwright show-trace test-results/your-test-name/trace.zip

# Or open directly from the HTML report
# The HTML report has "View trace" links for each test

Trace Viewer Features

Timeline View

The timeline shows all actions performed during the test in chronological order, including:

• Page navigation
• Click events
• Input events
• Network requests
• Console messages

Screenshots

For each action, Trace Viewer captures screenshots of the page state. You can:

• View before and after screenshots for each action
• Hover over timeline points to see the corresponding page state
• Click on a screenshot to enter fullscreen mode

DOM Snapshots

Trace Viewer captures the HTML structure at each step, allowing you to:

• Inspect the DOM as it appeared at specific points in the test
• Use the Elements panel to examine the HTML structure
• Check computed CSS styles
• Verify element properties and attributes

Network Panel

The Network panel shows all network requests made during the test:

• HTTP method and URL
• Response status and size
• Request and response headers
• Request and response bodies
• Timing information

Console Panel

The Console panel displays all console messages from the page:

• Log messages
• Warning messages
• Error messages
• Network errors

Debugging Test Failures

When a test fails, Trace Viewer helps you identify the cause:

1. Open the trace file of the failed test
2. Navigate to the point of failure (usually marked in red)
3. Examine the page state immediately before the failure
4. Check for any console errors or network failures
5. Look at the locator that failed to locate the element
6. Inspect the DOM to see if the element structure changed

Tips for Effective Trace Debugging

1. Use descriptive test names: Makes finding the right trace file easier
2. Add comments in your test code: These will appear in the timeline
3. Minimize trace size in CI: Use retain-on-failure to save only failed test traces
4. Attach trace files to bug reports: Helps developers reproduce and fix issues
5. Review network activity: Many failures are due to API errors or timeouts

Example Debugging Workflow

1. Run tests with trace collection enabled:

   nx e2e my-app

2. If a test fails, open the HTML report:

   open test-results/report/index.html

3. Find the failed test and click "View trace"

4. In Trace Viewer:

   • Navigate to the red failure point in the timeline
   • Check the error message in the log panel
   • Examine the before/after screenshots
   • Inspect the DOM state to verify element selectors
   • Check network requests for any API failures

5. Fix your test based on findings and rerun

CI Integration

When running tests in CI, you can save trace files as artifacts:

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: playwright-traces
    path: test-results/
    retention-days: 7

This allows you to download and analyze traces for tests that failed in CI.

Performance Considerations

Trace collection can impact test performance:

• Increases memory usage during test execution
• Makes tests run slightly slower
• Generates large ZIP files (can be several MB per test)

To mitigate these issues:

• Use trace: 'retain-on-failure' in CI environments
• Clean up old trace files regularly
• Consider disabling traces for smoke tests and enabling for full test suites

Conclusion

Playwright Trace Viewer is an indispensable tool for debugging end-to-end tests. By capturing the entire test execution flow including screenshots, DOM state, and network activity, it provides unparalleled insight into test behavior and makes troubleshooting failures much more efficient.

Video Introduction