Configuration
Configuration lives in frontguard.config.ts at your project root. Threshold values are fractions from 0 to 1 (for example, 0.01 = 1% changed pixels).
Minimal configuration
Below is a production-ready frontguard.config.ts combining explicit routes, pre-capture UI actions, multi-viewport rendering, deterministic anti-flake gates, and optional BYOK AI:
Configuration reference
| Property | Type | Default | Description |
|---|---|---|---|
version | 1 | 1 | Config schema version (required). |
baseUrl | string | 'http://localhost:3000' | Root URL of the application under test. |
routes | Array<string | RouteConfig> | undefined | Explicit route paths or route objects with custom actions, viewports, and threshold overrides. |
discover | { startUrl, maxDepth, exclude } | undefined | Zero-config route crawler settings when routes is omitted. |
storybook | { url, stories?, exclude? } | undefined | Discover and render stories from a running Storybook 7/8 server. |
viewports | number[] | [375, 768, 1440] | Viewport widths in CSS pixels. |
browsers | Array<'chromium'|'firefox'|'webkit'> | ['chromium'] | Playwright browser engines to test. |
threshold | number (0-1) | 0.1 | Whole-image changed-pixel ratio. 0.1 means 10% of pixels. The pixelmatch color distance is a separate hardcoded 0.1 (1 is black versus white). The Playwright per-pixel default is 0.2. A 16×16 window with more than 64 differing pixels fails even when the edit is a few percent of the image. |
ssimThreshold | number (0-1) | 0.98 | SSIM fallback cutoff when ssimFallback is enabled. |
colorScheme | 'light' | 'dark' | undefined | Emulate prefers-color-scheme during capture. Uses the same baseline file as the default scheme unless named capture modes are configured, and warns when the stored scheme differs. The warning does not change the exit code. |
modes | Record<string, CaptureModeConfig> | undefined | Named capture mode bundles (colorScheme, reducedMotion, forcedColors, contrast, locale, timezoneId) keyed onto baselines/<route>/<viewport>/<mode>/<browser>.png. |
waitForStability | boolean | { maxAttempts?, intervalMs?, pixelThreshold?, maxUnstableRatio? } | false | Wait for consecutive animation frames to converge before taking the screenshot (defaults: maxAttempts 4, intervalMs 120, maxUnstableRatio 0.0005). |
redactSensitive | boolean | string[] | false | Mask password, credit-card (autocomplete^="cc-"), one-time-code, and [data-frontguard-redact] / [data-sensitive] elements (plus any custom selectors) and scrub DOM snapshots. |
freezeTime | boolean | number | string | undefined | Freeze page.clock and Date.now() to a fixed epoch ms or ISO 8601 date string. |
seedRandom | boolean | number | undefined | Override Math.random() with a seeded Mulberry32 PRNG. |
blockUrls | string[] | [] | Abort third-party URLs matching glob/substring patterns before capture. |
ignore | Array<{ selector?: string, rect?: Rect, description?: string, since?: string }> | [] | Hide or mask volatile DOM elements or pixel rects (e.g., live tickers, video players) during capture. |
ai | { provider, model?, baseUrl?, maxCalls?, maxOutputTokens?, timeoutMs? } | undefined | Optional BYOK vision triage (openai, anthropic, gemini). maxCalls caps model calls per run; skipped calls are reported in aiUsage and leave pixel results unchanged. |
plugins | FrontguardPlugin[] | [] | Registered 9-hook lifecycle plugins (accessibility, performance budgets, script inventory, custom). |
outputDir | string | './frontguard-report' | Directory for HTML and images. JSON output is written to stdout; redirect it to save a file. |
Practical recipes
Recipe 1: Interacting with Modals, Tabs & Auth Forms Before Capture
Each entry in routes can specify an actions array executed sequentially by Playwright before stability checks and screenshot capture:
Recipe 2: Eliminating Third-Party & Time-Based Flake
Combine freezeTime, seedRandom, blockUrls, and ignore selectors so charts, relative timestamps ("2 minutes ago"), and analytics banners render identically on every run:
Optional controls
Optional controls include colorScheme (light or dark), waitForStability for multi-frame layout convergence, redactSensitive for masking password/email/token fields and scrubbing DOM snapshots, freezeTime (boolean, epoch ms number, or ISO 8601 date string), seedRandom (boolean or numeric PRNG seed), blockUrls (URL glob or substring patterns to abort before rendering), per-route actions (click, hover, fill, press, waitForSelector, wait), masks, region-scoped Chroma-SSIM (YCbCr) and CW-SSIM cluster similarity with spatial cluster.targetSelector DOM attribution, configurable multi-render consensus, telemetry opt-in, and multi-provider BYOK analysis (openai, anthropic, gemini, or custom baseUrl / FRONTGUARD_OPENAI_BASE_URL). Verify an option against the installed package version before adding it.
