Debugging & Trace Viewer

Trace viewer, UI mode, --debug, codegen, videos and screenshots — find why a test failed in CI without rerunning it twenty times.

The debugging toolchain

Trace viewer — the CI failure microscope

A trace records everything: DOM snapshots before/after each action, network calls, console logs, and a timeline. It’s a time machine for the failed test.

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',   // record only when a test retries — near-zero cost
  },
  retries: process.env.CI ? 2 : 0,
});

# Open a trace downloaded from CI artifacts
npx playwright show-trace trace.zip

# Or view the whole run's report (traces embedded)
npx playwright show-report

Inside the viewer: click any action in the timeline → see the exact DOM state at that moment, the locator it resolved, network requests in flight, and console output. Most CI-only failures are diagnosed in minutes this way.

UI mode — interactive development

npx playwright test --ui

UI mode is a live test workbench: a watch-mode test list, time-travel timeline for every run, DOM snapshots, a locator picker, and instant re-run on save. Develop new tests here, not in a terminal loop.

Inspector — step through one test

npx playwright test login.spec.ts --debug

Opens a browser plus the Playwright Inspector: step through actions one at a time, see which locator each step resolves, and edit locators live in the console. Two targeted alternatives:

// Pause exactly where you need — runs headed, opens Inspector at this line
await page.pause();

# Verbose API logs without any UI
DEBUG=pw:api npx playwright test failing.spec.ts

Codegen — locator discovery

npx playwright codegen https://www.saucedemo.com

Click through the app; codegen writes locator-quality test code in real time. Treat the output as a draft — extract page objects and tighten assertions — but it’s the fastest way to discover what getByRole name an element has.

Videos and screenshots

export default defineConfig({
  use: {
    screenshot: 'only-on-failure',  // attach final screenshot to report
    video: 'retain-on-failure',     // keep video only when test fails
  },
});

// Manual screenshot anywhere
await page.screenshot({ path: 'evidence/checkout-bug.png', fullPage: true });

Failure screenshots land in the HTML report automatically — the first thing to check before opening a trace.

Reference

Interview questions