Sub-pixel font drift, hydration jitter, and global whitespace dilution turn visual suites into alert fatigue.
Full-page pixel thresholds divide changed pixels by the entire canvas—drowning a broken button inside 1.3 million unchanged pixels while failing builds over 1px font hinting shifts.
Three connected phases from route discovery to verified report.
Six pipeline stages grouped into three architectural phases—running local pixel and perceptual similarity checks before optional model analysis.
Find what changed
Crawls live routes or Storybook stories, narrows to git-affected paths when configured, and renders deterministic multi-viewport snapshots with frozen clocks, seeded PRNG, and frame convergence.
Explain why it broke
Extracts 8-connected spatial diff clusters, computes local Chroma SSIM (YCbCr) and wavelet CW-SSIM to ignore sub-pixel font drift, and attributes each cluster to its highest-overlap DOM targetSelector.
Verified, not guessed
Emits deterministic exit codes (0 pass, 1 regression, 2 error), a self-contained 4-mode HTML diff workbench, and optional sandbox-verified CSS patch suggestions without ever auto-overwriting baselines.
See what Frontguard flags—and what it ignores.
Instead of averaging changed pixels across a 1440×900 canvas, Frontguard extracts 8-connected bounding boxes and scores each cluster with local Chroma SSIM and wavelet CW-SSIM.
Optional model-assisted classification for visual diffs—scores severity and suggests a CSS fix.
By default, Frontguard runs 100% offline using deterministic pixel and perceptual similarity math. When you opt in, Frontguard crops each diff cluster with its DOM selector and asks your model to classify severity and draft a candidate CSS patch—without ever silently overriding a failing exit code.
BYOK: OpenAI, Anthropic, Gemini, or custom baseUrl · Baselines are never auto-overwritten.
Run standalone, drop into Playwright, or wire into your coding agent.
The same local pixel and Chroma SSIM engine powers the standalone CLI, the Playwright test helper, and the 8-tool MCP server.
Every primitive required to run visual regression testing in production.
Built for real frontend repositories: monorepos, dynamic hydration, authenticated routes, and multi-viewport matrices.
Git-native baselines
Stores baseline PNGs in a dedicated frontguard-baselines orphan branch with SHA-256 content-addressable deduplication so your main branch stays free of binary bloat.
$ git fetch origin frontguard-baselines
manifest.json · sha256: 8f3a9c... (0 MB added to main)Frame convergence & anti-flake
Polls consecutive screenshots until layout variance settles below 0.05%, freezes Date/clock timestamps, seeds Math.random(), and aborts third-party ad or analytics trackers.
waitForStability: true · settled in 3 frames (< 0.05%)
freezeTime: '2026-01-01T00:00:00Z' · seedRandom: 42Smart rendering & spatial diffing
Scores 8-connected diff clusters with local Chroma SSIM (YCbCr) and wavelet CW-SSIM—catching color and layout shifts on small buttons while overriding 1px font hinting drift.
cluster #1 · targetSelector: "aside .sidebar-cta"
chromaSSIM: 0.614 (flagged) · cwSSIM: 0.994 (font AA ignored)Auto route & Storybook discovery
Crawls live links and parses Next.js, Remix, Astro, Nuxt, SvelteKit, and Storybook 8 index trees.
Pre-capture actions
Run click, hover, fill, scroll, and waitForSelector steps per route before taking the screenshot.
PII & input redaction
Masks password, email, and [data-sensitive] elements and scrubs [REDACTED] in DOM snapshots.
Parallel render pool
Reuses warm Playwright Chromium contexts across routes and viewports with configurable concurrency.
Production URL monitor
Scheduled frontguard monitor checks against live URLs with Slack/webhook alerts and flake tracking.
Sandbox fix verification
Injects candidate CSS patches into an isolated Playwright context and re-diffs to verify fixes.
How Frontguard compares
Local-first execution and perceptual cluster scoring compared against hosted visual regression platforms and legacy runners.
| CAPABILITY | Frontguard | Percy | Chromatic | BackstopJS | Lost Pixel |
|---|---|---|---|---|---|
| Open-source core | MIT | Not available | Not available | MIT | Sunset |
| Runs 100% locally (no cloud account) | Supported | Not available | Not available | Supported | Partial or opt-in |
| Perceptual SSIM + spatial cluster diff | Supported | Partial or opt-in | Not available | Not available | Not available |
| Frame-stability convergence check | Supported | Partial or opt-in | Partial or opt-in | Not available | Not available |
| AI classification (BYOK) | Partial or opt-in | Partial or opt-in | Not available | Not available | Not available |
| CSS suggestion verification (opt-in) | Partial or opt-in | Not available | Not available | Not available | Not available |
| Built-in WCAG + perf-budget plugins | Supported | Not available | Partial or opt-in | Not available | Not available |
| Git orphan-branch baseline storage | Supported | Not available | Not available | Not available | Not available |
Built for engineers who read the source before they trust the badge.
Visual testing only works when teams trust its signal. We separate deterministic pixel math from optional model inference and publish every benchmark script, result artifact, and boot failure.
Numbers from a real harness, not a slide.
0% FP RATEBooted chakra-ui-docs and tailwind-dashboard locally and re-ran 39 routes with zero code changes—recording 0 pixel false positives.
Executed on CLI v0.2.0 (2026-06-20) with AI disabled so every pass/fail decision reflects pure pixel and perceptual SSIM thresholds.
Every fixture repository, route list, and raw JSON output is checked into the repository for independent verification.
These fixture repositories failed headless environment boot before Frontguard ran. We publish them alongside booted repos rather than quietly dropping them from the denominator.
Stop triaging noise. Run your first diff locally.
Install the CLI, run a local comparison against your dev server, and inspect the interactive HTML diff workbench before gating pull requests.
- STEP 01 · INSTALL CLI & CHROMIUMInstalls the CLI and downloads the pinned Playwright Chromium binary.$npm install -D @frontguard/cli && npx playwright install chromium
- STEP 02 · GENERATE CONFIG & CI WORKFLOWDetects your framework and writes
frontguard.config.tswithbaseUrlin the generated config.$npx -p @frontguard/cli frontguard init --ci - STEP 03 · RUN YOUR FIRST COMPARISONStart your app in another terminal, then run Frontguard against your local server.$npx -p @frontguard/cli frontguard run
- STEP 04 · PROMOTE REVIEWED BASELINESAfter inspecting the HTML diff workbench, promote reviewed snapshots to the
frontguard-baselinesorphan branch.$npx -p @frontguard/cli frontguard update-baselines --confirm-baselines
npx -p @frontguard/cli frontguard run --ci is recommended while external Action smoke is still pending.