Playwright Trace Viewer: How to Find Why a Test Failed

What Does the Playwright Trace Viewer Show?

A Playwright trace is a trace.zip file that gets generated as your test runs. The trace viewer opens that up and allows you to step through every action afterward. It's by far the most useful tool when you've got a failure that you can't reproduce on your machine (e.g., a test that only fails in CI).

The Playwright trace viewer docs describe these panels:

This is even more pertinent now that Playwright agents are capable of fixing failing tests. According to the Playwright docs, the "healer" will re-play the failing steps, inspect the current UI and propose a fix (e.g., a locator update, a wait adjustment or a data fix). Someone still has to verify that the proposed patch actually matches what the trace shows.

How Do You Record a Playwright Trace?

Playwright records traces via the trace option. The trace viewer intro suggests you record on the first retry, so your pass runs will stay fast:

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

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: {
    trace: 'on-first-retry',
  },
});

The trace option reference lists seven modes:

To force tracing for one local run, use npx playwright test --trace on. Outside the test runner, the library API records a trace around any block:

await context.tracing.start({ screenshots: true, snapshots: true });
// ... the steps you want to record ...
await context.tracing.stop({ path: 'trace.zip' });

How Do You Open a trace.zip File?

There are three ways to open a trace:

• From the HTML report: run npx playwright show-report, then click on the trace icon next to the test or open the Traces tab in its detail view.
• From the command line: npx playwright show-trace path/to/trace.zip
• From a URL: npx playwright show-trace https://example.com/trace.zip will open up a remote trace directly, which is very useful when your CI is storing its artifacts behind a link.

The docs also state that the browser-based viewer at trace.playwright.dev loads the entire trace into your browser and doesn't send anything anywhere.

When the trace says the app is broken, prove it in one command.

Note: Kane CLI runs the same user journey (starting with a plain English objective) in a real Chrome browser and saves the steps, screenshots, logs, and verdict into an evidence pack which you can attach to the bug. Install it via npm install -g @testmuai/kane-cli. Get started with Kane CLI.

How Do You Read a Trace to Find the Cause? (The 5-Check Trace Triage)

The vast majority of failures fall into 5 categories. Run the checks in order and stop at the first one that explains the failure. That's the 5-check trace triage.

Two rules keep this honest:

• Compare against a passing trace. If the test passes locally, then record a trace of the passing run with --trace on and compare the same step side by side. The difference is usually in the Network or Metadata panel.
• Don't fix the test to make it match a broken app. If checks 4 or 5 are going to explain the failure, then the test has done its job. Fixing the locator or adding a wait would simply be hiding the bug.

Playwright's healer agent works on the same principle. You add the agent definitions via npx playwright init-agents --loop=vscode (the Playwright test agents docs will show you that command and list VS Code, Claude Code, Codex and OpenCode as the loops). The docs state that the healer's output is a passing test or a skipped test if the healer determines the functionality is broken.

For a quick visual walkthrough of this concept, watch the video below from TestMu AI.

Subscribe to the TestMu AI YouTube channel for more tutorials on testing and automation.

How Do You Confirm an App Bug Prior to Logging It?

When the trace points at the app (checks 4 and 5), the next question is whether the user actually hits that problem or whether it's just the test that does. Re-run the user journey outside of your test code. That's what Kane CLI / TestMu AI's terminal testing agent does, starting from a plain English objective.

npm install -g @testmuai/kane-cli
kane-cli login
kane-cli run "Add the first product to the cart, open checkout, and verify the order summary shows a total" \
  --url https://staging.example.com

The command follows the kane-cli run "<objective>" [options] format in the Kane CLI reference, where --url sets the start URL. Each run saves an evidence pack with the steps, screenshots, logs, and verdict, which the Kane CLI product page says uploads to Test Manager by default. Per the Kane CLI CI/CD docs, kane-cli run exits with 0 for pass, 1 for fail, 2 if the run didn't start, and 3 for a timeout or cancellation.

• Kane CLI fails at the same step (the app is broken for users). File the bug with the trace and the evidence pack, and keep the test failing.
• Kane CLI passes: the user journey works, so the failure is in the test (its data or its environment). Go back to checks 2 to 4.

The Kane CLI product page also states that its healing will never change the acceptance criteria and that wrong results are reported as bugs rather than being healed into a pass. That's the property you want from a second opinion.

How Do You Use Traces in CI?

The trace viewer docs state that traces should run in CI on the first retry of a failed test. In practice:

• Set retries to something above zero in CI and trace: 'on-first-retry'.
• Upload the HTML report as a build artifact so that the traces survive the job.
• Download the artifact, extract it, and run npx playwright show-report on that folder, then open the trace for the failed test.
• Run the 5-check trace triage before you re-run anything. A green re-run with no diagnosis is just hiding a flaky test.

The upload step from Playwright's CI guide for GitHub Actions:

- uses: actions/upload-artifact@v5
  if: ${{ !cancelled() }}
  with:
    name: playwright-report
    path: playwright-report/
    retention-days: 30

The guide says the downloaded report requires a web server, so you need to open it via npx playwright show-report rather than just double-clicking the HTML file. If a test fails in CI but passes locally, then refer to TestMu AI's guide to Playwright flaky tests for the usual suspects.

Keep in mind that 'on' will record every test, and the docs refer to it as performance-heavy. Use 'retain-on-failure' if you're running without retries.

Trace Viewer vs Inspector vs HTML Report: Which Do You Need?

For the live debugging side of things, TestMu AI's guide to the Playwright Inspector covers breakpoints and live locator editing.

The Trace-First Debugging Checklist

• CI sets retries to be above zero and trace: 'on-first-retry'.
• Trace files are saved as CI artifacts on all failed runs.
• You start at the first error on the timeline rather than the last assertion.
• You check the Snapshots tab prior to touching a locator.
• You check the network and the console before you add a wait.
• You're comparing with a passing trace when the test passes locally.
• App bugs are confirmed outside of the test code and are then filed with evidence. The test remains red.
• Any healer or AI fix is reviewed against the trace prior to merge.

Conclusion

Open the trace from your most recent CI failure and run the five checks. If it's pointing at the app, then confirm the journey with the Kane CLI before you touch a line of test code. Install the Kane CLI and keep the trace and the evidence side by side in the bug.

If your suite records no traces yet, add trace: 'on-first-retry' and retries above zero to playwright.config.ts first, so the next red build leaves a trace.zip to open.

Testing from the terminal? Kane CLI by TestMu AI lets SDETs and developers plan, write, run and debug tests from the command line.

To run your first test, start free, or

book a demo

for a full walkthrough of the product.