From Test Failure to an Actionable Next Step

A failed Playwright run is an observation, not yet a diagnosis. This chapter focuses on the evidence that turns a browser run into an inspectable event—reports, retries, traces, snapshots, network records, console messages, screenshots, and video—and then compares the CLI, MCP server, and Test Agents as different callers of the same browser control. The reader’s practical judgment is twofold: choose evidence in proportion to the cost of being wrong, and keep state, page-provided data, and agent capabilities inside explicit trust boundaries.

A failure becomes evidence before it becomes a fix

A terminal line that says a test failed is a useful signal, but it collapses many causes into one result. The locator may have matched the wrong state. A request may have failed. The browser may have been running under a different project configuration. An overlay may have intercepted an action. A shared account may have been changed by another worker. The assertion may simply encode the wrong product expectation. A diagnosis needs the run’s conditions and sequence, not only its final status.

Playwright’s HTML report provides an organized view of test outcomes across browsers and projects. It can distinguish passed, failed, skipped, and flaky results, and a test’s detail view can expose errors, steps, attachments, and traces. This gives a reader a place to ask which scenario failed and under which configuration before opening an artifact. UI Mode serves a different but related purpose during development: it lets a person watch the run, inspect steps, and use a more interactive view while changing tests.

A trace records a time-ordered account of what Playwright observed during execution. The Trace Viewer can show the actions of the test and the state of the page around each action. It can expose DOM snapshots, source, network requests, console messages, errors, and other context, allowing a reader to move through the run rather than reconstructing it from scattered log lines. The snapshot is especially useful for a dynamic page: it can show what the browser presented at the moment an action was attempted, not only what the page looks like after the failure.

The trace is not automatically the root cause. It is evidence from one browser, project, context, network condition, and data state. A DOM snapshot can show that a button was disabled; it cannot by itself tell whether the server rejected the input for a valid business reason. A network record can show an error response; it cannot establish whether the application handled that error correctly. A console message can reveal a client exception; it may still be a consequence of an earlier navigation or data problem. Diagnosis comes from relating the observations to the intended contract.

Selective recording makes that evidence policy manageable. Traces, screenshots, and videos can be configured to record on every run, only on failures, or around retries.