Eliminating CI Guesswork with Playwright Trace Viewer

The "Invisible Failure" Problem

Debugging a failing end-to-end test in a Continuous Integration (CI) pipeline is often a process of elimination. A standard failure report typically provides a stack trace and a final screenshot. However, these artifacts rarely explain why a failure occurred. Was a button obscured by a loading spinner? Did an API response return a 403 just before the crash? Recreating these transient states locally is often impossible because they depend on CI-specific latency or data states.

The Playwright Trace Viewer moves beyond static images by recording a full execution trace. It allows you to "time-travel" through a test, inspecting the page state, network traffic, and console logs for every single action performed.

DOM Snapshots vs. Video Recordings

A common misconception is that tracing is simply a video recording of the test. While Playwright can record video, the Trace Viewer uses DOM snapshots. A snapshot is a serialized version of the page's Document Object Model (DOM) at a specific point in time.

When you navigate the timeline in the Trace Viewer, you are interacting with a reconstructed version of the page. This means you can open the browser's developer tools inside the trace to inspect CSS styles, verify element visibility, or check if a selector was pointing to the wrong element—all after the test has already finished.

A complete trace captures four critical data streams:

• Action Timeline: A chronological sequence of every click, fill, and goto command.
• Network Waterfall: A detailed log of every HTTP request, including headers and response bodies.
• Console Logs: Browser-side console.log or error messages triggered during that step.
• Source Mapping: The exact line of test code associated with the current action.

Implementing Tracing in Your Workflow

While tracing can be started manually via the API, the most scalable approach is through the Playwright configuration file. This ensures consistent debugging data across your entire team without polluting test scripts with boilerplate code.

Configuration Example

In your playwright.config.ts (or .js), the trace option determines when a trace is recorded. For most projects, 'retain-on-failure' is the optimal setting; it discards traces for passing tests to save space but preserves them for failures.

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

export default defineConfig({
  use: {
    // Options: 'off', 'on', 'retain-on-failure', 'on-first-retry'
    trace: 'retain-on-failure',
    screenshot: 'only-on-failure',
  },
});

Generating and Inspecting Traces

To manually force a trace for a specific debugging session, run the tests from your terminal (requires Playwright v1.20+). Run this command in the project root with the necessary permissions to execute npx:

# Force tracing for all tests in the current run
npx playwright test --trace on

Upon completion, Playwright saves a trace.zip file within the test-results directory. To open this file in the visual viewer, use the following command:

# Replace 'path/to/trace.zip' with the actual path to your result file
npx playwright show-trace path/to/trace.zip

Trade-offs: Artifact Size and Performance

Tracing provides high fidelity, but it introduces overhead. Because it captures full DOM snapshots and network logs, trace.zip files can grow significantly. In a large suite with hundreds of tests, enabling trace: 'on' for every run can lead to gigabytes of CI artifacts, which may increase pipeline execution time or exceed storage limits of your CI provider.

Practical Verification: To verify your configuration, intentionally cause a test to fail (e.g., by asserting an incorrect page title). Run the test and check the test-results folder for a trace.zip. If the file is missing, ensure you are using Playwright v1.20 or later and that your configuration is correctly applied.

Actionable Summary

To reduce the time spent debugging "flaky" CI failures, transition from static screenshots to execution traces. Update your playwright.config.ts to use trace: 'retain-on-failure'. When a failure occurs in CI, download the resulting trace.zip and run npx playwright show-trace to pinpoint the exact network request or DOM state that caused the regression.