Back to Blog
Post

How to Use the Playwright Trace Viewer for Test Debugging

TraceLoom Team ·

The Playwright trace viewer is the built-in debugging tool that ships with Playwright. When a test fails in CI, the trace viewer lets you replay the exact execution — every action, every DOM snapshot, every network request — without re-running the test. This post covers how to open a trace, what each panel shows, and how TraceLoom surfaces traces per test directly from your S3 bucket.

What is the Playwright Trace Viewer?

The Playwright trace viewer is a local web UI that opens a .trace.zip file and renders it as an interactive replay. It ships bundled with Playwright — no separate install, no extra configuration. If you have Playwright installed, you already have the trace viewer.

Think of the difference between logs and traces this way: logs tell you what the test said; traces show you what the test saw. A log entry like expect(locator).toBeVisible() timed out tells you the symptom. The trace viewer shows you the page at that exact millisecond — what DOM was rendered, what network requests had completed, what the console contained.

Traces are enabled via trace: 'on' in playwright.config.ts:

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

export default defineConfig({
  use: {
    trace: 'on',
  },
});

With this setting active, Playwright writes a trace.zip for every test to the test-results/ directory. Each zip is a complete, self-contained replay of one test’s execution.

How to Open a Trace

Opening a trace from the command line

The simplest method: drag the trace.zip file onto https://trace.playwright.dev, or run:

npx playwright show-trace trace.zip

This opens the Playwright trace viewer in your default browser locally. Works for traces downloaded from CI, pulled from S3, or collected locally during development. The path argument can also be the full test-results/my-test/trace.zip path Playwright writes by default.

Opening a trace from VS Code

The Playwright VS Code extension adds a “Show Trace” button to the Test Results panel. Click any failed test; the extension pipes the trace into an embedded Playwright trace viewer without leaving the editor. This is the fastest path for local debugging — no terminal commands, no browser tabs to manage.

Opening a trace from TraceLoom

Every test run in TraceLoom surfaces per-test traces as clickable links. You land on the run page, click a failed test, and the Playwright trace viewer opens with the recorded execution — no local download, no CLI, no VS Code round-trip. The trace viewer runs in your browser against the .trace.zip stored in your own S3 bucket.

What Each Panel Shows

The Playwright trace viewer has five primary panels. Each shows a different slice of what the test did and what the browser saw. Learn these panels and most debugging becomes a two-minute exercise rather than a thirty-minute reproduction hunt.

Actions panel

The Actions panel is a vertical list of every Playwright action in order — goto, click, fill, expect, waitFor, locator, and more. Each entry shows the action name, the target locator or URL, and the duration in milliseconds.

Clicking an action jumps the DOM snapshot, screenshot, network timeline, and console view to that exact moment in the test. Failed actions are highlighted in red. When debugging, find the red action — that is where the test broke. But look at the two or three actions immediately before it, because the preceding state almost always reveals why it broke.

Timeline panel

The Timeline panel is a horizontal strip running across the top of the viewer. It shows action durations, browser events, and a compressed network waterfall on a shared time axis.

Scrub to any timestamp and the DOM snapshot, network panel, and console update in lock-step. If an action is slow, scrub to just before it and watch what the network was doing — a slow or failed request is the most common explanation for timeout failures that look like selector issues.

Network panel

The Network panel lists every HTTP request and response during the test — full request headers, response headers, and response body. Filter by type (XHR, fetch, document, script, image) and by response status.

When debugging an assertion failure that seems unrelated to the network, filter to 4xx and 5xx status codes first. A failed API call that returned 500 while the test was filling a form will show up here, and it is almost always the root cause of the assertion failure that fires three steps later.

Console panel

The Console panel shows all console.log, console.error, and uncaught exceptions from the page — timestamped and linked to the action that was executing when the log fired.

A console.error in the page’s own JavaScript often reveals the real failure faster than the Playwright error message itself. If the application code is logging an error, that error appears here verbatim, usually with a stack trace the Playwright assertion message omits entirely.

Source panel

The Source panel shows the Playwright test source code with the current line highlighted relative to the selected action. This maps an action in the Timeline or Actions panel back to the exact line in the spec file.

The Source panel shows which expect() failed and which fixture was active at that point. This matters most when a spec file runs the same helper across multiple tests — the Source panel tells you which call site in the shared helper triggered the failure.

How TraceLoom Surfaces Traces Per Test

In a standard Playwright CI setup, traces land in test-results/ on the CI runner and are uploaded as a tarball artifact. To debug a failure you download the artifact, unzip it, find the right trace file in the directory tree, and run npx playwright show-trace locally. That is four manual steps before you see a single panel.

TraceLoom removes every step. Every test’s trace.zip is uploaded directly from the EC2 worker to your S3 bucket as the test completes, at a deterministic path:

s3://your-bucket/runs/{runId}/{testId}/trace.zip

The TraceLoom dashboard lists every test in a run with a “View trace” link. Click the link and the Playwright trace viewer opens in-browser against the S3 object — no artifact download, no unzip, no local replay required.

The BYOC implication matters here: the trace never transits TraceLoom’s infrastructure. Your EC2 instance writes directly to your S3 bucket over the AWS internal network. The TraceLoom control plane only knows the trace exists — the path, the test name, the pass/fail status. Your test data stays in your account.

Debugging a Real Failure with TraceLoom Traces

Here is how a typical debugging session goes with TraceLoom traces in place.

A scheduled run shows 1 of 500 tests failed — the “checkout flow — apply coupon” spec. You click the failed test from the TraceLoom run dashboard. The Playwright trace viewer opens immediately.

Scan the Actions panel: the click('#apply-coupon') action is red. The action before it — fill('[name="coupon-code"]', 'SAVE20') — completed in 40 ms. So the element was reachable and the form field worked. The click itself is the failure point.

Open the Network panel. Filter to 5xx responses. There is a POST to /api/coupons that returned 500. It fired 80 ms before the click failed.

Open the Console panel. A CORS warning fired 100 ms before the 500 — Blocked: preflight response did not succeed.

Root cause: a recent backend deploy added a preflight requirement to the coupon endpoint, and the endpoint did not yet include OPTIONS handler support. The test exposed it immediately. Total debugging time: under two minutes. Without traces, this would have taken an hour of reproduction attempts and probably no definitive answer on the first day.

TraceLoom stores every trace in your S3 bucket and links it directly from the run dashboard. Your traces, your cloud, your debugging loop. Start free trial →

Related reading:

Back to Blog