Diagnose Playwright Test Failures with the Trace Viewer: A Step‑by‑Step Guide

What the Trace Viewer Solves

When a Playwright test stops unexpectedly, you often only see a stack trace and an error message. The Trace Viewer turns that opaque failure into a live replay of every action, network request, and DOM snapshot that happened during the test. By inspecting the trace you can pinpoint whether the problem was a flaky selector, a timing issue, a server error, or something else.

Desired Outcome

Enable automatic tracing for failing tests, generate a trace.zip artifact, and inspect it with Playwright’s built‑in viewer to identify the root cause of failures and performance regressions.

Prerequisites

• Node.js >= 18 (LTS recommended)
• Playwright Test @playwright/test v1.40+ (install with npm i -D @playwright/test)
• Project initialized with npm init playwright@latest (or equivalent)
• Writable test-results directory (default output folder)

Step 1 – Configure Tracing in playwright.config.ts

Add a trace option to the global config. Using on-first-retry keeps overhead low: tracing only starts if a test fails on its first run and is retried.

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 2, // enable retries so on-first-retry can trigger
  use: {
    trace: 'on-first-retry',
  },
});

Why on-first-retry?

Tracing captures screenshots, snapshots, and network payloads, which can add 50–200 ms per step and consume several megabytes. By limiting it to the first retry you get the diagnostic data you need only when a test actually fails.

Step 2 – Run Tests

Execute your suite as usual:

npx playwright test

If a test fails and a retry is attempted, Playwright will automatically generate trace.zip in the test-results folder.

Step 3 – Inspect the Trace

Open the trace viewer from the command line:

npx playwright show-trace test-results/trace.zip

This command starts a local web server and opens the viewer in your default browser. The UI shows a timeline, a list of actions, network calls, and console logs.

What to Look For

• Timeline – each step’s duration and order.
• Screenshots – visual context at each step.
• DOM snapshots – the page’s HTML structure.
• Network logs – request URLs, status codes, and payloads.
• Console output – errors, warnings, or debug logs.

Concrete Example

Suppose you have this test that intentionally fails due to a wrong selector:

// tests/fail.test.ts
import { test, expect } from '@playwright/test';

test('example.com headline', async ({ page }) => {
  await page.goto('https://example.com');
  // Wrong selector – will fail
  await expect(page.locator('h2')).toHaveText('Example Domain');
});

Run the test. After the retry, a trace.zip appears. Open it with the viewer and you’ll see:

• The page.goto action with a screenshot of the landing page.
• The failed assertion step, highlighted in red.
• A console error indicating ElementHandle is not attached to the DOM (if the selector never matched).

Step 4 – Verify the Trace Contents

To confirm the trace is complete, run the following checks:

1. Locate trace.zip in test-results.
2. Open the viewer and ensure the failing step is present and highlighted.
3. Verify that a screenshot exists for the step before the failure.
4. Check that network log entries match the expected requests (e.g., a GET to https://example.com/).

Recovery Options

• Trace missing – Make sure retries is set to at least 1 and trace: 'on-first-retry' is in the config. Also ensure the test-results directory is writable.
• Force tracing in a single run – Add --trace on to the test command: npx playwright test --trace on.
• Manual tracing in code – Use await context.tracing.start({screenshots:true, snapshots:true}); at the beginning of a test and await context.tracing.stop({path:'trace.zip'}); at the end. This guarantees a trace regardless of retries.

Cautions and Limits

• Tracing adds runtime overhead; avoid enabling it on all tests in CI unless necessary.
• Trace files capture full page content and network payloads, which may contain sensitive data. Sanitize or avoid tracing in production environments.
• Large traces (>50 MB) can slow the viewer. Disable snapshots for steps that generate huge DOM trees if you run into performance issues.

Practical Checklist

Check	How to Verify
Trace file created	File exists in test-results after run
Timeline shows all steps	Each action appears in order
Screenshot matches failure context	Visual comparison in viewer
Console logs present	Errors or warnings displayed
Network requests logged	Request URLs and status codes visible

Takeaway

Enabling trace: 'on-first-retry' turns a silent failure into a rich, replayable story. By inspecting the trace you can quickly see whether a selector was wrong, a page didn’t load, or a network call failed, and you can do so in a repeatable, low‑overhead way. Use the steps above to set up, run, verify, and recover from trace generation, and keep your test diagnostics fast and secure.