by avivgerz-hue
Autonomous headless Playwright QA agent & MCP server. Crawl localhost or staging URLs across Desktop, Tablet & Mobile to catch broken flows, console errors & layout bugs.
Available after the catalog security scan passes.
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM lists this project for discovery and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
# Add to your Claude Code skills
git clone https://github.com/avivgerz-hue/ghost-qaGuides for using ai agents skills like ghost-qa.
Coding agents write code blind. Code that type-checks can still ship with React hydration mismatches, uncaught exceptions, 500ing APIs, dead links, invisible dark-mode text, 30px tap targets, and mobile layouts that scroll sideways. The browser is the source of truth — never your mental model of the DOM.
The Rule: Before reporting ANY task that touches frontend code as complete, you MUST execute all five phases below, in order, and finish with a verified delta: QA Health Score 95–100 (Grade A+ band), zero critical/major findings, zero new regressions.
Unit tests, type-checking, linting and code review do not satisfy this rule. They cannot see hydration, layout, network, contrast or focus failures.
Not a substitute for: your unit/E2E suites, a full manual WCAG audit (the a11y trap covers machine-checkable WCAG 2.1 AA failures), load testing, or exploratory QA.
Every audit crawls each route on Desktop 1440×900, Tablet 768×1024 and Mobile 375×812, under light + dark colour schemes:
| # | Trap | What it catches |
|---|---|---|
| 1 | Console & Framework Runtime | pageerror, console.error, unhandled rejections, React/Next.js hydration mismatches, duplicate-key warnings, CSP violations |
| 2 | Network & Asset Integrity | 4xx/5xx, timed-out/aborted requests, failed CORS preflights, broken images (naturalWidth === 0), broken inline SVGs (0×0), >500KB unoptimized payloads |
| 3 | Layout, Responsive Geometry & Collision | Horizontal overflow, overlapping interactive elements (bounding-box collision math), <44×44px touch targets, clipped text, off-screen interactives |
| 4 | Accessibility (WCAG 2.1 AA) & Keyboard Focus | Missing accessible names/labels/alt, heading hierarchy breaks, real computed contrast ratios, automated Tab-order verification (invisible/dead focus) |
| 5 | Performance & Core Web Vitals | TTFB, FCP, LCP, CLS, DOM bloat (>1500 nodes), DOM depth (>32), render-blocking scripts, long tasks |
| 6 | Safe Interactive & Link Integrity | Placeholder hrefs ("", #, javascript:void(0)), dead anchors/routes, in-form buttons without type, stuck disabled controls |
| 7 | SEO, Metadata & Social Graph | Title length, meta description, <html lang>, viewport meta, canonical, OpenGraph set, duplicate ids |
| 8 | Dark / Light Theme Emulation | Contrast/visibility recomputed under colorScheme: light and dark — catches invisible dark-mode text |
Scoring is deterministic: each trap starts at 100, −25 per critical, −10 per major, −3 per minor. The QA Health Score is the mean of the 8 trap scores, graded A+ (97+) … F (<60).
ghost_qa_doctor)ghost_qa_doctor MCP tool, or run npx -y ghost-qa doctor.npx playwright install chromium (one-time), then re-run doctor. Never skip to Phase 2 on a red doctor — a failed launch is not a passing audit.npm run dev) or plan to use --server-cmd "npm run dev" / let the audit spawn it.ghost_qa_audit_url)Run the baseline BEFORE changing code (or before your fix, when debugging):
ghost_qa_audit_url with the app URL. Save the full returned report JSON as before.json.npx -y ghost-qa test <local-url> --out-dir ghost-qa-out → writes report.json (copy to before.json), GHOST-QA-REPORT.md, PATCH-PROMPT.md, and the interactive report.html dashboard. Add --screenshots for embedded route screenshots; --server-cmd "npm run dev" if the server isn't running.Record the baseline: QA Health Score, grade, per-trap scores, and every finding's #id. Common local URLs: Next.js/CRA http://localhost:3000, Vite http://localhost:5173, Astro http://localhost:4321, Angular http://localhost:4200. Never guess silently — state the URL you verified.
For every critical/major finding, trace it back to the exact source component before editing:
#id, [data-testid=…], or a CSS path, plus the live bounding box. Search the codebase for that id/testid/class or the element's visible text to find the React/Next.js/Vue/Svelte component that renders it.window at render, invalid nesting like <p> in <p>).theme-contrast finding names the scheme that fails — find the hard-coded colour in that component and replace it with the theme token.Write the mapping down (finding #id → file → root cause) before Phase 4. If you cannot map a finding, say so — do not guess-fix.
Fix root causes, one finding at a time, in severity order (critical → major → minor):
suppressHydrationWarning to silence it.min-width: 0 on flex/grid children, max-width: 100%, no 100vw + scrollbar overflow, reserve image space with width/height or aspect-ratio (also fixes CLS).aria-label on icon controls, <label for> (or wrapping label) per input, alt on images (alt="" only if decorative), one <h1>, no heading level skips, visible :focus-visible rings — never outline: none without a replacement.dark: variants driven by prefers-color-scheme or the app theme — never hard-coded hex that only works in one scheme.<button type="button">; dead anchors get real targets; in-form buttons get explicit type.Anti-cheating rules (absolute): never delete failing UI, never loosen the checker, never hide elements from the traps, never stub network responses. Fixing the checker instead of the bug is a failed task.
Use these in Phase 4. Each playbook starts from what the report hands you — selector + bounding box + viewport + trap — and ends at the component you must edit. Never guess: reproduce with the selector first (document.querySelector('<selector>') in DevTools), then find its source component by searching for the id / data-testid / class / visible text.
scrollWidth > innerWidth) · Trap 3 (Layout)Signature: horizontal-overflow on mobile/tablet; the finding names the overflowing elements and their boxes (right edge ≫ 375 or 768).
x + width exceeds the viewport width is your culprit — open its component.w-[500px], width: 500px), 100vw on an element inside a padded/scrollable ancestor (adds the scrollbar width), a flex/grid child that refuses to shrink, negative margins, or an absolutely-positioned decorative blob.min-w-0 to the flex/grid child, max-w-full on the wide element, and replace w-screen/100vw with w-full. For text that must not push layout: truncate or break-words.min-width: 0 on the flex item, max-width: 100%, box-sizing: border-box, and overflow-x: clip on the page shell only as a last-resort guardrail — masking with overflow-x: hidden on body without fixing the child is cheating: the trap also flags the still-overflowing element's box.Signature: element-collision naming both selectors and the first element's bounding box; the two boxes intersect by > 4px in both axes.
bottom-24 instead of bottom-4 over a footer CTA), add scroll-margin to anchored sections (scroll-mt-24), place the badge inside flow (relative parent + contained offsets that don't cross the neighbouring control), or assign explicit grid areas so siblings can't share a cell. If one element is supposed to overlay (modal, tooltip), the interactive element beneath must not remain clickable — pointer-events-none on the covered control or trap focus inside the modal.< 44×44px without breaking desktop density · Trap 3 (Layout)Signature: small-touch-target with the exact box (e.g. 38×20px) on mobile/tablet. Desktop has no such requirement — dense desktop UIs are fine, so fix responsively, never globally.
md: where density is welcome:
class="inline-flex items-center justify-center min-h-11 min-w-11 md:min-h-9 md:min-w-9" — 44px (11 × 4px) on mobile, 36px on desktop. Keep the icon itself small (h-5 w-5); it's the target that must be 44px.class="inline-flex items-center min-h-11 md:min-h-9 px-2".min-height: 44px; min-width: 44px; inside @media (pointer: coarse), or expand with a pseudo-element hit-slop (position: relative + ::after { content:""; position:absolute; inset:-10px; }) when visual spacing is locked by design.zoom, or making desktop airy to satisfy a mobile rule. Verify: trap silent at 375×812 and 768×1024, desktop rendering unchanged.Signature: theme-contrast tagged colorScheme: dark (or light), with selector, ratio (e.g. 1.3:1, needs 4.5:1) and box. The text is perfectly visible in your theme — that's the trap working as intended.
prefers-color-scheme: dark, then inspect the selector. You'll find a hard-coded colour: color: #111, text-neutral-900, an inline style, or an SVG fill that never flips — sitting on a background that does flip.text-neutral-900 dark:text-neutral-100, bg-white dark:bg-neutral-900, border-neutral-200 dark:border-neutral-800. If you find yourself writing a bare text-black/bg-white inside a themed surface, that's the bug.:root { --ink: #111827; --surface: #ffffff; } and @media (prefers-color-scheme: dark) { :root { --ink: #f3f4f6; --surface: #111827; } } (or under your [data-theme="dark"] selector), then consume color: var(--ink); background: var(--surface);. Check images/SVGs too: fill: currentColor inherits the fixed token.text.primary, bg.paper) instead of palette literals.Signature: hydration-mismatch (critical) with the first stack frames. Server HTML and first client render disagree — React discards the server DOM and re-renders, causing flicker and, in Next.js, hard errors.
Date.now() / new Date() / Math.random() / locale-formatted dates during render; reading window/localStorage/cookies during render; user-agent or viewport-dependent markup; invalid HTML nesting the browser "fixes" differently from React (<p> inside <p>, <div> inside <p>, <table> without <tbody>, nested <button>/<a>); extensions injecting attributes (suppress only those, on the exact element, with a comment).useEffect + state, or lazy-init from an effect — never during the server render. Dates: format on the server and pass as props, or render a stable placeholder that fills in after mount.next/dynamic with ssr: false, or a mounted-gate (const [mounted, setMounted] = useState(false); useEffect(() => setMounted(true), [])) — keep the gate as small as possible so the rest of the page still SSRs.<div>/<section> instead of <p> wrappers, real <tbody>, one interactive element per control.suppressHydrationWarning to silence the trap (except the single-element browser-extension case above), deleting the dynamic content, or forcing ssr: false on whole pages to make the error disappear.console-error friends in the delta.ghost_qa_compare)after.json.ghost_qa_compare with { before, after }, or npx -y ghost-qa compare before.json after.json.scoreDelta, fixedFindings, newRegressions, remainingFindings.verified: true). Otherwise loop back to Phase 3 with the delta as your new worklist.#id survives 5 loops, stop and report honestly what you tried — never declare success on a red delta.✅ Done. Verified in a real browser with ghost-qa:
ghost_qa_audit_urlon<url>Stack: Desktop 1440×900 + Tablet 768×1024 + Mobile 375×812, light + dark, 8 traps QA Health Score:<before>→<after>(Grade<grade>) · Delta:<n>fixed, 0 new regressions Routes crawled:<n>· Interactions tested:<n>· Artifacts:report.json,GHOST-QA-REPORT.md,PATCH-PROMPT.md,report.html
| Symptom | Fix |
|---|---|
| "could not launch Chromium" | npx playwright install chromium (one-time), then npx -y ghost-qa doctor |
| Navigation failures on every route | The dev server isn't running (or wrong port) — start it, or use --server-cmd "npm run dev" |
| Score stuck below 95 | Work the delta's remaining findings by severity; re-check Phase 3 mapping before editing |
| A trap flags a healthy page | File an issue with report.json attached — false positives are the most valuable bug reports |
All commands use the published npm package (
npx -y ghost-qa …). If npm is unavailable,npx -y github:avivgerz-hue/ghost-qa …runs the identical CLI straight from GitHub.
See how ghost-qa compares with popular alternatives.
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.
One command each — star all three and keep the whole suite free & maintained:
npx -y unslop-mcp@latest init)npx -y @vibefoundry/vibe-shield@latest scan .)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:3000works identically — every command in this README accepts either package source (ghost-qa mcp,ghost-qa init, …).
# 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.
┌──────────────────────────────────────────┐
│ 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
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.GHOST-QA-REPORT.md + PATCH-PROMPT.md with exact selectors); the agent fixes root causes and re-runs.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.src/traps/console-trap.tspageerror exceptions with stack tracesconsole.error (major) and console.warning (minor) — with dev-server noise ([vite], HMR, React DevTools banners) filtered outsrc/traps/network-trap.ts5xx API crashes (critical) and 4xx responses (major)fetch/XHR requests, timed-out requests, and connection failuresnaturalWidth === 0), broken inline SVGs (0×0), >500KB unoptimized payloads, and missing favicons (minor)src/traps/layout-trap.tsscrollWidth > innerWidth, with the offending elements named (critical on mobile)<meta name="viewport"> on mobilesrc/traps/a11y-trap.tsalt attributes (descriptive alt, or alt="" for decorative)getComputedStyle foreground vs effective background, WCAG formula) (new in v2)<h1>, h1→h3 skips) and automated Tab-order verification — simulated Tab presses catch invisible or dead focus states (new in v2)<title> and missing <html lang>src/traps/perf-trap.ts<head> resources, excessive DOM size (>1500 nodes) and DOM depth > 32src/traps/links-trap.ts (new in v2)href="", href="#", javascript:void(0)) and dead anchors/routes found during crawling<form> with no type (they silently become submit buttons)src/traps/seo-trap.ts (new in v2)<title> (missing, <10 or >60 chars), meta description, <html lang>, viewport meta, canonical tagog:title, og:description, og:image) for link unfurlsid attributes in the live, post-hydration DOMsrc/traps/theme-trap.ts (new in v2)colorScheme: 'dark' and 'light' emulationPlus 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 b
ghost-qa is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by avivgerz-hue. Autonomous headless Playwright QA agent & MCP server. Crawl localhost or staging URLs across Desktop, Tablet & Mobile to catch broken flows, console errors & layout bugs. It has 50 GitHub stars.
ghost-qa's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/avivgerz-hue/ghost-qa" and add it to your Claude Code skills directory (see the Installation section above). ghost-qa ships a SKILL.md manifest, so compatible agents can discover and load it automatically.
ghost-qa is primarily written in TypeScript. It is open-source under avivgerz-hue on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh ghost-qa against similar tools.
No comments yet. Be the first to share your thoughts!