ghost-qa

👻 ghost-qa

Autonomous headless browser QA & self-healing verification loop for coding agents. v2.1.1 — the 8-Trap Deep Browser Inspection Engine: 3 viewports × light/dark, QA Health Score (A+…F), interactive HTML dashboard, and regression diffing.

⭐ If this tool helps your AI coding workflow, please give this repository a Star! It helps more developers discover the project.

🧰 The VibeFoundry Agent Suite

*One command each — star all three and keep the whole suite free & maintained:*

• 🎨 [unslop](https://github.com/avivgerz-hue/unslop) — UI Design DNA & Anti-Slop Engine (npx -y unslop-mcp@latest init)
• 🛡️ [vibe-shield](https://github.com/avivgerz-hue/vibe-shield) — Security Scanner for AI Code (npx -y @vibefoundry/vibe-shield@latest scan .)
• 👻 [ghost-qa](https://github.com/avivgerz-hue/ghost-qa) — Autonomous Headless Browser QA (npx -y ghost-qa@latest test http://localhost:3000)

npx -y ghost-qa@latest test http://localhost:3000

Coding agents (Claude Code, Codex, Cursor, Windsurf) write code blind — then declare victory while the actual browser has React hydration errors, broken buttons, 500ing APIs, or mobile layout overflow.

ghost-qa fixes that. One command launches a headless browser against your running app, crawls the live DOM, safely pokes every button, traps runtime/network/layout failures, and hands the agent a structured Self-Healing Bug Report so it fixes its own bugs *before* telling you it's done.

npx -y ghost-qa test http://localhost:3000

No test scripts. No config. No mercy for "it works on my machine".

Prefer running straight from GitHub instead of npm? npx -y github:avivgerz-hue/ghost-qa test http://localhost:3000 works identically — every command in this README accepts either package source (ghost-qa mcp, ghost-qa init, …).

---

⚡ Quickstart

# 1. Start your app as usual

npm run dev # → http://localhost:3000

2. Verify it in a real browser (one-time: downloads Chromium)

npx playwright install chromium npx -y ghost-qa test http://localhost:3000

3. Teach your coding agent to do this automatically, forever

npx -y ghost-qa init

ghost-qa init installs .claude/skills/ghost-qa/SKILL.md and appends the strict "Verify in Browser Before Done" protocol to CLAUDE.md, AGENTS.md, and .cursorrules. From then on, your agent runs ghost-qa itself, fixes what it finds, and only reports completion on a PASS.

---

🔁 The Autonomous Self-Healing QA Loop

                        ┌──────────────────────────────────────────┐

│ CODING AGENT │ │ Claude Code · Codex · Cursor · Windsurf │ └───┬──────────────────────────────▲───────┘ writes code │ │ Self-Healing ▼ │ Bug Report ┌───────────────┐ ┌─────────┴──────────┐ │ DEV SERVER │ │ AGENT DIAGNOSTIC │ │ localhost:3000 │ │ verdict · #ids · │ └───────┬───────┘ │ fix playbook │ │ serves live DOM └─────────▲──────────┘ ▼ │ Markdown / JSON ┌────────────────────────────────────────┴──────────┐ │ 👻 ghost-qa │ │ │ │ Route Crawler ──► Interaction Runner │ │ │ │ │ │ ▼ ▼ │ │ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ │ │ CONSOLE │ │ NETWORK │ │ LAYOUT │ │ │ │ A11Y │ │ PERF │ │ 8 TRAPS │ │ │ │ TRAP │ │ TRAP │ │ TRAP │ │ │ └─────────┘ └──────────┘ └─────────┘ │ │ Desktop 1440×900 · Tablet 768×1024 · Mobile 375×812 │ └────────────────────────────────────────────────────┘ │ fix bugs ───────┘ re-run until ✔ PASS

1. The agent writes code and starts the dev server.
2. ghost-qa test crawls every internal route on Desktop 1440×900, Tablet 768×1024 and Mobile 375×812, in light + dark colour schemes, exercising interactive controls.
3. Eight traps capture everything the browser actually experienced, scored into a deterministic QA Health Score (0–100, Grade A+…F).
4. Failures return as a token-efficient diagnostic (GHOST-QA-REPORT.md + PATCH-PROMPT.md with exact selectors); the agent fixes root causes and re-runs.
5. ghost-qa compare before.json after.json proves the fix: the loop ends only at score 95–100 (A+), zero critical/major remaining, and zero new regressions.

---

🪤 The 8-Trap Deep Browser Inspection Engine *(v2.0.0)*

1. Console & Framework Runtime Trap — src/traps/console-trap.ts

• Uncaught pageerror exceptions with stack traces
• Unhandled promise rejections
• React hydration mismatches ("Text content did not match", "A tree hydrated but…")
• Duplicate-key warnings and Content-Security-Policy violations *(new in v2)*
• console.error (major) and console.warning (minor) — with dev-server noise ([vite], HMR, React DevTools banners) filtered out

2. Network & Asset Integrity Trap — src/traps/network-trap.ts

• HTTP 5xx API crashes (critical) and 4xx responses (major)
• Failed fetch/XHR requests, timed-out requests, and connection failures
• CORS-blocked requests and failed CORS preflights with remediation guidance
• Broken static assets, broken images (naturalWidth === 0), broken inline SVGs (0×0), >500KB unoptimized payloads, and missing favicons (minor)

3. Layout, Responsive Geometry & Collision Trap — src/traps/layout-trap.ts

• Horizontal overflow: scrollWidth > innerWidth, with the offending elements named (critical on mobile)
• Overlapping interactive elements via bounding-box collision math, with exact selectors + boxes *(new in v2)*
• Touch targets < 44×44px on touch viewports (WCAG 2.5.5 / Apple HIG), clipped text, and off-screen interactives *(new in v2)*
• Zero-dimension interactive elements — buttons rendered at 0×0 that no human could tap
• Missing on mobile

4. Accessibility (WCAG 2.1 AA) & Keyboard Focus Trap — src/traps/a11y-trap.ts

• Buttons and links with no accessible name (icon-only controls screen readers can't identify)
• Images missing `alt` attributes (descriptive alt, or alt="" for decorative)
• Form inputs with no associated label — a placeholder is not a label
• Real computed contrast ratios (getComputedStyle foreground vs effective background, WCAG formula) *(new in v2)*
• Heading hierarchy (missing , h1→h3 skips) and automated Tab-order verification — simulated Tab presses catch invisible or dead focus states *(new in v2)*
• Missing document and missing

5. Performance & Core Web Vitals Trap — src/traps/perf-trap.ts

• Core Web Vitals: TTFB, FCP, LCP estimation, and CLS (Cumulative Layout Shift) *(new in v2)*
• Slow page loads via Navigation Timing (DOMContentLoaded / load budgets, 2× = critical)
• Oversized resources (> 1MB single asset), unoptimized >500KB images/scripts, and excessive total payload (> 3MB)
• Main-thread jank / layout-thrashing indicators from the Long Tasks API
• Render-blocking resources, excessive DOM size (>1500 nodes) and DOM depth > 32

6. Safe Interactive & Link Integrity Trap — src/traps/links-trap.ts *(new in v2)*

• Placeholder links (href="", href="#", javascript:void(0)) and dead anchors/routes found during crawling
• Buttons inside with no `type` (they silently become submit buttons)
• Disabled/stuck interactive controls — all observational, this trap never clicks anything

7. SEO, Metadata & Social Graph Trap — src/traps/seo-trap.ts *(new in v2)*

• (missing, <10 or >60 chars), meta description, , viewport meta, canonical tag
• OpenGraph set (og:title, og:description, og:image) for link unfurls
• Duplicate `id` attributes in the live, post-hydration DOM

8. Dark / Light Theme Emulation Trap — src/traps/theme-trap.ts *(new in v2)*

• Every page also renders under colorScheme: 'dark' and 'light' emulation
• Computed contrast is re-evaluated per scheme — invisible dark-mode text (dark-on-dark) is caught automatically and tagged with the failing scheme

Plus a safety-first Interaction Runner: it fills forms with inert data (ghost-qa@example.com), opens tabs/modals/menus, and clicks ordinary buttons — but *never* destructive ones (delete, checkout, pay, logout, publish… are blocked by a tested safety gate).

---

📊 QA Health Score, Artifacts & Interactive Dashboard *(new in v2)*

Every run computes a deterministic QA Health Score (0–100) and Letter Grade (A+ … F): each trap starts at 100 and loses 25 per critical, 10 per major, 3 per minor finding; the overall score is the mean of the eight trap sub-scores (Console, Network, Layout, A11y, Performance, Links/UX, SEO/DOM, Theme Parity).

npx -y ghost-qa test http://localhost:3000 --out-dir ghost-qa-out --screenshots

🔀 Regression Diffing — ghost-qa compare / ghost_qa_compare *(new in v2)*

npx -y ghost-qa test http://localhost:3000 --json > before.json   # baseline

…agent fixes the bugs…

npx -y ghost-qa test http://localhost:3000 --json > after.json # re-audit npx -y ghost-qa compare before.json after.json # Regression & Verification Delta Report

The delta matches findings by stable fingerprint id and reports `scoreDelta`, `fixedFindings`, `newRegressions`, `remainingFindings` — so a coding agent can *prove* its fix resolved the bug without introducing regressions. verified requires score ≥ 95, zero regressions and no blocking findings left. Also available as the ghost_qa_compare MCP tool.

---

🔌 Native MCP Server

ghost-qa ships a zero