Tracing and Debugging with Playwright Inspector
When a test fails in CI, a stack trace and a single screenshot rarely explain why; you need to see the sequence of actions, the DOM at each step, and the network requests that were in flight. Playwright's tracing feature solves this by recording a self-contained trace.zip file per test that captures a full timeline: every action, DOM snapshots before and after each step, console logs, network activity, and (optionally) screenshots or video, which can then be replayed and inspected offline in the Trace Viewer.
Cricket analogy: It's like a stump-mic-and-multi-angle broadcast package handed to the third umpire instead of just the final scoreboard reading, letting them reconstruct exactly what happened ball by ball rather than guessing from the result.
Recording and Viewing Traces
Tracing is enabled per test run via context.tracing.start({ screenshots: true, snapshots: true, sources: true }) followed by context.tracing.stop({ path: 'trace.zip' }), though in practice most projects configure it declaratively in playwright.config.ts with the trace option set to 'on', 'off', 'retain-on-failure', or the more common 'on-first-retry'. Once a trace.zip exists, running npx playwright show-trace trace.zip opens a local web UI where you can scrub through a timeline of actions, click any step to see the exact DOM snapshot at that moment, inspect the Network tab for every request/response, and read console output — all without needing to re-run the test.
Cricket analogy: It's like scrubbing through a Hot Spot replay timeline ball by ball on the broadcast desk, clicking any delivery to see the exact bat-pad contact frame, instead of only watching the live feed once in real time.
Using the Playwright Inspector
While Trace Viewer is for post-mortem analysis after a run finishes, the Playwright Inspector is for live, interactive debugging: setting PWDEBUG=1 before running a test, or inserting an explicit await page.pause() call inside the test, opens a paused browser window alongside an Inspector panel with step-over controls, a locator picker that highlights matching elements when you hover generated selectors, and a live console for testing locator expressions against the actual page before committing them to code. This is the fastest way to figure out why a selector isn't matching or why a click isn't landing where you expect, since you can experiment directly against the real, running page state instead of guessing from a stack trace.
Cricket analogy: It's like a batting coach freezing a net session mid-delivery to physically walk out and adjust a batter's grip in real time, rather than only reviewing the footage afterward.
Debugging Failures in CI
Recording a full trace with screenshots and video for every single test run is expensive in both time and storage, so the recommended CI configuration is trace: 'on-first-retry' combined with screenshot: 'only-on-failure' and video: 'retain-on-failure' in playwright.config.ts — this way passing tests produce no artifacts at all, while a failing test that gets retried produces a complete trace.zip, a failure screenshot, and a video, uploaded as CI artifacts for later download. Downloading that trace.zip from a failed CI run and opening it locally with npx playwright show-trace almost always reveals the root cause immediately, since you can see the exact DOM state, network response, and console error at the moment the assertion failed, without needing to reproduce the flake on your own machine.
Cricket analogy: It's like a stadium only archiving full multi-angle broadcast footage for matches that go to a controversial finish, rather than storing every camera feed from every bilateral ODI ever played, to save storage while keeping what actually matters.
// playwright.config.ts
import { defineConfig } from '@playwright/test';
export default defineConfig({
use: {
trace: 'on-first-retry',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
retries: process.env.CI ? 2 : 0,
});
// checkout.spec.ts
import { test, expect } from '@playwright/test';
test('checkout applies discount code', async ({ page }) => {
await page.goto('/cart');
await page.pause(); // opens Playwright Inspector for live debugging
await page.getByPlaceholder('Promo code').fill('SAVE10');
await page.getByRole('button', { name: 'Apply' }).click();
await expect(page.getByText('10% discount applied')).toBeVisible();
});Run npx playwright show-trace trace.zip (or drag the .zip into trace.playwright.dev) to open the Trace Viewer's Actions, Network, Console, and Source tabs for a completed run — no browser or test re-execution required, since the trace is a fully self-contained artifact.
Setting trace: 'on' for every run in CI (rather than 'on-first-retry' or 'retain-on-failure') will substantially slow down your suite and bloat artifact storage — reserve full always-on tracing for local debugging sessions, not routine CI runs.
- Trace Viewer records a timeline of actions, DOM snapshots, network activity, and console logs into a self-contained trace.zip file.
- npx playwright show-trace opens a recorded trace for post-mortem, offline inspection without re-running the test.
- Playwright Inspector (PWDEBUG=1 or await page.pause()) enables live, interactive debugging against the actual running page.
- The Inspector's locator picker and live console let you validate selectors against real DOM state before writing them into code.
- trace: 'on-first-retry' in playwright.config.ts is the recommended CI setting, capturing a trace only when a test fails and retries.
- Pairing trace: 'on-first-retry' with screenshot: 'only-on-failure' and video: 'retain-on-failure' keeps passing runs artifact-free.
- Downloading a failed CI run's trace.zip usually pinpoints the root cause without needing to reproduce the flake locally.
Practice what you learned
1. What is the key difference between the Trace Viewer and the Playwright Inspector?
2. Which playwright.config.ts trace setting is recommended for CI to balance diagnostics with performance?
3. How do you open the Playwright Inspector for live debugging during a test run?
4. What information is NOT captured in a Playwright trace.zip by default when screenshots and snapshots are enabled?
5. Why is trace: 'on' for every test discouraged as a default CI setting?
Was this page helpful?
You May Also Like
Visual Comparisons and Screenshots
How Playwright captures, compares, and maintains screenshot baselines to catch visual regressions that functional assertions miss.
Fixtures and Test Hooks
How Playwright's fixture system and lifecycle hooks provide reusable, isolated setup and teardown for tests.
Cross-Browser and Device Emulation
How Playwright's project configuration runs the same suite across Chromium, Firefox, and WebKit, and emulates mobile devices, locales, and permissions.