Playwright Trace Viewer Workflow for Finding the First Mismatch

A Playwright assertion usually reports the last visible symptom. The useful failure may have happened several actions earlier when a request returned the wrong status, the page logged an application error, or the DOM moved into an unexpected state.

Playwright Trace Viewer lets you inspect those signals on one timeline. You can move through recorded actions, compare DOM snapshots before and after an action, inspect network traffic, read browser and test console output, open source locations, and review the final error.

The fastest workflow is simple: start at the assertion, move backward to the first meaningful mismatch, and stop when you have a specific next question. Do not begin by replaying every successful click.

This guide covers how to record and open a trace, what each panel answers, and how a controlled two-run comparison exposed a version conflict before the assertion timeout.

What Playwright Trace Viewer records

A Playwright trace is an inspectable archive of a recorded browser test. Depending on configuration, it can include:

• test actions and timing;

• DOM snapshots before, during, and after actions;

• locator details and Playwright call logs;

• source locations;

• network requests and responses;

• browser and test console messages;

• errors and stack traces;

• screenshots and a filmstrip;

• browser, viewport, project, and test metadata;

• attachments such as visual comparison images.

This is different from a screen recording. Video shows pixels over time. A trace connects the action to the DOM, request, console output, source, and error that surrounded it. Video is still useful for motion, focus, or layout timing, but Trace Viewer is usually better when the receiver needs to inspect why a test reached the wrong state.

The official Playwright documentation recommends recording a trace on the first retry in CI. That keeps routine storage bounded while preserving a diagnostic run. If retries are disabled, retain-on-failure keeps traces only for failed tests.

Record the attempt you actually need

Use a configuration that matches the failure question:

import { defineConfig } from '@playwright/test';

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

on-first-retry records the retry, not the original attempt. That distinction matters when the first run fails and the retry passes. The passing retry may omit the state you wanted to diagnose.

For a bounded local investigation, record the exact run:

Do not enable every trace forever without reviewing storage, access, and retention. A trace can contain page text, DOM structure, screenshots, URLs, request data, console messages, and test source. Use synthetic accounts when possible and treat CI traces as potentially sensitive.

Open a saved trace

Open a local archive with:

If the HTML reporter is enabled, open the report and select the trace attachment:

Playwright also provides trace.playwright.dev. The official documentation says this static viewer loads a selected trace in the browser and does not transmit its data externally. Your own trace may still contain sensitive information, so review sharing and device policy before opening production material anywhere outside the controlled CI or development environment.

Read the panels in a useful order

Each panel answers a different question. The table below keeps the investigation focused.

Start with expected versus actual

Read the assertion first. Separate these failure classes:

• no element matched;

• multiple elements matched;

• the intended element never became actionable;

• the action completed but the next state was wrong;

• the state was correct briefly and then changed;

• the browser state looked right but a durable outcome was never verified.

That first classification prevents random edits. If a button click completed and a later status assertion failed, locator tuning is unlikely to be the first move.

Move backward to the first contradiction

Select the failed assertion or action, then step backward. Ask:

1. What was the last state that matched the test's assumptions?

2. Which action first changed that state?

3. Did the DOM, request, console, or URL disagree first?

4. What is the smallest question the receiver should answer next?

Stop at the earliest signal that changes the diagnosis. A thirty-action trace does not require a thirty-step explanation.

Use DOM snapshots for target and state

The Before, Action, and After snapshots can show the element Playwright targeted and the state around it. Check the accessible role and name, visible text, attributes, disabled or selected state, duplicate controls, overlays, and the click position.

A screenshot can show that a control looked correct. The snapshot can show that Playwright clicked a different matching node or that the status element already contained the failure message.

Use Network for browser-to-service boundaries

Filter to the request associated with the decisive action. Inspect the method, route, status, timing, request body, and response body when retained.

A click can succeed while the request returns a conflict. The Actions panel proves the interaction happened. Network explains what followed.

Use Console for application meaning

Console output is most useful when the application emits a focused domain event near the failing request. A message such as preferences_save_conflict 12 11 connects a generic HTTP 409 to the state rule the application enforced.

Keep the time window tight. Page-load warnings and unrelated third-party messages can hide the one event that matters.

Return to Source after classifying the failure

Source is where you decide whether the test asserted the wrong contract, skipped a readiness boundary, used a brittle locator, or exposed a product defect. Reading source last reduces the temptation to rewrite a test before understanding the browser state.

Controlled comparison of a passing and failing trace

For this article, the Samelogic team ran Playwright Test 1.62.1 against a synthetic account-preferences page in Chromium. The fixture makes no external request and contains no customer data.

Both tests performed the same visible flow:

1. open Account preferences;

2. enable Use dark theme;

3. click Save settings;

4. expect the status to become Settings saved.

The controlled variable was the response to PUT https://fixture.test/api/preferences.

The passing run returned HTTP 200 with version 12. Its status changed to Settings saved. The test passed and produced a 19,703-byte trace archive.

The failing run returned HTTP 409 with expectedVersion: 12, submittedVersion: 11, and error: version_conflict. The page logged preferences_save_conflict 12 11, rendered Settings changed elsewhere. Reload and try again, and then failed the success assertion. That run produced a 42,912-byte trace archive.

The first useful mismatch was the 409 response. The assertion timeout was only the final symptom. Adding a delay would make the same contradiction arrive later.

The experiment source, JSON test report, screenshots, and both trace ZIP files are retained together under the August 30 publication artifact. The passing and failing traces were produced by the same test code, browser, viewport, fixture, and action sequence, with only the response mode changed.

What a trace cannot prove by itself

Trace Viewer explains the recorded browser run. It does not automatically prove every external consequence.

A 200 response may arrive before an asynchronous job finishes. A confirmation banner may appear before another session can observe the saved value. A message may be accepted before delivery. When the durable result matters, add an independent readback of that result after the browser action.

A trace also cannot recover state that was never recorded. If CI saved only a passing retry, the original failure is absent. If the application masks a response body, the trace cannot invent it. If the test starts after the critical setup transition, the trace begins too late.

Use the trace to classify the browser failure and identify the first mismatch. Use server logs, controlled data, or an independent readback for the next layer.

A compact handoff for the receiving engineer

Do not send only trace.zip. Include a short note that points the receiver to the useful window:

Test: saves dark-theme preference
Environment: Chromium, CI, synthetic account
Expected: status becomes Settings saved
Actual: status says settings changed elsewhere
First mismatch: PUT /api/preferences returned 409
Trace location: attached trace.zip
Open at: Save settings click, then Network and Console
Next question: why did setup submit version 11 when the server expected 12?

This turns a large archive into a focused debugging handoff. A Ministry of Testing discussion reflects the same practitioner need. Contributors described using Trace Viewer in local and CI debugging, and combining context such as logs, screenshots, and DOM snapshots according to the failure.

For broader failure causes, use Samelogic's flaky Playwright tests guide. If the trace began with generated steps, review Playwright Codegen output before commit. For agent-driven runs, see how to verify a Playwright MCP browser outcome.

When the important browser path starts outside a Playwright test, install CSS Selector & XPath Finder by Samelogic and deliberately capture the bounded path before sending it to the teammate fixing the issue.

Sources

• Playwright Trace Viewer documentation

• Ministry of Testing discussion on debugging automated e2e tests