Playwright Trace Decoder MCP

What playwright-trace-decoder-mcp MCP server does

playwright-trace-decoder-mcp MCP server turns Playwright trace.zip archives into focused, queryable results for failure investigation. Instead of exposing the archive as an undifferentiated collection of JSON and media files, it provides separate operations for test metadata, actions, browser logs, page structure, screenshots, and error relationships.

The server is aimed at Playwright end-to-end failures, especially those produced in CI. It can identify the failing action and top-level error, return the browser and viewport context, show failed network responses, and report JavaScript exceptions or warnings. It can also map a failed browser interaction to the file, line, and column in the test runner stack when that information is available in the trace.

How it works

Each operation receives a trace_path. The path may point to an absolute local archive or an HTTPS URL. For HTTPS inputs, the server downloads the archive and caches it for the session. Results are returned in focused formats rather than requiring an agent to read the archive directly.

List-oriented results, including action timelines, filtered network logs, and console output, accept limit and offset parameters. The documented range for limit is 1–500, with a default of 50, and responses include a has_more indicator for further pages.

The DOM-oriented tools use compact ARIA representations instead of full HTML. One operation returns the accessibility tree at a selected action, while another computes the added and removed ARIA lines around an action. Screenshot tools return Base64-encoded JPEG data, allowing an agent to inspect visual state when a page is blank or the accessibility tree does not provide enough information.

Tools and capabilities

The inspection tools expose test metadata, a high-level trace summary, paginated action history, server-error network responses, console errors, failure element state, and strict trace-format metadata. The strict metadata result includes the format version, retry-session breakdown, and HAR payload mode.

For UI investigation, the server can retrieve an accessibility tree, calculate DOM mutation deltas, obtain screenshots near failure, inspect requests that were still in flight, correlate completed fetches with DOM changes, and extract selected screencast frames around the failure window.

Root-cause tools build a chronological chain of preceding actions, network errors, and console errors; generate a stable 12-character SHA-1 signature from a normalized error; compare passing and failing traces; and map a locator or action to source code. Trace comparison aligns action sequences and reports structural differences, timing anomalies over 500 milliseconds, unmatched actions, and network changes.

Limitations and notes

The input is a Playwright trace.zip archive. The material describes analysis of trace data rather than live browser control or test execution, so it should be used after a trace has been produced. Visual results are encoded as Base64 JPEG data, which may still be sizable even though the server limits extraction to selected frames.

ARIA output is intentionally compressed and may not represent every detail available in raw HTML. The accessibility tree defaults to the snapshot associated with the failed action, while a specific action index can be requested. Screenshot selection similarly defaults to the image closest to failure, with an index available for walking the visual timeline.

playwright-trace-decoder-mcp MCP server can reduce the amount of trace data an agent needs to inspect, but conclusions still depend on what the recorded trace contains. The archive can also be trimmed by removing screenshots outside the critical failure window; the trimming result reports original size, reduced size, compression percentage, and the path to the new archive.