Skip to main content
DETERMINISTIC VISUAL REGRESSION TESTING · MIT OPEN SOURCE

Catch the regression, not the noise.

Deterministic visual regression testing for engineers and AI coding agents. Run local pixel and perceptual similarity checks in CI without mandatory cloud accounts.

$ npm install @frontguard/cli
Read the docs →
/dashboard·Desktop · 1440×900
CTA 36px
BASELINE
✘ REGRESSION · 1.84%
IGNORED · 1px font hinting (CW-SSIM 0.994)
CLUSTER #1 · 148×164px · aside .sidebar-cta
SPLIT52%
Chroma SSIM: 0.614·Settled: 3 frames
39 / 43
Routes verified cleanly

route rechecks completed in the published local harness

2 / 5
Benchmark repos booted

fixture repositories booted successfully

0 AI calls
Fully deterministic unless you opt in

classifier accuracy was not measured in that run

1 HOST
Runs on a single machine

macOS only; cross-OS equivalence remains unproven

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.

HOW FRONTGUARD WORKS

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.

PHASE 01 · CAPTUREPhase 1 →

Find what changed

01Discover
02Filter
03Render

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.

›waitForStability + freezeTime + seedRandom
›redactSensitive masks PII before disk write
PHASE 02 · COMPAREPhase 2 →

Explain why it broke

04Diff
05Analyze

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.

›Connected-component cluster bounding boxes
›Optional BYOK severity & root-cause triage
PHASE 03 · REPORTPhase 3 · Final

Verified, not guessed

06Report

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.

›frontguard-baselines git orphan branch
›Candidate CSS re-rendered in Playwright sandbox

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.

CONNECTED-COMPONENT CLUSTER OVERLAY2 REGIONS SCORED
✘ FLAGGED · CLUSTER #1 (aside .sidebar-cta)Chroma SSIM (YCbCr): 0.614

Primary sidebar CTA collapsed from 36px to 0px height inside bounding box 148×164px @ (48, 224).

✓ IGNORED NOISE · REGION #2 (h1.page-title)CW-SSIM: 0.994

1px sub-pixel font anti-aliasing shift along glyph stems. Complex wavelet phase consistency exceeds 0.985, so Frontguard suppresses the false alarm.

Why this matters: Frontguard flagged the collapsed aside .sidebar-cta button (Chroma SSIM 0.614) while automatically suppressing 1px sub-pixel glyph hinting on the header (CW-SSIM 0.994).

🔒 redactSensitive: 2 inputs masked
OPTIONAL LAYER · OFF BY DEFAULT

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.

./frontguard-report/report.jsondeterministic exitCode: 1
{
"route": "/dashboard",
"classification": "regression",
"severity": "critical",
"confidence": 0.92,
"explanation": "Sidebar CTA button collapsed from 36px to 0px height",
"suggestion": "aside .sidebar-cta { min-height: 36px; display: flex; }",
"exitCode": 1
}

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.

@frontguard/cli

Auto-discovers routes from your live server or filesystem, converges animation frames, and stores reviewed baselines in the frontguard-baselines git orphan branch.

@frontguard/cli
# Terminal 1: keep your app server running
npm run dev

# Terminal 2: initialize config & run visual check
npx -p @frontguard/cli frontguard init --ci
npx -p @frontguard/cli frontguard run
KEY CAPABILITIES

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 STORAGE

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)
DETERMINISTIC CAPTURE

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: 42
PERCEPTUAL ENGINE

Smart 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.

5 Built-in plugins:FigmaPerf BudgetsAccessibility3rd-Party ScriptsMonitor
Build your own plugin →
9 LIFECYCLE HOOKSsetup · beforeDiscover · afterDiscover · beforeRender · afterRender · afterCompare · afterRun · onError · teardown

How Frontguard compares

Local-first execution and perceptual cluster scoring compared against hosted visual regression platforms and legacy runners.

See all 15 capabilities across 6 tools →

Experimental CSS suggestion verification, clearly labeled.

Candidate CSS patches are opt-in (◐) and never auto-applied to source files.
CAPABILITYFrontguardPercyChromaticBackstopJSLost Pixel
Open-source coreMITNot availableNot availableMITSunset
Runs 100% locally (no cloud account)SupportedNot availableNot availableSupportedPartial or opt-in
Perceptual SSIM + spatial cluster diffSupportedPartial or opt-inNot availableNot availableNot available
Frame-stability convergence checkSupportedPartial or opt-inPartial or opt-inNot availableNot available
AI classification (BYOK)Partial or opt-inPartial or opt-inNot availableNot availableNot available
CSS suggestion verification (opt-in)Partial or opt-inNot availableNot availableNot availableNot available
Built-in WCAG + perf-budget pluginsSupportedNot availablePartial or opt-inNot availableNot available
Git orphan-branch baseline storageSupportedNot availableNot availableNot availableNot available
✓ supported · ◐ partial / paid add-on / opt-in · ✕ not available
Based on public documentation and pricing as of March 2026 · Lost Pixel archived February 2026
OPEN-SOURCE PROOF & TRUST

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 RATE
1. Zero-change recheck gate

Booted chakra-ui-docs and tailwind-dashboard locally and re-ran 39 routes with zero code changes—recording 0 pixel false positives.

2. Deterministic offline baseline

Executed on CLI v0.2.0 (2026-06-20) with AI disabled so every pass/fail decision reflects pure pixel and perceptual SSIM thresholds.

3. Reproducible open-source script

Every fixture repository, route list, and raw JSON output is checked into the repository for independent verification.

UNEDITED DENOMINATOR · 3 REPOS SKIPPED ON BOOT

These fixture repositories failed headless environment boot before Frontguard ran. We publish them alongside booted repos rather than quietly dropping them from the denominator.

taxonomyNext.js app
next 13.3.2-canary dev server failed to load config under Node 22; contentlayer dev succeeded but next dev crashed
medusa-storefronte-commerce storefront
requires a running Medusa backend and NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY — not provisioned in this harness run
nextra-docsdocs site
monorepo's root `pnpm dev` builds every package but does not bind a dev server on :3000 within the 120 s timeout

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.

  1. STEP 01 · INSTALL CLI & CHROMIUM
    Installs the CLI and downloads the pinned Playwright Chromium binary.
    $npm install -D @frontguard/cli && npx playwright install chromium
  2. STEP 02 · GENERATE CONFIG & CI WORKFLOW
    Detects your framework and writes frontguard.config.ts with baseUrl in the generated config.
    $npx -p @frontguard/cli frontguard init --ci
  3. STEP 03 · RUN YOUR FIRST COMPARISON
    Start your app in another terminal, then run Frontguard against your local server.
    $npx -p @frontguard/cli frontguard run
  4. STEP 04 · PROMOTE REVIEWED BASELINES
    After inspecting the HTML diff workbench, promote reviewed snapshots to the frontguard-baselines orphan branch.
    $npx -p @frontguard/cli frontguard update-baselines --confirm-baselines
CI note: Direct npx -p @frontguard/cli frontguard run --ci is recommended while external Action smoke is still pending.