DEV Community: Vanessa Sastre

Playwright Trace Viewer: Debug Failed Tests Without Reproducing Them

Vanessa Sastre — Thu, 06 Aug 2026 21:57:33 +0000

Playwright Trace Viewer is a built-in GUI that records a full, replayable snapshot of a test run — every action, DOM state, network call, and console log — so you can debug a CI failure by opening a file, not by reproducing it.

In practice, that makes a UI test into more than a UI recording. Every browser interaction is synchronized with the underlying API traffic, console output, and page state at the moment it happened — which gives you an API debugging layer for free, without writing a single API test.

That one difference changes the economics of test debugging. This post covers what changes in your day-to-day workflow, how to turn it on, and how to justify it to the people who care about engineering time and CI spend rather than DOM snapshots.

The Problem: Debugging Requires Reproducing

CI fails → Try locally → Can't reproduce → Add debugging → Implement a fix → Push → Wait for CI → Repeat

A test fails on CI. Here's what that traditionally costs you:

Read the error message and stack trace, which often aren't clear enough on their own.
Pull the branch and try to reproduce the failure locally.
It passes locally. CI-only failures are common — different browser, viewport, timing, environment, or data state.
Add console.log, screenshots, tracing, or page.pause() calls and run the test again.
It still doesn't reproduce. Try running headed, slow down actions, add waits, or tweak the environment until it finally fails.
Eventually reproduce the issue, identify the root cause, remove the debugging code, and implement a fix.
Push the fix and wait for CI to run again. If the failure persists, repeat the process.

Depending on the bug, that loop can take anywhere from a few minutes to most of an afternoon — and it scales linearly with how flaky or environment-dependent the failure is. Every step exists because you're missing information that already existed at the moment the test ran, and is now gone.

Trace Viewer's premise: stop throwing that information away.

The Fix: Open the Trace Instead of Re-Running the Test

With tracing enabled, every action, DOM snapshot, request, and log from the run is captured into a single trace.zip. When a test fails, you open that file — locally, from CI, or in the browser — and the run replays exactly as it happened.

Here's the same debugging tasks, before and after:

Task	Without Trace Viewer	With Trace Viewer
Find why a click hit the wrong element	Re-run headed, add logs, hope it reproduces	Click the action, see the before/after DOM and the exact click coordinates
Grab a locator for a new assertion	Re-run in debug mode, use the inspector live	Open the Locator tab on the already-captured screen and pick it — no re-run
Diagnose a failed network call	Add request logging, re-run, inspect devtools	Open Network, already filtered to that action
Find the exact line of code behind a step	Search the file, count steps manually	Click the action, Source jumps to that line
Investigate a CI-only flake	SSH into CI, add debug output, wait for the next occurrence	Download the trace CI already attached, open it locally

The pattern across every row: instead of recreating the conditions of the failure, you're looking at a recording of it.

Setup: Two Lines of Config

Locally, trace everything while you're developing:

npx playwright test --trace on

Or use UI Mode, which traces every test automatically without the flag.

On CI, tracing every run is wasteful — trace only what fails, on retry:

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

export default defineConfig({
  retries: 1,
  use: {
    trace: 'on-first-retry',
  },
});

Other values: on-all-retries, retain-on-failure (if you don't use retries), on (every run — expensive), off.

Opening a trace:

From the HTML report: click View trace on any test — it opens a local instance of Trace Viewer directly, no file hunting.

  npx playwright show-report

From the CLI, pointing at a file or a URL:

  npx playwright show-trace path/to/trace.zip
  npx playwright show-trace https://example.com/trace.zip

In the browser, no install required: trace.playwright.dev. Drag in a file, or pass one as a URL query parameter — handy for linking straight from a CI artifact. Everything renders locally in your browser; nothing is uploaded.

What's Inside a Trace

A timeline runs across the top of the viewer — click or drag anywhere on it, and every panel below updates to that moment. You never have to click through actions one by one to find the point you care about.

Tab	What you get
Actions	Every action, its locator, and its duration, with before/after DOM snapshots
Locator	The exact screen, fully replicated, with Pick Locator available on it — build a new locator without executing anything
Source	The exact line of test code behind the action you're viewing
Call	Timing, resolved locator, and mode (e.g. strict) for the selected action
Log	Playwright's internal narration — waiting for visible/enabled/stable, then acting
Errors	The failure message, with a red marker on the timeline showing exactly when it happened
Console	Browser and test console logs, filterable to a single action
Network	Every request with headers/bodies, filterable to a single action
Metadata	Browser, viewport, duration, and run context in one place
Attachments	Expected vs. actual image diffs with a slider, for visual regression tests

The Network tab is easy to underestimate. This is the API debugging layer mentioned at the top of this post: even if your suite only exercises the UI, every backend call made during the test is captured and synchronized with the user's actions. Instead of opening DevTools and trying to reproduce the issue, you already have a complete timeline of both the frontend behavior and the API interactions that produced it.

Traces as Context for AI Agents

Everything a trace captures — actions, locators, DOM snapshots, network calls, console output — is structured data sitting in a zip file, not just a GUI to click through manually. That makes it a good fit for AI coding agents and testing skills that need to diagnose a failure without a human first reproducing it.

A few ways this shows up in practice:

Autonomous failure triage. An agent can be handed a trace.zip from a CI run and asked to identify the failing action, the locator involved, and the DOM state around it, then propose a fix — without ever spinning up a browser or re-running the suite itself.
Root-cause summaries instead of raw logs. Rather than pasting a stack trace into a chat, an agent (or a skill built around one) can walk the Actions, Network, and Console data from a trace and produce a plain-language explanation of what broke and where, which is a much shorter path to a fix than reading raw output.
Locator generation without execution. Because the Locator tab replicates the exact screen at a given moment, an agent can use that captured state to derive or validate a selector for a new assertion, the same way a human uses Pick Locator — without needing a live browser session.
Feeding "video receipts" back in. If you're also recording screencasts (Playwright's page.screencast API) alongside traces, an agent's own verification steps can be captured the same way — giving you a reviewable artifact of what an agent did, not just a claim that it passed.
CI feedback loops. Since traces are already CI artifacts with stable URLs, an agent watching a pipeline can fetch a failing test's trace automatically as soon as it's produced, rather than waiting on a person to attach logs or describe the failure.

The underlying shift is the same one this post keeps coming back to: a trace turns "the test failed" into a self-contained record that doesn't require a human — or an agent — to reproduce the failure to understand it.

The Efficiency Case

Trace Viewer isn't just a developer-experience nicety — it changes measurable costs. If you need to justify adopting it (or prioritizing better trace coverage in CI), these are the levers to point at:

Mean time to resolution (MTTR) on test failures. The reproduction loop above is where most debugging time goes. Removing the "make it fail again" step is the single biggest lever on how long a failure sits open.
Engineer context-switching cost. A flaky CI failure that can be diagnosed by opening a file, versus one that requires blocking time to reproduce locally, has a very different interruption cost — especially for failures that surface hours after the engineer has moved to other work.
CI compute spend. trace: 'on-first-retry' only records what actually fails, so you get debugging data without paying to trace every green run. Compare that to teams that resort to re-running whole suites repeatedly to catch a flake in the act.
Flaky test triage throughput. Because traces are attachable CI artifacts, failures can be triaged asynchronously by whoever has time, not only by whoever can reproduce the environment.

If you want to track the impact concretely, two numbers are enough to start: time from failure to root cause identified, and number of "couldn't reproduce, closed as flaky" tickets. Both should move once trace review replaces manual reproduction as the default first step.

CI/CD Recommendations

Trace on retry, not on every run. on-first-retry (or retain-on-failure without retries) gives full debugging data for failures at a fraction of the storage and runtime cost of on.
Link traces directly from CI output. Since show-trace and trace.playwright.dev both accept URLs, wire your CI's artifact link straight into a one-click trace view instead of a manual download-and-unzip step.
Treat "couldn't reproduce" as a process gap, not bad luck. If a failure recurs without a trace attached, that's a signal to widen trace coverage, not just re-run the suite again.

Official Resources

Trace viewer documentation — full walkthrough of every tab and feature
testOptions.trace — configuration reference
trace.playwright.dev — the hosted viewer, for opening traces without the CLI
Playwright documentation — general guides, including CI configuration

Final Thoughts

Most test-debugging time isn't spent fixing bugs — it's spent recreating the conditions that exposed them. Trace Viewer removes that step by keeping a full record of the run itself, so the question shifts from "can I reproduce this?" to "what does the trace show?"

For engineering teams, the value isn't measured by prettier debugging tools — it's measured by fewer engineering hours lost to reproducing failures. Shorter debugging cycles, fewer unnecessary CI reruns, and faster root-cause analysis are improvements that show up in both developer productivity and infrastructure costs.

Stop Debugging Blind: Playwright Screencast API for Richer Test Evidence

Vanessa Sastre — Wed, 22 Jul 2026 22:13:02 +0000

When an automated test fails, the error message alone is often insufficient to diagnose the root cause.

You're usually left asking:

What actions happened before the failure?
Which element was being interacted with?
Where exactly did the app start behaving differently than expected?
Can a teammate understand the failure without re-running the test themselves?

Playwright 1.59 introduced page.screencast, a programmatic recording API that answers these questions by turning a test run into a narrated, annotated video — instead of just a pass/fail line in a report.

With screencast-based reporting, a test can produce:

A recording of the full execution
Visual annotations on every interacted element
Chapter markers that break the run into named stages
Custom HTML overlays for context or metadata
Real-time JPEG frame capture for external tooling
"Video receipts" for AI-driven test and coding agents

The goal is simple: make failures faster to understand, and make passing runs easier to trust.

Why Screencasts Matter

Traditional artifacts already carry useful information:

Artifact	What it tells you
Logs	What the framework reported
Screenshots	The app's state at one moment
Traces	DOM snapshots, network activity, console output

A screencast adds a fourth layer that none of these provide well on their own: the full user journey, as a video.

Instead of staring at this:

Expected: "Order completed"
Received: "Payment failed"

...you watch the actual sequence: checkout opens, a product is added, payment details are entered, submit is clicked, and the error appears, all annotated in place.

Screencast vs. Playwright Trace

These two tools solve different problems, and a mature framework should use both.

Trace Viewer is built for deep technical debugging:

Network activity
DOM snapshots
Console messages
Step-by-step execution inspection

Screencast is built for fast, visual understanding:

A timeline of what a user (or agent) actually did
Visible, annotated interactions
Context that non-technical stakeholders can follow without opening dev tools

In practice: reach for traces when you need to diagnose why something broke, and for screencasts when you need to show what happened quickly, and to a wider audience than just engineers.

Setting Up Screencast Recording

The cleanest way to roll this out across a suite is a shared fixture, so every test gets recording, annotations, and reporting for free — no boilerplate in individual test files.

// fixtures.ts
import { test as base } from '@playwright/test';

export const test = base.extend({
  page: async ({ page }, use, testInfo) => {
    const videoPath = testInfo.outputPath('screencast.webm');

    await page.screencast.start({ path: videoPath });
    await page.screencast.showActions({ position: 'top-right' });

    await use(page);

    await page.screencast.stop();

    await testInfo.attach('Screencast', {
      path: videoPath,
      contentType: 'video/webm',
    });
  },
});

Every test that imports test from this file now automatically records a screencast and attaches it to the report, including in CI.

Adding Narration Inside a Test

Once the fixture is in place, use showChapter() to label the stages of a test as it runs:

import { test } from './fixtures';

test('checkout flow', async ({ page }) => {
  await page.screencast.showChapter('Login', {
    description: 'User authentication flow',
  });
  await page.goto('/login');
  // ...login steps

  await page.screencast.showChapter('Checkout', {
    description: 'Complete purchase flow',
  });
  // ...checkout steps
});

The resulting video reads like a labeled walkthrough rather than raw, unexplained footage.

Screencast API Reference

`page.screencast.start(options)`

Starts a screencast session. Pass path to save a WebM recording, or onFrame to receive JPEG frames in real time — both can be used together.

await page.screencast.start({
  path: 'execution.webm',
  size: { width: 1280, height: 720 },
  quality: 90,
});

Because it's called explicitly, you control exactly when recording starts and stops, unlike the older, always-on video config option, which records for the entire test lifecycle regardless of what you actually need.

`page.screencast.stop()`

Stops the active session and finalizes the video file at the path given to start(). Typically called right after the test body finishes:

await use(page);
await page.screencast.stop();

`page.screencast.showActions(options)`

Annotates interacted elements as they're clicked, filled, or hovered, so a reviewer can see exactly which element was touched and when.

await page.screencast.showActions({
  position: 'top-right',
  duration: 1500,   // ms each annotation stays visible
  fontSize: 16,
  cursor: 'pointer', // animates a cursor between actions; use 'none' to disable
});

Valid position values: top-left, top, top-right, bottom-left, bottom, bottom-right.

To turn annotations off mid-test:

await page.screencast.hideActions();

Suite-wide alternative: if you want action annotations everywhere without touching a fixture, enable them directly in playwright.config.ts:

export default defineConfig({
  use: {
    video: {
      mode: 'on',
      show: {
        actions: { position: 'top-left' },
        test: { position: 'top-right' },
      },
    },
  },
});

`page.screencast.showChapter(title, options)`

Displays a centered, blurred-backdrop overlay to mark a new stage of the recording. Disappears automatically after duration (defaults to a couple of seconds).

await page.screencast.showChapter('Payment validation', {
  description: 'Submitting card details and confirming charge',
  duration: 4000,
});

Chaining a few of these gives you a scannable timeline:

Login → Search product → Add to cart → Checkout → Payment validation

Reviewers can jump straight to the stage they care about instead of scrubbing a long recording blindly.

`page.screencast.showOverlay(html, options)` / `showOverlays()` / `hideOverlays()`

Adds arbitrary HTML on top of the recording — handy for environment info, build numbers, or debug messages.

await page.screencast.showOverlay(
  '<div style="color:red">Running checkout validation</div>',
  { duration: 3000 }
);

Omit duration and the overlay stays until you explicitly hide or remove it. showOverlays() / hideOverlays() toggle visibility of overlays already on screen without discarding them.

Real-Time Frame Capture

Pass onFrame to start() to stream JPEG-encoded frames while the test runs, instead of (or alongside) writing a video file:

await page.screencast.start({
  onFrame: ({ data, timestamp, viewportWidth, viewportHeight }) => {
    processFrame({ data, timestamp, viewportWidth, viewportHeight });
  },
});

This opens the door to live dashboards, vision-model analysis, or custom monitoring pipelines that react to what's on screen during execution, not after.

Agentic Video Receipts

Screencasts are also a good fit for AI-driven testing and coding agents, where a plain text summary ("verified checkout — passed") is much less convincing than a video showing exactly what the agent did.

await page.screencast.start({ path: 'receipt.webm' });
await page.screencast.showActions({ position: 'top-right' });

await page.screencast.showChapter('Verifying checkout flow', {
  description: 'Validating payment completion',
});

// Agent performs its verification steps here
await page.locator('#coupon').fill('SAVE20');
await page.locator('#apply-coupon').click();
await expect(page.locator('.discount')).toContainText('20%');

await page.screencast.showChapter('Done', {
  description: 'Checkout validation completed',
});
await page.screencast.stop();

The output is a self-contained "receipt": chapter titles explain intent, action annotations show exactly what was clicked or filled, and a human can review the whole thing in the time it takes to watch a short clip, no re-running the agent required.

CI/CD Recommendations

Recording every single test run adds up fast in storage and CI time. A few practical guardrails:

Record failures, not everything. Attach the screencast only when a test doesn't match its expected status:

  if (testInfo.status !== testInfo.expectedStatus) {
    await testInfo.attach('Screencast', {
      path: videoPath,
      contentType: 'video/webm',
    });
  }

Record critical paths deliberately. Reserve always-on recording for your highest-value flows (checkout, sign-up, payment) rather than every spec.
Clean up old artifacts on a schedule so recordings don't silently pile up in CI storage.

Official Resources

This post covers the common patterns, but the official docs are the source of truth for full option lists, edge cases, and future updates:

Screencast API reference — full method and options list
Playwright release notes — see the v1.59 entry for the original page.screencast announcement, and later releases for additions like the cursor option
Playwright documentation — general guides, including video/trace configuration If you hit something this post doesn't cover, those are the pages to check first.

Final Thoughts

Test automation is moving past a simple pass/fail line. Screencast-based reporting gives teams:

Faster failure diagnosis
A visual record of execution flow anyone can follow, technical or not
Better handoffs between QA and development
A foundation for reviewing AI-driven testing and coding agents

A mature framework shouldn't just report that a test failed, it should show what happened, where it happened, and give you what you need to fix it.

DEV Community: Vanessa Sastre

Playwright Trace Viewer: Debug Failed Tests Without Reproducing Them

The Problem: Debugging Requires Reproducing

The Fix: Open the Trace Instead of Re-Running the Test

Setup: Two Lines of Config

What's Inside a Trace

Traces as Context for AI Agents

The Efficiency Case

CI/CD Recommendations

Official Resources

Final Thoughts

Stop Debugging Blind: Playwright Screencast API for Richer Test Evidence

Why Screencasts Matter

Screencast vs. Playwright Trace

Setting Up Screencast Recording

Adding Narration Inside a Test

Screencast API Reference

page.screencast.start(options)

page.screencast.stop()

page.screencast.showActions(options)

page.screencast.showChapter(title, options)

page.screencast.showOverlay(html, options) / showOverlays() / hideOverlays()

Real-Time Frame Capture

Agentic Video Receipts

CI/CD Recommendations

Official Resources

Final Thoughts

`page.screencast.start(options)`

`page.screencast.stop()`

`page.screencast.showActions(options)`

`page.screencast.showChapter(title, options)`

`page.screencast.showOverlay(html, options)` / `showOverlays()` / `hideOverlays()`