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

Quick Start

Initialize first, then run the app and Frontguard in separate terminals. This five-step walkthrough sets up deterministic visual regression testing in any web project.

Quick Start Two-Terminal Workflow and Explicit Baseline Gate
FIG 01 · TWO-TERMINAL WORKFLOW — INIT & DOCTOR · APP SERVER · EXPLICIT BASELINE CAPTURE · COMPARISON EXIT CODES

Initialize

STEP 01Generate frontguard.config.ts
Run init at the root of your git repository. Frontguard detects your framework (Next.js, Remix, Nuxt, SvelteKit, Astro, Vite) and writes a starter frontguard.config.ts and .gitignore entry.
STEP 02Review configured routes & commit
Open frontguard.config.ts and confirm the routes array matches real pages in your app. Commit frontguard.config.ts and .gitignore so your git working tree is clean before creating the frontguard-baselines orphan branch.
terminal - setup
$ npx -p @frontguard/cli frontguard init
$ git add frontguard.config.ts .gitignore && git commit -m "Add Frontguard"

Accept baselines

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

app terminal - leave running
$ npm run dev

In the Frontguard terminal, use the generated config rather than overriding its URL. Run doctor, capture initial baselines with update-baselines, and push the orphan branch if CI will compare against it:

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

Compare

Exit code 0 means comparisons passed or warned, 1 means regressions or unaccepted new screenshots, and 2 means no comparisons or a tool error.

To test how Frontguard catches a real regression, change a button color or heading margin in your app while npm run dev is running, then re-run frontguard run:

terminal - catching a regression
$ npx -p @frontguard/cli frontguard run

  ✘ /pricing @ 1440px (chromium): 1.84% changed (SSIM: 0.942, Chroma-SSIM: 0.610)
    Cluster #1: (100, 200) 120×40px -> targetSelector: [data-testid="upgrade-btn"]
  Report written to ./frontguard-report/report.html (exit code 1)

Inspect the HTML workbench

Open ./frontguard-report/report.html in a browser. To serve it over HTTP, run python3 -m http.server 8080 --directory ./frontguard-report and visit http://localhost:8080/report.html. Keep the images/ directory alongside report.html when moving or sharing the report; the HTML normally links to those PNG files.

ShortcutActionPractical Use
1 / 2 / 3 / 4Switch comparison view modeToggle Side-by-Side (1), Interactive Swipe Curtain (2), Onion Skin Opacity (3), or Diff Focus (4).
bToggle spatial cluster bounding boxesHighlights 8-connected diff clusters and displays their grounded DOM selector (targetSelector).
j / kNext / Previous routeStep rapidly through failed and warned routes without touching the mouse.
/Focus route search & status filterFilter by route path (/pricing), viewport (375px), or status (Regressions, Warnings, Passed).