Read Playwright Trace Viewer Like a Failure Timeline

A failed screenshot shows one moment after the test gave up. A Playwright trace shows the sequence that produced that moment: the locator call, actionability checks, page state before and after an action, requests, console output, and the source line involved. Effective trace analysis therefore reads backward from the failure until it finds the earliest event that contradicts the expected journey.

That distinction matters. "Button not visible after 30 seconds" is a terminal symptom. The root cause may be a rejected API request eight seconds earlier, an overlay that never closed, a redirect to the wrong tenant, or a locator that resolved to a hidden duplicate. Trace Viewer can separate those classes of failure when it is treated as a synchronized timeline rather than a collection of tabs.

Establish the failure window before forming a theory

Open the retained archive with npx playwright show-trace path/to/trace.zip, or enter through the HTML report. The official Trace Viewer documentation explains that selecting an action aligns its snapshots, source, call details, logs, console entries, and network activity. Use that alignment as the unit of investigation.

Begin at the red failure marker. Read the error and source location, then select the final successful action. This creates a bounded window: the application was still consistent with the scenario before that action, but something diverged before the failed assertion or operation. Do not scan the entire archive for anything unusual. Search within this causal interval first.

Capture evidence that survives CI

For a Playwright Test project, prefer configuration-level tracing because it includes test-runner steps, assertions, and fixtures in addition to browser operations. on-first-retry is a strong default when retries are enabled: the first attempt establishes that a failure occurred, and the retried attempt captures evidence in a clean worker. retain-on-failure is useful when retries are disabled or the original attempt is especially important.

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',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  reporter: [['html', { open: 'never' }]],
});

Upload the entire relevant output directory even when the test command exits nonzero. A CI step guarded only by success silently discards the evidence needed for the failed run. Set a retention period that matches investigation latency and data sensitivity; traces may contain URLs, request bodies, text rendered in the DOM, and attachments.

Read the action and call log before the screenshot

The Actions panel tells you which locator was used and how long an operation took. The Call and Log panels expose the mechanics behind it: locator resolution, strictness, scrolling, and waits for visibility, enabled state, and stability. These details often classify a failure before visual inspection.

If a click remained pending on stability, look for animation or layout movement. If the locator repeatedly resolved to multiple nodes, the failure is selector ambiguity, even if the screenshot makes one button look obvious. If it resolved correctly but an overlay intercepted interaction, investigate the overlay lifecycle rather than forcing the click.

Use the Before, Action, and After views to answer three distinct questions. Was the intended element present before input? Where did Playwright actually apply input? What state followed? A click action snapshot can highlight the target and click position, making it possible to distinguish a wrong target from a correct target whose event handler failed.

Treat DOM snapshots as historical documents

A trace DOM snapshot is not the live application. It is a recorded state around an action that can be inspected and compared. Search for the semantic role or test id used by the locator, inspect duplicates, and compare attributes such as aria-expanded, disabled, or a loading label across adjacent actions.

Do not infer behavior solely from markup presence. An element may exist outside the viewport, beneath a dialog, or in a non-actionable state. Pair the snapshot with actionability logs and the screencast. Conversely, a screenshot may omit useful off-screen structure that the DOM snapshot preserves. The two views answer different questions.

When debugging a failed assertion, compare the last successful state with the assertion state. If a row never appears, ask whether the parent table entered loading, empty, or error state. That state transition usually points to a more specific boundary than the missing row itself.

Correlate network activity with the triggering action

The Playwright trace network tab can be filtered to a selected action or timeline range. Find the request expected to result from the user operation, then inspect method, URL, status, request body, response body, headers, duration, and size. A missing request suggests the UI event did not dispatch or client validation blocked it. A present request with an error response shifts ownership toward API behavior or test data.

A successful HTTP status does not prove the response was usable. Inspect the payload for a business error, unexpected schema, stale entity, or tenant mismatch. Also check ordering: a slower earlier response may overwrite a newer state, or the assertion may begin before the application subscribes to an event.

Avoid declaring "network flake" from one long duration. Compare failure and passing attempts, check whether the test waited on the correct user-visible result, and inspect server logs when available. The trace proves what the browser exchanged; it cannot independently explain why a service responded that way.

Use console and source evidence to close the loop

Console entries are synchronized with the chosen action window. A thrown client exception immediately after a valid response can explain why the DOM never updated. Warnings may reveal hydration issues, blocked resources, or duplicate keys, but prioritize messages that occur in the bounded failure interval and connect to the affected component.

The Source panel anchors every action to test code. This is especially helpful when helper abstractions produce repeated calls. If the trace labels are too generic, use test.step to describe domain operations so a future reader can navigate by intent.

import { expect, test } from '@playwright/test';

test('approver can publish a release', async ({ page }) => {
  await test.step('open the pending release', async () => {
    await page.goto('/releases/pending');
    await page.getByRole('link', { name: 'Release 1842' }).click();
  });

  await test.step('approve and observe publication', async () => {
    const response = page.waitForResponse(
      value => value.url().endsWith('/api/releases/1842/approve'),
    );
    await page.getByRole('button', { name: 'Approve release' }).click();
    expect((await response).ok()).toBeTruthy();
    await expect(page.getByRole('status')).toHaveText('Published');
  });
});

This structure does not replace trace inspection. It gives the timeline domain landmarks and preserves the request-to-visible-state relationship in the test itself.

Compare attempts without erasing worker boundaries

When a retry passes, compare the failing and passing traces at the first divergent action. Verify that project, browser, viewport, environment, and test data are equivalent. A retry runs in a fresh worker, so a pass may indicate leaked process state, a setup race, or data cleanup rather than random browser behavior.

Look for differences in request order, initial DOM, authentication state, and fixture setup. If the first attempt sees an old record while the retry sees the new one, the likely issue is eventual consistency or data readiness. If a modal is present only on the first attempt, a persisted account flag may be involved. The comparison should produce a testable hypothesis, not merely the label "flaky."

Recognize common misleading signals

The final timeout is rarely the first fault. A locator timeout may follow a navigation to an error page. A visual mismatch may follow a missing font request. An expect(response.ok()).toBeTruthy() failure may be downstream from malformed test data created in a fixture.

Another trap is changing the locator because the snapshot contains a different element. First establish why the journey reached that state. A perfect selector cannot fix an unauthorized redirect. Likewise, adding a wait may hide a response-order defect without proving which event makes the page ready.

When an action was forced, the trace may show input applied to an element a user could not operate. Treat that as a test-design warning. Remove force, restore an observable readiness contract, and let actionability expose the real obstruction.

Balance trace detail, storage, and privacy

Tracing every test on every run creates large artifact sets and can make the useful archive harder to find. Capture broadly only during a focused incident. For routine CI, retain failure-oriented traces, name artifacts with project and attempt identifiers, and upload them under an always-run condition.

Review what the application exposes in URLs, DOM text, console output, and request payloads. Use synthetic accounts and redact secrets before they reach the browser. Access controls and artifact expiry are part of the debugging architecture, not administrative cleanup.

Operational trace-analysis checklist

• Open the exact failed attempt and confirm its project metadata.
• Identify the failed action and the last successful domain step.
• Read call and actionability logs before changing a locator.
• Compare Before, Action, and After DOM states.
• Filter network and console evidence to the same action window.
• Check whether a request is missing, rejected, malformed, or merely slow.
• Compare retry traces at the earliest divergence.
• Account for the fresh worker used after a failure.
• Write one root-cause hypothesis with supporting panels.
• Confirm the hypothesis with the smallest focused rerun.

Turn the timeline into a corrective action

Finish analysis by naming the earliest observable contradiction, its evidence, and the responsible boundary. Then choose a fix that improves the product or its testability: expose a stable status, isolate test data, wait on a meaningful response, repair a race, or strengthen a locator contract. Re-run the narrow scenario with tracing, then run its surrounding suite without relying on the trace. The archive has done its job when it changes a vague timeout into a specific, reproducible correction.