Trace Viewer - Playwright

Overview

The Trace Viewer is a post-mortem debugging tool that allows you to explore a recorded trace of your test execution. It captures everything: actions, screenshots, network requests, console logs, and more. Unlike the Inspector which debugs live execution, Trace Viewer analyzes what already happened.

Recording Traces

During Test Execution

Enable tracing in your Playwright config:

playwright.config.ts

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

export default defineConfig({
  use: {
    trace: 'on-first-retry',
  },
});

Trace Modes

trace

string

Show options

'on-first-retry' - Record trace only when retrying a test (default, recommended)
'on' - Record trace for every test (large files)
'retain-on-failure' - Record trace but delete if test passes
'on-all-retries' - Record trace for all retry attempts
'off' - Disable tracing

Via Command Line

Override config settings:

npx playwright test --trace on
npx playwright test --trace retain-on-failure

In Test Code

Programmatically control tracing:

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

test('custom trace', async ({ page, context }) => {
  // Start tracing
  await context.tracing.start({
    screenshots: true,
    snapshots: true,
    sources: true,
  });

  // Your test actions
  await page.goto('https://example.com');
  await page.click('button');

  // Stop and save trace
  await context.tracing.stop({
    path: 'trace.zip',
  });
});

Opening Traces

Show Trace Command

The primary way to view traces:

npx playwright show-trace

This opens the Trace Viewer UI where you can:

Drag and drop trace files
Paste trace URLs
Browse to trace files

With Trace File

npx playwright show-trace trace.zip

With Trace URL

npx playwright show-trace https://example.com/trace.zip

Serve Trace on Network

Open trace in a browser tab:

npx playwright show-trace --host=127.0.0.1 --port=9323
npx playwright show-trace trace.zip --host=0.0.0.0

This starts an HTTP server and opens the trace in your default browser.

Browser Selection

npx playwright show-trace --browser=firefox
npx playwright show-trace -b webkit trace.zip

Choose which browser to display the trace viewer in:

chromium (default)
firefox or ff
webkit or wk

Trace Viewer Interface

The Trace Viewer provides a comprehensive timeline view:

Action Timeline

Left sidebar showing all actions:

Navigation events
Clicks and inputs
Assertions
API calls
Waits and timeouts

Each action displays:

Duration
Success/failure status
Associated logs

Action Details

Click any action to see:

Action
Before/After
Console
Network
Source

Method called (e.g., page.click())
Selector used
Parameters passed
Stack trace
Source code location

Metadata Panel

Top section shows:

Test name and file
Browser and platform
Duration and status
Retry attempt number

Advanced Trace Features

Filtering Actions

Use the filter box to find specific actions:

click
goto
waitFor
expect

Snapshots and Screenshots

The Trace Viewer captures:

Before snapshot: DOM state before each action
After snapshot: DOM state after each action
Screenshots: Visual representation at each step

Snapshots are interactive - you can click elements to copy selectors and explore the DOM.

Network Tab Analysis

Investigate network issues:

test('analyze network', async ({ page, context }) => {
  await context.tracing.start({ snapshots: true });
  
  await page.goto('https://example.com');
  await page.click('button');
  
  await context.tracing.stop({ path: 'network-trace.zip' });
});

In the trace viewer:

Open the Network tab
See all requests with timing
Check for failed requests (red)
Inspect request/response data

Console Logs

All browser console output is captured:

test('with console', async ({ page, context }) => {
  await context.tracing.start();
  
  await page.goto('https://example.com');
  
  // This will appear in the trace
  await page.evaluate(() => {
    console.log('Custom log message');
    console.error('An error occurred');
  });
  
  await context.tracing.stop({ path: 'console-trace.zip' });
});

Trace Implementation Details

Based on /home/daytona/workspace/source/packages/playwright-core/src/server/trace/viewer/traceViewer.ts:154, the trace viewer:

Starts an HTTP server to serve trace files
Validates trace paths - supports local files, directories, and URLs
Synthesizes trace descriptors for directory-based traces
Launches a browser (or uses an existing one) to display the UI
Routes trace file requests through the server
Handles live trace updates when --stdin flag is used

Trace File Formats

Traces can be:

ZIP files (.zip) - Standard format containing all trace data
JSON files (.json) - Trace manifest/descriptor
Directories - Unzipped trace with multiple files

Using Traces in CI/CD

Playwright Cloud

# Automatically upload traces
npx playwright test --reporter=html

Storing Artifacts

playwright.config.ts

export default defineConfig({
  use: {
    trace: 'retain-on-failure',
  },
  
  reporter: [
    ['html', { open: 'never' }],
    ['json', { outputFile: 'test-results.json' }],
  ],
});

GitHub Actions Example

.github/workflows/tests.yml

- name: Run Playwright tests
  run: npx playwright test --trace on
  
- name: Upload traces
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: playwright-traces
    path: test-results/
    retention-days: 30

Download the artifacts and view locally:

npx playwright show-trace trace.zip

Performance Considerations

Tracing adds overhead to test execution:

Disk space: 1-10 MB per test (with screenshots)
Execution time: 10-20% slower
Use on-first-retry to minimize impact

Optimizing Trace Size

await context.tracing.start({
  screenshots: false,  // Disable screenshots
  snapshots: false,    // Disable DOM snapshots
  sources: true,       // Keep source code
});

Trace Viewer Options

Option	Description
`--browser, -b`	Browser to use (chromium, firefox, webkit)
`--host, -h`	Host to serve trace on (opens in browser tab)
`--port, -p`	Port to serve trace on
`--stdin`	Accept trace URLs over stdin to update viewer

Example Workflows

Debug Failed CI Test

# 1. Download trace from CI artifacts
gh run download 12345 -n playwright-traces

# 2. View the trace
npx playwright show-trace test-results/example-test/trace.zip

Compare Before/After

# Open multiple traces side-by-side
npx playwright show-trace baseline-trace.zip
npx playwright show-trace current-trace.zip

# Start a server to share traces
npx playwright show-trace --host=0.0.0.0 --port=9323 trace.zip

# Others can access at:
# http://your-ip:9323

Getting Started

Core Concepts

Test Runner

Guides

Tools

Advanced

Documentation Index

​Overview

​Recording Traces

​During Test Execution

​Trace Modes

​Via Command Line

​In Test Code

​Opening Traces

​Show Trace Command

​With Trace File

​With Trace URL

​Serve Trace on Network

​Browser Selection

​Trace Viewer Interface

​Action Timeline

​Action Details

​Metadata Panel

​Advanced Trace Features

​Filtering Actions

​Snapshots and Screenshots

​Network Tab Analysis

​Console Logs

​Trace Implementation Details

​Trace File Formats

​Using Traces in CI/CD

​Playwright Cloud

​Storing Artifacts

​GitHub Actions Example

​Performance Considerations

​Optimizing Trace Size

​Trace Viewer Options

​Example Workflows

​Debug Failed CI Test

​Compare Before/After

​Share Traces

​See Also

Build docs developers (and LLMs) love

Overview

Recording Traces

During Test Execution

Trace Modes

Via Command Line

In Test Code

Opening Traces

Show Trace Command

With Trace File

With Trace URL

Serve Trace on Network

Browser Selection

Trace Viewer Interface

Action Timeline

Action Details

Metadata Panel

Advanced Trace Features

Filtering Actions

Snapshots and Screenshots

Network Tab Analysis

Console Logs

Trace Implementation Details

Trace File Formats

Using Traces in CI/CD

Playwright Cloud

Storing Artifacts

GitHub Actions Example

Performance Considerations

Optimizing Trace Size

Trace Viewer Options

Example Workflows

Debug Failed CI Test

Compare Before/After

Share Traces

See Also