Q15 of 42 · Playwright

What is the trace viewer and how do you use it to debug a failing test?

PlaywrightMidplaywrighttrace-viewerdebuggingmid

Short answer

Short answer: The trace viewer is a post-run debugger that replays the test with DOM snapshots, network log, console, source code, and timeline. Enable with `trace: 'on-first-retry'` or generate manually with `page.context().tracing`. Open with `npx playwright show-trace trace.zip`.

Detail

The trace viewer is Playwright's killer debugging feature. Each trace captures:

  • Action timeline — every Locator interaction with timestamps and durations.
  • DOM snapshots at each action — hover the timeline, see the DOM state at that moment.
  • Screenshots before, during, after each action.
  • Network log — all requests with headers, body, timing.
  • Console output — console.log, errors, warnings.
  • Source code — the test code with the current step highlighted.

Enable in config:

use: {
  trace: 'on-first-retry',  // 'off' | 'on' | 'on-first-retry' | 'retain-on-failure'
}

on-first-retry is the sweet spot: no overhead on the first attempt, full trace on the retry that ran because the first failed.

Open a trace:

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

The browser-based UI lets you scrub through the timeline, inspect the DOM at any step, and replay actions.

The CI workflow: store traces as build artefacts. When a test fails, download the trace zip from CI, open with show-trace, debug locally without re-running anything.

Manual tracing for finer control:

test('with manual trace', async ({ context, page }) => {
  await context.tracing.start({ screenshots: true, snapshots: true });
  await page.goto('/dashboard');
  // ...
  await context.tracing.stop({ path: 'trace.zip' });
});

Why it changes debugging: with Cypress's time-travel debugger you have to re-run the test to see what happened. With Playwright's trace, you replay a past run — making CI failures debuggable from your laptop without reproduction.

// EXAMPLE

.github/workflows/playwright.yml

- run: npx playwright test
- name: Upload trace on failure
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: playwright-traces
    path: test-results/
    retention-days: 14

# Then locally:
#   npx playwright show-trace path/to/downloaded/trace.zip

// WHAT INTERVIEWERS LOOK FOR

Naming what the trace captures (timeline, DOM, network, screenshots, source), the `on-first-retry` config, and the CI artefact workflow.

// COMMON PITFALL

Setting `trace: 'on'` and slowing every CI run for tests that pass first time — `on-first-retry` is the right default.

// Related questions

How do you take a screenshot on test failure?

Selenium

Walk through how you'd debug a Playwright test that flakes only in CI.

Playwright

How does Playwright's tracing change your approach to debugging vs Cypress's time-travel debugger?

Playwright