frontend-qa

Opens your app in a real browser, observes what actually happens, and writes a structured, evidence-tagged report. No LLM in the loop. Nothing leaves your machine.

Get Started Read the Docs

npx frontend-qa scan --url http://localhost:5173

The problem

Console errors, failed API calls, missing alt text, oversized bundles, and accessibility regressions routinely ship to production because nothing routinely looks. Manually opening dev tools on every route doesn’t scale; hosted synthetic-monitoring services are built for production uptime, not a local dev loop, and mean sending your app’s traffic to someone else’s cloud.

The solution

frontend-qa drives a real Chromium instance with Playwright against a URL you point it at — your local dev server or a deployed environment — and records what actually happens: console errors, network failures, a screenshot, navigation timing, and (opt-in) accessibility, performance, and visual-regression checks. Everything is normalized into one JSON report, and every issue is tagged with how it was found — Measured, Observed, StaticAnalysis, Heuristic, Inferred, or Unavailable — so you never mistake a guess for a fact. It runs entirely on your machine; nothing is uploaded, and there is no LLM anywhere in the scan path.

How it works

You run one command — frontend-qa scan — against a URL, or nothing at all if a dev server for a detected Vite/Next project is already running (or launchable).
A real browser opens the app. Playwright navigates each configured route and waits for it to go quiet (no new console output or network activity), not a fixed timer.
Collectors observe. Console, network, screenshot, and timing are always on; accessibility (--a11y), performance (--perf), and visual diffing (--visual) are opt-in.
Results normalize into Issue[]. Every collector’s raw output maps to the same Issue shape — severity, evidence type, source location where available.
A report is written locally to .local/frontend-qa/runs/<runId>/report.json. The CLI exits non-zero if anything at or above your --fail-on severity was found.

Read the full breakdown in How It Works.

Core capabilities

Runtime scanning

Console errors, uncaught exceptions, failed and HTTP-error network requests, a screenshot, and navigation timing — on every scan, no flags required.

Opt-in QA engines

Accessibility checks via axe-core (--a11y), a Lighthouse performance audit (--perf), and pixel-diff visual regression against a stored baseline (--visual).

Static analysis

frontend-qa static parses your source with ts-morph — missing alt text, unsafe dangerouslySetInnerHTML, dead exports, unresolved imports, TODO/FIXME — no browser required.

Bundle analysis

frontend-qa bundle walks a build output directory and flags oversized JS/CSS chunks — no browser required.

MCP server

frontend-qa-mcp exposes scan, report, issues, console errors, and screenshots as five stdio tools an AI coding assistant can call directly.

Redacted by construction

Authorization/Cookie/API-key headers are redacted at the point of capture, before anything reaches disk — not as a later filtering pass.

Quick start

# in the project you want to scan
npx frontend-qa scan --url http://localhost:5173

[frontend-qa] project: react (vite=true)
[frontend-qa] scanning http://localhost:5173 routes=["/"]

[frontend-qa] report: .local/frontend-qa/runs/01J.../report.json
[frontend-qa] issues: 4 (critical=1 high=2 medium=1 low=0 info=0)
  - [critical] browser.console: Uncaught exception on click
  - [high] browser.console: console.error on mount
  - [high] browser.network: GET /api/data → 500
  - [medium] browser.network: img src 404

Full walkthrough, including auto-detecting a dev server: Quick Start.

Architecture

CLI (frontend-qa) ──┐
MCP server ──────────┼──▶ core (config, project detection, normalizer, report writer)
                     │        └─▶ shared (Issue/Report schemas, redaction)
                     └──▶ browser (Playwright collectors: console, network,
                                    screenshot, timing, a11y, perf, visual)

Five packages, one dependency direction — shared → core → browser → {cli, mcp-server} — so a new collector never requires touching the orchestrator. Full breakdown: Architecture.

Why a local tool

No cloud dependency. Nothing about a scan requires network access beyond the URL you’re testing.
Deterministic. Same code, same URL, same viewport → the same normalized report, modulo timings.
Evidence over inference. Every issue says how it was found, so a “possible N+1” heuristic never reads the same as a measured 500 response.
AI-ready without being AI-dependent. The MCP server hands the same report to an assistant that the CLI prints to your terminal — the reasoning layer is optional, the instrumentation isn’t.

Read the documentation →