Skip to main content

​
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

​
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:
  • 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:
  1. Open the Network tab
  2. See all requests with timing
  3. Check for failed requests (red)
  4. 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:
  1. Starts an HTTP server to serve trace files
  2. Validates trace paths - supports local files, directories, and URLs
  3. Synthesizes trace descriptors for directory-based traces
  4. Launches a browser (or uses an existing one) to display the UI
  5. Routes trace file requests through the server
  6. 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

OptionDescription
--browser, -bBrowser to use (chromium, firefox, webkit)
--host, -hHost to serve trace on (opens in browser tab)
--port, -pPort to serve trace on
--stdinAccept 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

​
Share Traces

# 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

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us