Debugging Playwright Test Failures with the Trace Viewer

The Debugging Ritual Nobody Talks About

A Playwright test fails in CI. The Slack bot fires. You open the GitHub Actions log and scroll through two hundred lines of terminal output to find the error: locator.click: Target closed. That tells you almost nothing.

You need context. What did the page look like before the click? Did a network request fail? Was there a console error? Was the element even visible? The error message alone does not answer any of these questions.

So you download the CI artifacts. You find a zip file. You unzip it. You run the trace viewer locally. After ten minutes of setup, you can finally see what happened. Now imagine doing this three times a day, across a team of eight engineers.

This is the default debugging experience for Playwright tests in CI, and it wastes an enormous amount of engineering time.

What Playwright Traces Actually Are

Playwright traces are the single most powerful debugging tool in the Playwright ecosystem, and most teams underuse them. A trace is a detailed recording of everything that happened during a test execution:

• DOM snapshots at every action — before and after each click, fill, navigation, and assertion
• Network requests and responses — every API call with timing, headers, status codes, and payloads
• Console logs — everything the browser logged during execution
• Action timeline — a step-by-step replay of every Playwright action with precise timestamps
• Source code — the test source alongside the execution timeline

Think of a trace as a flight recorder for your test. When something goes wrong, the trace contains everything you need to understand why — without reproducing the failure locally.

How Traces Work Today (Without Euriqa)

The standard trace workflow in most teams looks like this.

First, you enable tracing in your Playwright config:

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

export default defineConfig({
  use: {
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'on-first-retry',
  },
  retries: 2,
})

The trace: 'on-first-retry' setting tells Playwright to capture a trace on the first retry of a failing test. This is a good default because it avoids the overhead of tracing every test while still capturing diagnostic data when something goes wrong.

When a test fails and retries, Playwright writes a .zip file containing the trace data. In CI, this file ends up in the build artifacts. To view it, you need to:

1. Navigate to the CI job
2. Find the artifacts section
3. Download the trace zip file
4. Run npx playwright show-trace trace.zip on your local machine

This requires every developer on the team to have Playwright installed locally. The artifacts expire after a few days (GitHub Actions defaults to 90 days, but many teams set it lower). And there is no way to share a trace with a teammate — you send them the zip file over Slack and they repeat the same local setup.

It works, but the friction is real. And friction means people skip the trace and guess at root causes instead.

How Euriqa Changes This

With Euriqa, trace files are uploaded automatically during the test run. When a test fails, you open the Euriqa dashboard, click into the failing test, and click "View Trace." The trace opens directly in Playwright's official trace viewer — in your browser.

No downloads. No local setup. No npx commands. The trace viewer loads with a secure signed URL that expires after one hour. Anyone on your team with project access can view it.

Here is what that workflow looks like in practice.

A Real Debugging Session

Your CI pipeline runs the nightly test suite. Sixteen tests fail. You open the Euriqa dashboard and see the run summary: 484 passed, 16 failed, 3 flaky.

You click into the first failure: checkout.spec.ts > should add item to cart. The test details page shows:

• Error: locator.click: Target closed
• Location: checkout.spec.ts:47:22
• Screenshot: the page at the moment of failure — it shows a loading spinner

This narrows it down, but you still do not know why the page closed. You click View Trace.

The trace viewer opens in a new tab. You see the full action timeline on the left:

1. page.goto('/products') — 320ms
2. page.click('[data-testid="product-card"]') — 45ms
3. page.waitForURL('/products/widget-pro') — 890ms
4. page.click('[data-testid="add-to-cart"]') — failed

You click on step 3. The DOM snapshot shows the product page loading. You switch to the Network tab and see it: a POST /api/cart/validate request returned a 500 Internal Server Error with the body {"error": "inventory service unavailable"}.

The page crashed because the backend inventory service was down. The Target closed error was a downstream symptom, not the root cause. This took five minutes to find in the trace viewer. Without it, you might have spent thirty minutes trying to reproduce locally — and failed, because the inventory service is back up now.

The Team Effect

The real value multiplies across the team. When the QA lead finds the root cause, they copy the Euriqa dashboard URL and paste it into the Slack thread. The backend engineer clicks the link, opens the trace, sees the 500 response, and starts investigating the inventory service. No file transfers. No "can you send me the trace?" No setup instructions.

Recommended Playwright Configuration for Traces

Here is the configuration we recommend for teams using Euriqa:

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

export default defineConfig({
  retries: 2,
  use: {
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'on-first-retry',
  },
  reporter: [
    [
      '@euriqa/euriqa-playwright',
      {
        apiKey: process.env.EURIQA_API_KEY,
        projectId: process.env.EURIQA_PROJECT_ID,
        uploadScreenshots: true,
        uploadTraces: true,
        uploadVideos: true,
      },
    ],
    ['html'],
  ],
})

A few notes on these settings:

• trace: 'on-first-retry' — Captures a trace on the first retry of a failing test. This gives you diagnostic data for failures without the performance overhead of tracing every passing test. If you want traces for every test (useful during debugging phases), use 'on' — but be aware this increases execution time and artifact size.
• screenshot: 'only-on-failure' — Takes a screenshot when a test fails. Combined with the trace, this gives you a quick visual of the failure state before diving into the full timeline.
• video: 'on-first-retry' — Records a video on retry. Videos are useful for understanding timing-sensitive failures where the trace alone is not enough, such as animation issues or rapid state changes.
• retries: 2 — Two retries is a reasonable default. It catches genuine flakiness without masking persistent failures.

Euriqa uploads all three artifact types (screenshots, traces, videos) by default. You can disable any of them in the reporter config if you want to reduce upload time or storage usage.

Beyond Traces: Screenshots, Videos, and HTML Reports

Traces are the deepest debugging tool, but they are not always what you need first. Sometimes a screenshot is enough — you see the failure state, recognize the issue immediately, and fix it without opening the trace at all.

Euriqa gives you all three levels of debugging context in one place:

1. Screenshots — Quick visual check. Is the page in the right state? Is there an error banner? Is the element visible?
2. Videos — Watch the test execute in real time. Useful for understanding sequences of interactions and timing issues.
3. Traces — Full debugging toolkit with DOM snapshots, network requests, console logs, and action timeline.

Each level is available directly in the dashboard, accessible to everyone on the team, with no local tooling required.

Give Your Whole Team Access to Traces

The best debugging tool is the one people actually use. When traces require downloading zip files and running local commands, most engineers skip them. When traces are one click away in a shared dashboard, they become the first thing everyone reaches for when a test fails.

Get started free at app.euriqa.dev and give your whole team instant access to Playwright traces, screenshots, and videos — no setup required.