Playwright Trace Viewer

Trace Viewer is one of Playwright's most powerful debugging tools. It records everything that happens during test execution, allowing you to inspect actions, network requests, screenshots, console logs, and DOM snapshots after a test run.

Instead of guessing why a test failed, Trace Viewer lets you replay the entire execution step-by-step and identify the exact cause of the issue.

What is Trace Viewer?

Trace Viewer is a visual debugging tool that records and displays:

  • User actions performed during test execution
  • Screenshots captured at each step
  • DOM snapshots
  • Network activity
  • Console logs
  • Timing information
  • Error details

It helps testers and developers quickly analyze test failures and understand application behavior.

Why Use Trace Viewer?

  • Debug failed tests efficiently
  • Replay test execution step-by-step
  • View screenshots for every action
  • Inspect network requests and responses
  • Analyze application state at any point in time
  • Reduce troubleshooting time

How Trace Viewer Works

During test execution, Playwright records trace data into a ZIP file. This file can later be opened in Trace Viewer for detailed analysis.

Typical Workflow:

  1. Enable tracing
  2. Execute test cases
  3. Generate trace file
  4. Open Trace Viewer
  5. Analyze recorded execution

Enable Trace Viewer in Playwright Configuration

Configure tracing inside playwright.config.js. 

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'on'
  }
});

This records traces for every test execution.

Trace Recording Options

Option Description
on Always record traces
off Disable tracing
retain-on-failure Keep traces only for failed tests
on-first-retry Record traces only during first retry

Recommended Configuration

Most automation teams use trace recording only when tests fail. 

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'retain-on-failure'
  }
});

This reduces storage usage while still providing valuable debugging information.

Running Tests with Trace Recording

npx playwright test

If tracing is enabled, Playwright automatically generates trace files during execution.

Opening Trace Viewer

Open a generated trace file using the following command: 

npx playwright show-trace trace.zip

This launches the Trace Viewer interface in your browser.

Manual Trace Recording

You can start and stop tracing programmatically. 

import { chromium } from 'playwright';

const browser = await chromium.launch();
const context = await browser.newContext();

await context.tracing.start({
  screenshots: true,
  snapshots: true
});

const page = await context.newPage();

await page.goto('https://example.com');

await context.tracing.stop({
  path: 'trace.zip'
});

await browser.close();

Trace Viewer Interface

The Trace Viewer dashboard contains several important sections:

  • Action Timeline
  • Screenshots
  • DOM Snapshots
  • Network Requests
  • Console Messages
  • Source Code View

Action Timeline

The timeline displays every action executed during the test.

Examples:

  • Page navigation
  • Button clicks
  • Text input
  • Assertions
  • API requests

Clicking any action shows detailed information about that step.

Screenshots

Trace Viewer captures screenshots during execution.

This allows you to see exactly what was displayed on the screen at each step.

Useful for:

  • UI validation
  • Failure investigation
  • Visual debugging

DOM Snapshots

DOM snapshots capture the page structure at each action.

You can inspect elements and verify whether they existed when the action was executed.

Network Monitoring

Trace Viewer records all network requests and responses.

Information Available:

  • Request URL
  • HTTP Method
  • Status Code
  • Response Headers
  • Request Timing

Console Logs

Browser console messages are captured during execution.

Examples:

console.log('Login successful');

console.error('API failed');

console.warn('Validation warning');

These logs can be reviewed directly inside Trace Viewer.

Source Code View

Trace Viewer displays the exact line of test code responsible for each action.

This makes it easy to connect test failures with the corresponding automation code.

Combining Trace with Screenshots and Videos

Playwright allows tracing, screenshots, and video recording together. 

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure'
  }
});

Example Test with Trace Viewer

import { test, expect } from '@playwright/test';

test('User Login', async ({ page }) => {

  await page.goto('https://example.com/login');

  await page.fill('#username', 'admin');

  await page.fill('#password', 'password');

  await page.click('#loginBtn');

  await expect(page)
    .toHaveURL(/dashboard/);

});

If this test fails, the generated trace file can be opened to analyze each action.

Benefits of Trace Viewer

  • Complete test execution replay
  • Faster debugging
  • Visual inspection of failures
  • Network request analysis
  • Console log monitoring
  • Reduced troubleshooting effort

Best Practices

  1. Use retain-on-failure in production test suites.
  2. Capture screenshots along with traces.
  3. Enable video recording for critical workflows.
  4. Review network activity during failures.
  5. Avoid storing traces for every successful test in large projects.
  6. Include trace artifacts in CI/CD pipelines.

Common Commands

Command Purpose
npx playwright test Run Playwright tests
npx playwright show-trace trace.zip Open Trace Viewer
trace: 'on' Always record traces
trace: 'retain-on-failure' Keep traces for failed tests only
trace: 'on-first-retry' Record traces on first retry

Conclusion

Trace Viewer is one of Playwright's most valuable debugging tools. It provides a complete replay of test execution, including screenshots, DOM snapshots, network activity, and console logs. By enabling tracing in your automation framework, you can significantly reduce debugging time and quickly identify the root cause of test failures.

```