Playwright Debugging & Trace Viewer

Writing automated tests is only half the job. When tests fail, you need effective tools to identify the root cause quickly.

One of Playwright’s biggest advantages over traditional automation frameworks is its powerful built-in debugging ecosystem. Instead of relying on third-party plugins or manually adding log statements, Playwright provides features like Debug Mode, Playwright Inspector, Trace Viewer, Screenshots, Videos, and Execution Logs. In this guide, you’ll learn how to debug Playwright tests efficiently and use the Trace Viewer to analyze test failures step by step.

Why Debugging Matters

Test failures can occur for many reasons:

• Application bugs
• Incorrect locators
• Timing issues
• Network delays
• Environment problems
• Test data issues

Without proper debugging tools, identifying the cause can be time-consuming.

Playwright simplifies this process with built-in diagnostics.

Debugging Tools in Playwright

Playwright provides several debugging features:

• Debug Mode
• Playwright Inspector
• Trace Viewer
• Screenshots
• Video Recording
• Console Logs
• Network Logs
• HTML Reports

Together, these tools provide complete visibility into test execution.

Debug Mode

Debug Mode pauses test execution and opens the Playwright Inspector.

Run a test in debug mode:

npx playwright test --debug

Features include:

• Step-by-step execution
• Pause and resume
• Inspect page elements
• View locator information
• Live browser interaction

Debug Mode is ideal for investigating a failing test during development.

Playwright Inspector

The Playwright Inspector is an interactive debugging tool that launches alongside your browser.

It allows you to:

• Pause execution
• Inspect locators
• Highlight elements
• Execute actions manually
• Step through each test command

This provides a much more visual debugging experience than simply reading logs.

Using page.pause()

You can intentionally pause a running test by inserting:

await page.pause();

When execution reaches this line:

• The browser pauses.
• Inspector opens.
• You can inspect the page.
• Execution resumes when you’re ready.

This is especially useful while developing new tests.

Trace Viewer

The Trace Viewer is one of Playwright’s most powerful features.

It records everything that happens during test execution, allowing you to replay the test after it finishes.

The Trace Viewer captures:

• Every action
• Every locator
• Screenshots
• Network requests
• Console messages
• Timing information
• DOM snapshots

Think of it as a “flight recorder” for your automated tests.

Enabling Trace Recording

Configure tracing in playwright.config.ts:

import { defineConfig } from '@playwright/test';
export default defineConfig({
    use: {
        trace: 'on-first-retry'
    }
});

Available options:

• off
• on
• retain-on-failure
• on-first-retry

For most projects, on-first-retry provides a good balance between debugging information and storage usage.

Viewing a Trace

After a test run, open the trace:

npx playwright show-trace trace.zip

Or, if HTML reporting is enabled, open the report:

npx playwright show-report

Select the failed test and launch the Trace Viewer directly from the report.

What You Can See in the Trace Viewer

The Trace Viewer provides a timeline of the entire test.

Action Timeline

See every Playwright action in sequence:

Navigate
↓
Fill Username
↓
Fill Password
↓
Click Login
↓
Verify Dashboard

Click any action to inspect its details.

DOM Snapshot

View the exact state of the page at any point in the test.

This helps identify:

• Missing elements
• Incorrect UI states
• Timing issues

Screenshots

Playwright captures screenshots during trace recording.

You can visually inspect what the application looked like when each action occurred.

Network Requests

The Trace Viewer records HTTP requests and responses.

You can verify:

• API endpoints
• Response status codes
• Failed requests
• Slow network calls

This is especially helpful for debugging API-dependent UI tests.

Console Messages

Any browser console logs are available in the trace.

This makes it easier to identify JavaScript errors that may affect the UI.

Screenshots on Failure

Automatically capture screenshots when a test fails.

Configuration:

use: {
    screenshot: 'only-on-failure'
}

Benefits:

• Visual evidence of failures
• Faster root cause analysis
• Easier reporting

Video Recording

Record browser sessions automatically.

Configuration:

use: {
    video: 'retain-on-failure'
}

Videos are particularly useful for intermittent failures that are difficult to reproduce.

Capturing Browser Console Logs

You can listen for console events:

page.on('console', message => {
    console.log(message.text());
});

This helps identify client-side JavaScript issues.

Logging Network Requests

Monitor API calls during execution:

page.on('request', request => {
    console.log(request.method(), request.url());
});

This is useful when validating network activity or debugging failed API calls.

HTML Reports

Generate the built-in HTML report:

npx playwright show-report

The report includes:

• Passed tests
• Failed tests
• Execution time
• Retries
• Screenshots
• Videos
• Trace links

This makes it easy to review test results after local or CI/CD execution.

Common Debugging Workflow

A typical debugging process might look like this:

Test Fails
↓
Open HTML Report
↓
Launch Trace Viewer
↓
Review Timeline
↓
Inspect Screenshots
↓
Check Console Logs
↓
Analyze Network Requests
↓
Fix Test or Application

Following a consistent workflow speeds up troubleshooting.

Best Practices

• Enable traces for failed tests.
• Capture screenshots on failure.
• Record videos only when necessary to save storage.
• Use page.pause() while developing new scripts.
• Review browser console logs during failures.
• Keep HTML reports as part of your CI/CD artifacts.

Common Mistakes

Relying Only on console.log()

Playwright’s built-in tools provide far more context than log statements alone.

Recording Traces for Every Test

Continuous trace recording can increase execution time and consume significant disk space.

Use on-first-retry or retain-on-failure for most projects.

Ignoring Browser Console Errors

JavaScript errors often explain unexpected UI behavior.

Always review console messages when investigating failures.

Playwright vs Selenium Debugging

Playwright provides a richer debugging experience without additional setup.

Frequently Asked Questions

What is the Playwright Trace Viewer?

The Trace Viewer is a built-in tool that records and replays test execution, showing actions, screenshots, DOM snapshots, network activity, and console logs.

How do I debug a Playwright test?

Run:

npx playwright test --debug

This launches the Playwright Inspector for interactive debugging.

When should I enable tracing?

A common practice is to enable tracing only on failed tests or the first retry to balance storage usage and debugging capability.

Can Playwright record videos?

Yes. Configure the video option in playwright.config.ts to record browser sessions.

Does Playwright generate HTML reports?

Yes. The built-in HTML report includes execution summaries, screenshots, videos, and links to traces.

Conclusion

Playwright’s debugging ecosystem is one of its greatest strengths. With tools like Debug Mode, Playwright Inspector, Trace Viewer, screenshots, videos, and HTML reports, you can diagnose failures much faster than with many traditional automation frameworks.

By incorporating these tools into your daily workflow and CI/CD pipelines, you’ll reduce troubleshooting time, improve test reliability, and build more maintainable automation suites.

Related Articles

✓ Playwright Page Object Model (POM)

✓ Playwright Test Runner Explained

✓ Playwright UI Elements Interactions

✓ What is Playwright?

✓ Playwright Architecture Explained

✓ Playwright Setup with TypeScript

✓ Playwright Setup with Java

✓ Playwright Locator Strategies

✓ Playwright Auto-Waiting Mechanism

✓ Complete Playwright Tutorial