Playwright Trace Viewer Explained – Complete Beginner Guide with Debugging Examples & TypeScript (2026 Guide)

Leave a Comment / Uncategorized / By

Introduction: Why Debugging Is Important in Playwright

One of the biggest challenges in automation testing is understanding why a test failed.

Imagine your Playwright test fails in a CI/CD pipeline at 2:00 AM.

The error message says:

Timeout 30000ms exceeded.

But it doesn’t tell you:

  • What the page looked like
  • Which element was missing
  • What network requests failed
  • What happened before the failure
  • Whether the application loaded correctly

This is where Playwright Trace Viewer becomes extremely useful.

Instead of guessing why a test failed, Trace Viewer lets you replay the entire test execution step by step.

Whether you are:

  • A QA Automation Engineer
  • An SDET
  • A Selenium engineer transitioning to Playwright
  • A Software Testing Student
  • A Developer
  • Preparing for Playwright interviews

Learning Playwright Trace Viewer will help you debug automation failures much faster.

In this guide, you’ll learn:

  • What Playwright Trace Viewer is
  • Why Trace Viewer is useful
  • How tracing works
  • How to enable tracing
  • How to analyze traces
  • Real-world TypeScript examples
  • Debugging workflow
  • Best practices
  • Interview questions
  • FAQs

Let’s begin.

What Is Playwright Trace Viewer?

Playwright Trace Viewer is a built-in debugging tool that records everything that happens during test execution.

Instead of only showing an error message, it records:

  • Every user action
  • DOM snapshots
  • Screenshots
  • Network requests
  • Console logs
  • Source code
  • Action timeline

Simple Definition

Playwright Trace Viewer is a visual debugging tool that records and replays the complete execution of a Playwright test.

Think of it as a video player for your automation test—but with much more information.

Why Use Trace Viewer?

Traditional debugging usually relies on:

  • Console logs
  • Screenshots
  • Videos

These methods provide only part of the story.

Trace Viewer combines everything into one interactive report.

Benefits include:

  • Faster debugging
  • Step-by-step replay
  • DOM inspection
  • Network analysis
  • Better CI/CD troubleshooting
  • Easier root cause analysis

How Playwright Trace Viewer Works

The execution flow is simple.

Playwright Test

↓

Tracing Enabled

↓

Execute Test

↓

Record Every Action

↓

Generate Trace.zip

↓

Open Trace Viewer

↓

Analyze Failure

Playwright records events while the test runs and stores them in a trace file.

What Information Does Trace Viewer Capture?

Trace Viewer collects detailed information about every test run.

It records:

  • Screenshots
  • DOM snapshots
  • Network requests
  • Console logs
  • Source code
  • Action timeline
  • Assertions
  • Errors
  • Browser metadata

This makes it easier to understand what happened before a failure.

Enabling Tracing in Playwright

Tracing can be configured in playwright.config.ts.

Enable Tracing for Every Test

import { defineConfig } from ‘@playwright/test’;

export default defineConfig({

  use: {

    trace: ‘on’

  }

});

This records traces for every test execution.

Record Traces Only for Failed Tests

A common enterprise configuration is:

use: {

    trace: ‘retain-on-failure’

}

This saves storage because traces are preserved only for failed tests.

Record Trace on First Retry

use: {

    trace: ‘on-first-retry’

}

This option records traces only when a failed test is retried, balancing debugging detail with storage usage.

Trace Options Explained

Trace OptionDescriptionBest Use Case
onRecord every testLocal debugging
retain-on-failureKeep traces only for failed testsCI/CD pipelines
on-first-retryRecord when the first retry occursLarge regression suites

Opening and Analyzing a Trace

After running tests with tracing enabled, Playwright generates a trace file.

Open it using:

npx playwright show-trace trace.zip

The Trace Viewer interface lets you inspect:

  • Timeline of actions
  • Screenshots
  • DOM snapshots
  • Network requests
  • Console output
  • Source code location

You can move step by step through the test to see exactly where it failed.

Real-World Playwright Trace Viewer Example (TypeScript)

import { test, expect } from ‘@playwright/test’;

test(‘Login Test’, async ({ page }) => {

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

    await page.fill(‘#username’, ‘admin’);

    await page.fill(‘#password’, ‘admin123’);

    await page.click(‘button[type=submit]’);

    await expect(page).toHaveTitle(/Dashboard/);

});

With tracing enabled, every interaction in this test is recorded automatically.

Step-by-Step Explanation

Step 1 – Open Login Page

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

Trace Viewer records:

  • Navigation timing
  • Initial DOM snapshot
  • Network activity

Step 2 – Enter Username

await page.fill(‘#username’, ‘admin’);

The action appears in the timeline with the corresponding DOM state.

Step 3 – Enter Password

await page.fill(‘#password’, ‘admin123’);

You can inspect the page just before and after the action.

Step 4 – Click Login

await page.click(‘button[type=submit]’);

Trace Viewer captures:

  • Click event
  • Network requests triggered
  • Page transition
  • Updated screenshot

Step 5 – Verify Dashboard

await expect(page).toHaveTitle(/Dashboard/);

If this assertion fails, Trace Viewer helps identify whether the issue was caused by navigation, a missing element, or another problem.

Trace Viewer Workflow Diagram

Playwright Test Runner

        │

        ▼

Execute Test

        │

        ▼

Capture Actions

        │

        ├── Screenshots

        ├── DOM Snapshots

        ├── Network Requests

        ├── Console Logs

        ├── Assertions

        └── Source Code

        │

        ▼

Generate Trace.zip

        │

        ▼

Open Trace Viewer

        │

        ▼

Analyze Failure

This workflow provides a complete picture of what happened during test execution.

Trace Viewer vs Screenshots vs Videos

Many automation engineers use screenshots or videos to investigate failed tests. While these are helpful, Playwright Trace Viewer provides a much more complete debugging experience.

FeatureTrace ViewerScreenshotsVideos
Step-by-step timeline✅ Yes❌ No❌ No
DOM Snapshots✅ Yes❌ No❌ No
Network Requests✅ Yes❌ No❌ No
Console Logs✅ Yes❌ No❌ No
Source Code Navigation✅ Yes❌ No❌ No
Screenshots✅ Yes✅ Yes❌ No
Video PlaybackInteractive timelineSingle imageFull recording
Best ForRoot cause analysisQuick visual proofWatching UI execution

Which Should You Use?

  • Screenshots – Capture the UI at a specific moment.
  • Videos – Show the entire execution visually.
  • Trace Viewer – Provide the complete debugging story, including actions, DOM, network activity, logs, and source code.

For most Playwright projects, Trace Viewer is the preferred tool for investigating failed tests.

Common Debugging Scenarios

Scenario 1: Element Not Found

Error:

Timeout 30000ms exceeded.

Locator not found.

Use Trace Viewer to:

  • Check whether the page loaded.
  • Verify the element exists in the DOM snapshot.
  • Confirm the locator is correct.
  • Review the action timeline.

Scenario 2: Login Failed

Symptoms:

  • Redirect does not occur.
  • Dashboard is not displayed.

Trace Viewer helps verify:

  • Username entered correctly
  • Password entered correctly
  • Login button clicked
  • Network response status
  • Browser navigation after login

Scenario 3: Slow Application

Sometimes the application loads slowly only in CI/CD.

Trace Viewer allows you to inspect:

  • Page load timing
  • Network delays
  • Resource loading
  • Action timing

Scenario 4: Unexpected Popup

Suppose a cookie banner blocks the Login button.

Trace Viewer shows:

  • Screenshot before click
  • DOM snapshot
  • Failed click action
  • Console logs

The issue becomes immediately visible.

Scenario 5: API Failure

A page may fail because an API returns an error.

Trace Viewer records:

  • Request URL
  • Response status
  • Failed requests
  • Timing information

This helps distinguish frontend issues from backend failures.

Enterprise Debugging Workflow

Many enterprise teams follow a structured process for analyzing failed Playwright tests.

Developer Push

        │

        ▼

CI/CD Pipeline

        │

        ▼

Run Playwright Tests

        │

        ▼

Test Failure

        │

        ▼

Generate Trace

        │

        ▼

QA Engineer Opens Trace

        │

        ▼

Analyze Timeline

        │

        ▼

Identify Root Cause

        │

        ▼

Create Bug Report

This workflow reduces debugging time and improves collaboration between QA engineers and developers.

Best Practices for Using Playwright Trace Viewer

1. Use retain-on-failure in CI/CD

Instead of storing traces for every test, use:

use: {

    trace: ‘retain-on-failure’

}

This saves disk space while preserving traces for failed tests.

2. Use on-first-retry for Large Test Suites

For regression suites with thousands of tests:

use: {

    trace: ‘on-first-retry’

}

This records traces only when a retry is needed.

3. Combine Trace Viewer with HTML Reports

HTML reports summarize test results, while Trace Viewer provides detailed debugging information.

Using both gives the best visibility into test execution.

4. Review Network Requests

Many failures are caused by backend APIs rather than UI problems.

Always inspect the Network tab in Trace Viewer when debugging.

5. Keep Traces Organized

Store traces in a dedicated folder.

Example:

playwright-report/

traces/

screenshots/

videos/

reports/

A clear structure makes it easier to locate debugging artifacts.

6. Share Trace Files with Your Team

The generated trace.zip file can be shared with developers or other QA engineers.

Anyone with Playwright installed can open it using:

npx playwright show-trace trace.zip

This makes collaboration easier without reproducing the issue locally.

Common Mistakes to Avoid

Mistake 1: Enabling Traces for Every CI Run

Recording every trace increases storage usage. Prefer retain-on-failure or on-first-retry for most CI/CD pipelines.

Mistake 2: Ignoring the Timeline

The action timeline often reveals the exact step where a failure begins.

Mistake 3: Looking Only at Screenshots

Screenshots provide limited information. Use the timeline, DOM snapshots, network requests, and console logs together for a complete analysis.

Mistake 4: Not Reviewing Network Activity

If a page fails to load because an API returned an error, screenshots alone won’t explain the problem.

Mistake 5: Forgetting to Disable Unnecessary Tracing

Recording traces for every successful execution can consume significant disk space over time.

Playwright Trace Viewer Interview Questions

1. What is Playwright Trace Viewer?

Answer:
 It is a built-in debugging tool that records and replays the complete execution of a Playwright test.

2. What information does Trace Viewer capture?

Answer:

  • Screenshots
  • DOM snapshots
  • Network requests
  • Console logs
  • Source code
  • Action timeline
  • Assertions
  • Errors

3. How do you enable tracing?

Answer:

Configure it in playwright.config.ts.

Example:

use: {

    trace: ‘retain-on-failure’

}

4. How do you open a trace?

Answer:

npx playwright show-trace trace.zip

5. What is the difference between trace: ‘on’ and retain-on-failure?

Answer:

  • on records every test.
  • retain-on-failure keeps traces only for failed tests.

6. Why is Trace Viewer useful in CI/CD?

Answer:
 It allows engineers to investigate failures without rerunning tests locally.

7. Can Trace Viewer display network requests?

Answer:
 Yes. It records requests, responses, and timing information.

8. Can Trace Viewer replace screenshots?

Answer:
 Not entirely. Trace Viewer includes screenshots but also provides timelines, DOM snapshots, logs, and network information.

Frequently Asked Questions (FAQs)

What is Playwright Trace Viewer?

It is Playwright’s built-in debugging tool that records and replays test execution with detailed diagnostic information.

Does Trace Viewer record screenshots?

Yes. Screenshots are captured as part of the trace, along with additional debugging data.

Can I use Trace Viewer in CI/CD?

Yes. Many teams configure retain-on-failure so traces are available only when tests fail.

How do I open a Playwright trace?

Run:

npx playwright show-trace trace.zip

Does Trace Viewer capture console logs?

Yes. Console messages are included in the trace.

Is Trace Viewer better than videos?

For debugging, Trace Viewer is often more useful because it combines screenshots, timelines, DOM snapshots, logs, and network requests in one interface.

Should I enable tracing for every test?

Not necessarily. For large projects, retain-on-failure or on-first-retry is usually a better balance between debugging capability and storage usage.

Leave a Comment

Your email address will not be published. Required fields are marked *