Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Reference / Configuration(6 of 37)

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:

frontguard.config.ts
export default {
  version: 1,
  baseUrl: 'http://localhost:3000',
  routes: [
    '/',
    {
      path: '/pricing',
      threshold: 0.005, // Stricter 0.5% threshold on pricing page
      actions: [
        { type: 'waitForSelector', selector: '[data-ready]' },
        { type: 'click', selector: '[data-billing="annual"]' },
      ],
    },
  ],
  viewports: [375, 768, 1440],
  browsers: ['chromium'],
  colorScheme: 'dark',
  waitForStability: true,
  redactSensitive: true,
  freezeTime: '2026-01-01T00:00:00Z',
  seedRandom: 42,
  blockUrls: ['*google-analytics.com*', '*intercom.io*'],
  threshold: 0.01,
  ai: {
    provider: 'gemini', // default model 'gemini-3.5-flash-lite'
    // Or provider: 'openai' (default 'gpt-6-luna') with optional baseUrl for OpenRouter / Ollama / vLLM,
    // or provider: 'anthropic' (default 'claude-sonnet-5-5')
  },
  ignore: [
    { selector: '.live-visitor-counter' },
  ],
  smartRender: true,
  workers: 4,
  pageTimeout: 30000,
  maxHeight: 5000,
  outputDir: './frontguard-report',
}

Configuration reference

PropertyTypeDefaultDescription
version11Config schema version (required).
baseUrlstring'http://localhost:3000'Root URL of the application under test.
routesArray<string | RouteConfig>undefinedExplicit route paths or route objects with custom actions, viewports, and threshold overrides.
discover{ startUrl, maxDepth, exclude }undefinedZero-config route crawler settings when routes is omitted.
storybook{ url, stories?, exclude? }undefinedDiscover and render stories from a running Storybook 7/8 server.
viewportsnumber[][375, 768, 1440]Viewport widths in CSS pixels.
browsersArray<'chromium'|'firefox'|'webkit'>['chromium']Playwright browser engines to test.
thresholdnumber (0-1)0.1Whole-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.
ssimThresholdnumber (0-1)0.98SSIM fallback cutoff when ssimFallback is enabled.
colorScheme'light' | 'dark'undefinedEmulate 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.
modesRecord<string, CaptureModeConfig>undefinedNamed capture mode bundles (colorScheme, reducedMotion, forcedColors, contrast, locale, timezoneId) keyed onto baselines/<route>/<viewport>/<mode>/<browser>.png.
waitForStabilityboolean | { maxAttempts?, intervalMs?, pixelThreshold?, maxUnstableRatio? }falseWait for consecutive animation frames to converge before taking the screenshot (defaults: maxAttempts 4, intervalMs 120, maxUnstableRatio 0.0005).
redactSensitiveboolean | string[]falseMask password, credit-card (autocomplete^="cc-"), one-time-code, and [data-frontguard-redact] / [data-sensitive] elements (plus any custom selectors) and scrub DOM snapshots.
freezeTimeboolean | number | stringundefinedFreeze page.clock and Date.now() to a fixed epoch ms or ISO 8601 date string.
seedRandomboolean | numberundefinedOverride Math.random() with a seeded Mulberry32 PRNG.
blockUrlsstring[][]Abort third-party URLs matching glob/substring patterns before capture.
ignoreArray<{ 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? }undefinedOptional BYOK vision triage (openai, anthropic, gemini). maxCalls caps model calls per run; skipped calls are reported in aiUsage and leave pixel results unchanged.
pluginsFrontguardPlugin[][]Registered 9-hook lifecycle plugins (accessibility, performance budgets, script inventory, custom).
outputDirstring'./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:

frontguard.config.ts: per-route actions
routes: [
  {
    path: '/settings',
    actions: [
      { type: 'fill', selector: 'input[name="search"]', value: 'billing' },
      { type: 'click', selector: '[data-testid="open-api-key-modal"]' },
      { type: 'waitForSelector', selector: '[role="dialog"]' },
      { type: 'wait', ms: 150 },
    ],
  },
]

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:

frontguard.config.ts: hermetic anti-flake setup
export default {
  version: 1,
  baseUrl: 'http://localhost:3000',
  waitForStability: true,
  freezeTime: '2026-01-01T00:00:00Z',
  seedRandom: 42,
  blockUrls: [
    '*googletagmanager.com*',
    '*intercom.io*',
    '*segment.com*',
    '*doubleclick.net*',
  ],
  ignore: [
    { selector: '[data-testid="live-latency-sparkline"]' },
  ],
}

Optional controls

Deterministic Rendering and Anti-Flake Engine
FIG 02 · DETERMINISTIC STABILIZATION GATES — CLOCK FREEZE · PRNG SEED · NETWORK GUARD · FRAME CONVERGENCE · PII REDACTION

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.