Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Getting started / Getting Started(1 of 37)

Frontguard

SUPPORTED PATH. The local MIT-licensed CLI runs without a Frontguard account. Hosted and marketplace surfaces remain pre-release.

Frontguard is a local-first visual regression testing toolkit for frontend teams. It renders your web pages or Storybook components in real browsers, compares pixels and perceptual similarity (SSIM, Chroma-SSIM, CW-SSIM) against reviewed baselines stored on a dedicated git orphan branch, and writes an interactive offline HTML workbench.

Frontguard 5-Stage Visual Regression Pipeline
FIG 01 · 5-STAGE PIPELINE — DISCOVER · HERMETIC RENDER · PERCEPTUAL DIFF · VISION AI & FIX · GIT CAS & REPORT

Supported path

Frontguard renders configured pages, compares screenshots against reviewed baselines, and writes console, JSON, and HTML evidence. Optional model-assisted analysis runs only when you configure a provider.

StageWhat Runs LocallyOutput / Artifact
1. DiscoverReads explicit routes from frontguard.config.ts, crawls your live app sitemap, or queries Storybook /index.json.Normalized route × viewport × browser matrix
2. RenderLaunches a bounded Playwright worker pool with optional anti-flake controls (waitForStability, freezeTime, seedRandom, blockUrls, redactSensitive).Deterministic PNG captures + DOM bounding boxes
3. CompareRuns Pixelmatch with anti-aliasing filters plus Luminance SSIM, Chroma-SSIM (YCbCr), and Wavelet CW-SSIM.8-connected spatial diff clusters mapped to DOM selectors (cluster.targetSelector)
4. Analyze (Optional)If BYOK AI is configured (OpenAI, Anthropic, Gemini, or custom baseUrl), classifies diffs and optionally tests candidate CSS patches in a sandbox.Advisory classification, confidence score, and verified/unverified patch status
5. Report & StoreStores approved baselines on the frontguard-baselines git orphan branch and writes local inspection artifacts.Console summary, frontguard-report/report.html (4-mode workbench), and JSON output

Choose your workflow

WORKFLOW 01 · FULL-APP CLI
@frontguard/cli

Crawl or list routes in frontguard.config.ts, capture multi-viewport baselines onto the frontguard-baselines git orphan branch, and gate PRs in CI.

WORKFLOW 02 · IN-TEST ASSERTIONS
@frontguard/playwright

Drop visualTest(page, name, options) directly inside your existing Playwright .spec.ts tests after complex login flows, form fills, or modal interactions.

WORKFLOW 03 · CODING AGENTS
@frontguard/mcp

Connect Claude Code, Cursor, or Windsurf to your local frontguard-report/report.json over stdio JSON-RPC to inspect diff clusters and DOM selectors.

Quick start

Run these four steps in any Node.js 22+ git repository to initialize Frontguard, capture reviewed baselines, and run your first comparison:

terminal - setup
$ npx -p @frontguard/cli frontguard init --ci

In a separate app terminal, use your project's dev-server command and leave it running. The command below is one example; wait for the baseUrl generated in frontguard.config.ts to respond.

app terminal - leave running
$ npm run dev

Then use a Frontguard terminal; these commands read baseUrl from the generated config.

Frontguard terminal
$ npx -p @frontguard/cli frontguard doctor
$ npx -p @frontguard/cli frontguard update-baselines --confirm-baselines
$ git push origin frontguard-baselines
$ npx -p @frontguard/cli frontguard run

Baseline contract

Ordinary runs never accept CLI screenshots. Review captures first, then use frontguard update-baselines --confirm-baselines explicitly. Unaccepted new pages and regressions exit non-zero.

Interactive 4-Mode HTML Visual Diff Workbench
FIG 02 · INTERACTIVE HTML WORKBENCH — SIDE-BY-SIDE, SWIPE CURTAIN, ONION SKIN, DIFF FOCUS & SPATIAL CLUSTER INSPECTOR
Exit CodeMeaningWhen It Happens
0Passed / WarningAll route comparisons matched within threshold (or produced non-blocking warnings).
1Regression / Unaccepted New PageOne or more routes exceeded threshold or had no accepted baseline on frontguard-baselines.
2Tool / Configuration ErrorTarget server unreachable, invalid config, missing browser binary, or zero routes discovered.
← PREVIOUS
Overview
NEXT →