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.
- 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 500on an API route. Standard test runners only reportTimeout 30000ms exceeded, sending developers on wild goose chases. - 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.ziparchives, forcing them to hallucinate inaccurate fixes. - 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.
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) │
└──────────────┘ └──────────────┘
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) |
Run in any Playwright project repository:
# Auto-detect Playwright config, wire GitHub Actions CI failure autopsy & register MCP
npx playwright-trace-doctor init
# Preview changes without modifying disk
npx playwright-trace-doctor init --dry-run# 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 --jsonAdd directly to your .github/workflows/playwright.yml:
- name: Autopsy Broken Playwright Tests
if: failure()
uses: Pranav-Nexus/playwright-trace-doctor@v1
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
post-pr-comment: trueAdd 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"]
}
}
}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.
Scans project subdirectories (test-results/, playwright-report/, .playwright-artifacts/) and returns the newest trace file with file metadata.
Extracts only aborted, 4xx, and 5xx HTTP requests captured during the test run.
Analyzes a fragile CSS or XPath selector and suggests resilient Playwright locators (getByRole, getByTestId, web-first auto-await assertions).
Run the built-in 5-suite stress benchmark simulating authentic browser crashes:
# Run the automated stress benchmark
npm run test:stressOutput:
============================================================
🧪 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)
============================================================
MIT © 2026 Pranav H