Playwright Trace Viewer: Debug Tests with Screenshots & Videos
Playwright Trace Viewer shows exactly why your tests fail with full execution visibility. Debug CI failures in minutes, not hours.
Your Playwright test passes locally but fails in CI with a cryptic error message. No context. No screenshots. No network logs. You're debugging blind, adding console.log statements and increasing timeouts, hoping to catch the failure locally.
Playwright Trace Viewer eliminates this guesswork. It records every action, screenshot, network call, and DOM mutation during test execution, creating a complete forensic record you can replay step-by-step. This transforms debugging from hours of trial and error into minutes of targeted analysis.
This guide covers Playwright Trace Viewer setup, CI/CD configuration, debugging with screenshots and videos, and how TestDino streamlines trace-based workflows for faster failure resolution.
Why Playwright trace viewer essential for debugging tests
Test failures without context waste valuable development time. When your Playwright test breaks in CI, you get a generic "element not found" error with zero visibility into what actually happened. The application state is gone. Network requests are invisible. DOM snapshots have vanished.
Playwright Trace Viewer captures five critical data layers:
Action Timeline - Every Playwright action with duration, status, and locator details. Identifies slow operations, unexpected retries, and the exact step that triggered failures.
DOM Snapshots - Complete page state before and after each action. Inspect elements, verify selectors, and debug DOM structure changes that break your tests.
Network Activity - All HTTP requests with headers, payloads, status codes, and timing. Failed API calls that prevent buttons from loading become immediately visible.
Console Messages - Browser console output plus Playwright's internal logs. JavaScript errors and auto-wait explanations help determine if failures stem from application bugs or test logic.
Screenshots & Videos - Visual confirmation of page state at each step. Spot overlapping UI elements, rendering delays, and layout shifts invisible in text logs.
This visibility eliminates the "works on my machine" problem by showing exact browser state during CI execution. You see timing issues like elements appearing then disappearing before interaction. Backend errors that cause UI elements to never load become traceable.
Without Trace Viewer, debugging flaky Playwright tests means recreating failures locally and guessing at root causes. With Trace Viewer, you open the trace file, navigate to the failed action, and see the exact browser state that caused the problem.
How to use Playwright trace viewer to analyze screenshots and videos
Playwright trace files are .zip archives containing screenshots, network logs, DOM snapshots, and action metadata. You can open traces locally via Playwright CLI or in a browser using trace.playwright.dev.
Opening Traces with Playwright CLI
The fastest way to analyze Playwright traces on your machine.
This launches a local server and opens the Playwright Trace Viewer in your browser. The interface loads client-side, so trace data never leaves your machine, which is critical when traces contain authentication tokens or sensitive user data.
Browser-Based Trace Viewer
For quick analysis without installing Playwright, use trace.playwright.dev. Drag and drop your trace file or use the file selector. The viewer processes everything in-browser without transmitting data externally.
Open remote Playwright traces directly by URL:
This eliminates downloading trace files from CI artifacts. Tools like TestDino provide one-click Playwright Trace Viewer access directly from dashboards, removing manual download steps entirely.
Navigating the Playwright Trace Viewer Interface
The Actions tab shows a chronological timeline of every Playwright step. Click any action to see before/after states, execution time, and artifacts.
The Screenshots filmstrip displays a visual timeline. Hover for magnified views of each screenshot to spot visual changes or layout shifts. Double-click actions to zoom the timeline.
Before and After tabs show DOM snapshots captured around each action. Click elements to inspect properties, verify CSS classes, and confirm selector matches. This interactive inspection beats static screenshots because you can explore the full DOM tree and test different Playwright locators.
Analyzing Network Activity in Trace Viewer
The Network tab lists all HTTP requests chronologically with method, URL, status code, response time, and payload size. Click requests for full headers, request bodies, and response data.
Failed requests appear highlighted, making it easy to spot backend errors preventing UI elements from loading. Slow API responses show via timing bars, indicating when requests started and their duration. This identifies performance bottlenecks causing timeouts or flaky test behavior in Playwright.
Using Console Logs for Debugging
The Console tab displays browser console output and Playwright's internal logs. JavaScript errors and application logging appear alongside Playwright's auto-wait explanations.
Filter console messages by type, source, or search term. Double-clicking an action filters the console to show only messages logged during that action's execution. This correlation reveals why Playwright waited, retried, or failed at specific steps.
Debugging with DOM Snapshots
DOM snapshots preserve the complete page structure at each action. Unlike screenshots showing only visual state, snapshots let you inspect element attributes, CSS properties, and DOM hierarchy essential when debugging Playwright selector issues.
If your test fails with "element not found," the snapshot shows exactly what elements existed. Test different locators directly in the snapshot using the picker tool, verify target elements were present but hidden, or discover elements had different data attributes than expected.
Setting Up Playwright Trace Viewer in Your Tests
Configure Playwright tracing in your test setup file to automatically capture traces based on test outcomes.
Basic Playwright Trace Configuration
Add trace configuration to playwright.config.ts:
import {defineConfig} from '@playwright/test';
export default defineConfig({
use: {
trace: 'on-first-retry',
},
});
This records Playwright traces only when tests fail and retry, balancing diagnostic value with storage efficiency. The trace captures everything needed to debug failures without generating unnecessary data.
Playwright Trace Mode
trace: 'on' - Records traces for every test. Use during active development when you need complete visibility. Generates large amounts of trace data and slows test execution.
trace: 'off' - Disables tracing entirely. Use for fast feedback loops when you don't need debugging artifacts.
trace: 'on-first-retry' - Captures traces only when tests fail, and Playwright retries them. Recommended for CI pipelines provides debugging artifacts for failures without wasting storage on passing tests.
trace: 'retain-on-failure' - Records traces for all tests but only saves them when tests fail. Works well without configured retries.
Programmatic Trace Control
For explicit control over when Playwright traces start and stop:
const browser = await chromium.launch();
const context = await browser.newContext();
await context.tracing.start({
screenshots: true,
snapshots: true,
sources: true
});
const page = await context.newPage();
await page.goto('https://storedemo.testdino.com/');
await context.tracing.stop({ path: 'trace.zip' });
Capture traces for specific workflows, record only authentication flow, or focus on particular user journeys. Screenshots provide visual verification, snapshots enable DOM inspection, and sources help correlate trace actions with test code.
Integrating Playwright Trace Viewer with CI/CD Pipelines
CI environments create unique trace debugging challenges. Tests run headless on remote machines with different resources than development environments. Trace files are stored as build artifacts requiring manual download.
Configuring Traces for CI
Set up CI to capture Playwright traces on failure and store them as artifacts. In GitHub Actions:
- name: Run Playwright tests
run: |
npx playwright test
env:
CI: true
- name: Upload results to TestDino
if: always() # Upload both passing and failing runs
run: npx tdpw upload ./playwright-report --token="${{ secrets.TESTDINO_TOKEN }}"
- name: Upload trace artifacts
if: failure() # Only upload traces on failure to save storage
uses: actions/upload-artifact@v3
with:
name: playwright-traces
path: test-results/**/trace.zip
The if: failure() condition ensures artifacts upload only when tests fail, saving storage and upload time for successful runs.
Accessing Playwright Traces from CI
After failed CI runs, navigate to workflow artifacts and download the trace archive. Extract the zip and open using Playwright CLI or trace.playwright.dev. This manual process creates friction between failure detection and root cause analysis.
Modern CI debugging workflows integrate trace viewing directly into test reporting platforms. TestDino automatically processes Playwright trace files and provides one-click access to the trace viewer from test results dashboards. Click a failed test and immediately see its trace, screenshots, and error details in one interface.
Optimizing Trace Storage
Playwright trace files consume significant storage. A single trace for complex tests can be 10-50MB. Suites with hundreds of tests generate gigabytes of trace data per run.
Manage storage costs by configuring retention policies that automatically delete old trace artifacts after 30-90 days. Most CI systems support artifact expiration settings.
For large test suites, use trace: 'on-first-retry' instead of trace: 'retain-on-failure'. This reduces trace volume by only capturing diagnostics when failures warrant investigation.
Analyzing Playwright Traces at Scale
When multiple tests fail in CI, opening each Playwright trace file individually becomes impractical. Centralized reporting platforms aggregate traces across all failed tests with filtering, search, and grouping capabilities.
TestDino's AI-powered failure classification automatically groups similar failures and identifies patterns across Playwright traces. Instead of analyzing 20 individual trace files for selector errors, you see a single failure group with representative traces and suggested fixes.
The platform tracks flaky tests over time, correlating retry patterns with specific traces. Historical trace data reveals whether flakiness stems from timing issues, network variability, or environmental differences.
How TestDino Enhances Playwright Trace Viewer Workflows
Standard Playwright trace workflows require manually downloading trace files from CI artifacts, running CLI commands, and switching between tools. TestDino streamlines this by centralizing all test artifacts with one-click trace access.
Centralized Trace Access
When tests fail in CI, TestDino automatically uploads and indexes the Playwright trace file with screenshots, videos, and error details. Test results pages display all evidence in organized panels, with traces accessible via a single click. No downloading, no CLI commands, no context switching.
The trace opens in the native Playwright Trace Viewer running in your browser with full functionality. Same experience as opening traces locally, but without manual artifact management.
AI-Powered Failure Analysis
TestDino's AI analyzes Playwright trace data to classify failures by root cause. It examines error messages, stack traces, and trace patterns to determine whether failures represent actual bugs, UI changes breaking selectors, or flaky tests from timing issues.
Classification appears immediately when viewing test results before opening the trace. Instead of determining failure type, you start with that context and focus on solving the specific problem. AI provides confidence scores and suggested next steps based on failure type.
Historical Trace Analysis
Beyond individual trace inspection, TestDino tracks patterns across test runs over time. When tests become flaky, the platform correlates Playwright traces from passing and failing runs to identify environmental differences, timing sensitivities, or resource constraints triggering intermittent failures.
The analytics dashboard shows trends like increasing failure rates, new failure patterns after code changes, and tests failing only in specific CI environments. This historical context transforms reactive debugging into proactive stability improvement.
Integrated Evidence Panels
The test case view organizes all debugging artifacts in dedicated panels. Error details show exact error messages and stack traces. Test steps list each Playwright action with timing information. Screenshots display the page state at failure. The trace provides an interactive investigation of complete execution.
This eliminates gathering evidence from multiple sources. Everything required to debug the failure lives in one place, accessible from a single shareable URL.
Best Practices for Using Playwright Trace Viewer
Effective trace usage requires strategic configuration and analysis patterns.
Use Conditional Tracing in CI
Always use trace: 'on-first-retry' or trace: 'retain-on-failure' in CI environments. Never enable trace: 'on' for all tests in CI. Recording traces for passing tests wastes storage without providing value.
The exception: when actively debugging specific intermittent failures, temporarily enable tracing for problematic test files to capture traces from both passing and failing runs.
Start with Screenshots
When opening Playwright traces, start with the visual timeline. Skim screenshots to quickly identify where application state diverged from expectations. Visual inspection often reveals problems faster than reading action logs.
If the failure is visual (wrong layout, missing elements), screenshots immediately show the issue. If functional (wrong data, failed navigation, timeout), screenshots show context narrowing investigation focus.
Check Network Logs for Backend Issues
Many test failures stem from backend problems manifesting as frontend issues. A missing button might be a failed API call preventing button rendering. A timeout waiting for elements might be slow API responses delaying page updates.
Always check the Network tab in Playwright Trace Viewer when investigating element visibility issues, timeouts, or data validation failures. Look for failed requests, slow responses, and unexpected error codes.
Compare Passing and Failing Traces
When debugging flaky tests, capture Playwright traces from both passing and failing runs. Load them in separate browser tabs and navigate to the same action. Compare screenshots, network timing, console logs, and DOM states.
Small timing differences, variable network latency, or race conditions become visible. A flaky test might pass when APIs respond in 200ms but fail at 400ms. The trace comparison shows this timing difference helping you fix root causes instead of just increasing timeouts.
TestDino automates this comparison for flaky tests by grouping multiple runs of the same test and highlighting differences between passing and failing attempts.
Conclusion
Playwright Trace Viewer transforms test debugging from guesswork into systematic analysis. Instead of adding console logs and hoping to catch failures locally, you get complete forensic records of test execution with screenshots, network logs, and DOM snapshots.
Configure tracing once in your Playwright config, and it automatically captures diagnostic data when tests fail. Open traces using CLI or browser-based viewer to investigate failures with interactive timeline navigation, DOM inspection, and network analysis.
For teams running extensive Playwright test suites in CI, trace management becomes a workflow challenge. TestDino centralizes traces, provides one-click access from test results, and uses AI to classify failures by root cause. The platform tracks flaky tests over time, correlates traces across multiple runs, and provides evidence-rich reporting that accelerates debugging for entire teams.
Start using Playwright Trace Viewer today by adding trace: 'on-first-retry' to your Playwright configuration. The next time a test fails in CI, you'll have everything needed to understand and fix the failure in minutes instead of hours.
FAQs
Table of content
Flaky tests killing your velocity?
TestDino auto-detects flakiness, categorizes root causes, tracks patterns over time.
Follow Us
