Skip to main content
Glama
Pranav-Nexus

playwright-trace-doctor

by Pranav-Nexus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🩺 Playwright Trace Doctor

The Instant MRI for Broken Web Tests.
When Playwright tests fail in CI, don’t waste hours digging through 50MB trace files. Trace Doctor pinpoints whether your UI broke or your backend crashed—and generates the exact self-healing fix code in under a second.

CI License: MIT MCP Compatible

⚡ The Pain It Solves

  1. The Downstream Casualty Trap: In modern web apps, a button click timeout is almost never a button bug—it's usually caused by a silent upstream HTTP 500 on an API route. Standard test runners only report Timeout 30000ms exceeded, sending developers on wild goose chases.

  2. Binary Blindspot for AI Coding Agents: AI coding agents (Antigravity, Cursor, Claude Code) only receive truncated terminal logs. They cannot read Playwright’s binary trace.zip archives, forcing them to hallucinate inaccurate fixes.

  3. Tool-Sprawl in Existing Decoders: Existing trace MCP servers force AI agents to make 6–10 consecutive tool roundtrips (open_trace → list_actions → get_action → get_network → get_console → get_dom), blowing token limits and stalling agent execution.

Related MCP server: deploytest MCP server

🚀 The Solution

playwright-trace-doctor provides one-shot, token-budgeted triage and self-healing recommendations in a single call (< 5ms latency, < 1.5k tokens).

┌────────────────────────────────┐
│   Playwright trace.zip         │
│   (Actions, DOM, Network, Log) │
└───────────────┬────────────────┘
                │
                ▼
┌────────────────────────────────┐
│  🩺 Playwright Trace Doctor    │
│  - In-Memory Streaming Parser  │
│  - Upstream 5xx/4xx Correlator │
│  - Heuristic Root Cause Engine │
│  - Self-Healing Fix Generator  │
└───────────────┬────────────────┘
                │
        ┌───────┴───────┐
        ▼               ▼
┌──────────────┐ ┌──────────────┐
│ Terminal CLI │ │  MCP Server  │
│  (Human PRs) │ │ (AI Agents)  │
└──────────────┘ └──────────────┘

📊 Benchmark vs Existing Decoders

Tested across 5 real-world stress scenarios (Strict Mode Violations, Pointer Interceptions, Missing Locators, Downstream 500s, and Web-First Assertion Mismatches):

Metric

Existing Decoders

Playwright Trace Doctor

Agent Roundtrips

6–10 fragmented tool calls

1-Shot Holistic Triage (triage_failure)

Upstream Causality

Ignored

Correlates 4xx/5xx network failures to UI timeouts

Self-Healing Code

None (raw JSON dumps)

Generates resilient Playwright locator replacements

Trace Auto-Discovery

Requires manual file path

Auto-detects latest trace in test-results/

CLI Mode

MCP-only

Dual-mode: Rich Terminal CLI + Stdio MCP

Diagnostic Latency

~500ms–2000ms

~3.2ms average execution time

Token Consumption

20k–50k tokens

< 1.5k tokens (strict token guard)

📦 Quick Start

1. Terminal CLI (Local & CI Usage)

# Auto-discover and triage the latest failed trace in the project
npx playwright-trace-doctor --latest

# Direct path inspection
npx playwright-trace-doctor path/to/trace.zip

# Output clean Markdown (ideal for GitHub Actions / PR comments)
npx playwright-trace-doctor --latest --markdown

# Output structured JSON
npx playwright-trace-doctor --latest --json

2. Model Context Protocol (MCP) Setup

Add to your MCP configuration (antigravity.json, .cursor/mcp.json, or claude_desktop_config.json):

{
  "mcpServers": {
    "trace-doctor": {
      "command": "npx",
      "args": ["-y", "playwright-trace-doctor", "mcp"]
    }
  }
}

🛠️ MCP Tools Reference

1. triage_failure (Primary Tool)

One-shot diagnostic of a Playwright failure trace. Extracts failing locator, stack trace, classified root cause, correlated network 4xx/5xx requests, console errors, and resilient self-healing fix code. Automatically finds latest trace if tracePath is omitted.

2. find_latest_trace

Scans project subdirectories (test-results/, playwright-report/, .playwright-artifacts/) and returns the newest trace file with file metadata.

3. get_failed_network_calls

Extracts only aborted, 4xx, and 5xx HTTP requests captured during the test run.

4. suggest_locator_fixes

Analyzes a fragile CSS or XPath selector and suggests resilient Playwright locators (getByRole, getByTestId, web-first auto-await assertions).

🧪 Comprehensive Stress Testing

Run the built-in 5-suite stress benchmark simulating authentic browser crashes:

# Run the automated stress benchmark
npm run test:stress

Output:

============================================================
🧪 RUNNING PLAYWRIGHT TRACE DOCTOR STRESS BENCHMARK (5 SUITES)
============================================================

✅ Suite [strict-mode]: Strict Mode Violation (Multiple Elements)
   Expected: STRICT_MODE_VIOLATION | Detected: STRICT_MODE_VIOLATION
   Perf: Parse 4.19ms, Analysis 0.81ms (Total: 5.00ms)
   Fixes Suggested: 2
------------------------------------------------------------
✅ Suite [pointer-intercept]: Pointer Events Intercepted (Modal Overlay)
   Expected: POINTER_INTERCEPTED | Detected: POINTER_INTERCEPTED
   Perf: Parse 2.28ms, Analysis 0.22ms (Total: 2.50ms)
   Fixes Suggested: 2
------------------------------------------------------------
✅ Suite [locator-timeout]: Locator Timeout (Element Missing in DOM)
   Expected: TIMEOUT_LOCATOR_NOT_FOUND | Detected: TIMEOUT_LOCATOR_NOT_FOUND
   Perf: Parse 1.88ms, Analysis 0.19ms (Total: 2.07ms)
   Fixes Suggested: 3
------------------------------------------------------------
✅ Suite [backend-500]: Backend API 500 Failure with Downstream Timeout
   Expected: BACKEND_API_FAILURE | Detected: BACKEND_API_FAILURE
   Perf: Parse 2.35ms, Analysis 0.15ms (Total: 2.50ms)
   Fixes Suggested: 1
------------------------------------------------------------
✅ Suite [assertion-failure]: Assertion Mismatch Failure (expect.toHaveText)
   Expected: ASSERTION_FAILED | Detected: ASSERTION_FAILED
   Perf: Parse 1.89ms, Analysis 0.18ms (Total: 2.07ms)
   Fixes Suggested: 2
------------------------------------------------------------

============================================================
📊 STRESS TEST SUMMARY: 5/5 PASSED (100% Target)
============================================================

📄 License

MIT © 2026 Pranav H

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers