The Frontguard CLI — a standalone tool for visual regression testing of any web application.

CLI Overview

The frontguard CLI is the primary way to run visual regression tests. It works with any web application accessible via a URL — no framework-specific setup required.

Architecture

src/
├── cli/              # CLI entry point (Commander.js)
├── core/             # Pipeline orchestrator, types, config, plugin system
├── discovery/        # Route discovery (crawler + filesystem)
├── render/           # Playwright rendering engine
├── diff/             # Pixel diff + AI vision analysis
├── storage/          # Git orphan branch baselines
├── report/           # Console, JSON, HTML, GitHub PR reporters
├── plugins/          # Figma, perf budgets, monitoring
└── utils/            # Redaction, logging, retry

Pipeline

The CLI orchestrates a multi-stage pipeline:

discover → filter → render → diff → analyze → report

Each stage is independent with error boundaries. If a single page fails to render, the rest of the pipeline continues unaffected.

Key Capabilities

Feature	Description
Route Discovery	Auto-crawls your app or reads from config/filesystem
Multi-Browser	Chromium, Firefox, WebKit via Playwright
Multi-Viewport	Test at mobile, tablet, and desktop widths
Smart Rendering	Dependency graph filters to only changed pages
Pixel Diff	`pixelmatch` with SSIM perceptual fallback
AI Analysis	GPT-4V / Claude explains regressions and suggests fixes
Git-Native Baselines	Stored in an orphan branch, zero main branch bloat
Reports	Console, JSON, HTML, and GitHub PR comments
Plugin System	6 lifecycle hooks for extensibility

Sample Output

 frontguard v0.1.0

 🔍 Discovering routes... found 47 routes
 📊 12/47 routes affected by changed files
 🖥  Rendering 12 routes × 3 viewports

 ───────────────────────────────────────────
  RESULTS                        12 routes
 ───────────────────────────────────────────
  ✓ /                375  768  1440   PASS
  ✓ /pricing         375  768  1440   PASS
  ⚠ /checkout        375  768  1440   WARNING
  ✘ /dashboard       375  768  1440   REGRESSION
  ★ /settings        375  768  1440   NEW
 ───────────────────────────────────────────

  ✘ /dashboard @ 375px
    AI: "Sidebar overlaps main content on mobile.
         flex-direction change in Dashboard.module.css:28"
    Severity: 🔴 Critical (confidence: 94%)

  1 regression · 1 warning · 9 passed · 1 new

Statuses: ✓ PASS (within threshold), ⚠ WARNING (minor diff), ✘ REGRESSION (exceeds threshold), ★ NEW (no baseline yet).

Next Steps

Commands — All CLI commands and flags
Configuration — Full frontguard.config.ts reference

CLI Overview

CLI Overview

Architecture

Pipeline

Key Capabilities

Sample Output

Next Steps

On this page