API Reference
Complete TypeScript API reference for visualTest(page, name, options), VisualTestOptions, and VisualTestResult in @frontguard/playwright.
Signature
Options
Options include threshold, selector (component-scoped locator capture), fullPage, mask, maskRegions, redactSensitive, waitForStable, freezeTime (boolean, epoch ms number, or ISO 8601 date string), seedRandom (boolean or numeric PRNG seed), blockUrls (URL patterns to block during capture), captureAriaSnapshot (stores the ARIA tree beside the PNG and diffs it as text; a mismatch does not change passed), textSnapshot (json and markdown selectors stored the same way), optional AI (openai, anthropic, gemini, or custom baseUrl), baselineDir, and update. Threshold is the fraction of pixels that may differ (0-1).
| Option | Type | Default | Description |
|---|---|---|---|
threshold | number (0-1) | 0.01 | Fraction of pixels allowed to differ before passed becomes false (0.01 = 1%). |
selector | string | undefined | CSS selector to capture a specific component instead of the full viewport. |
fullPage | boolean | true | Capture the full scrollable page height (ignored when selector is set). |
waitForStable | boolean | { maxAttempts?: number, intervalMs?: number } | false | Wait for fonts, then compare consecutive captures using threshold. Defaults: maxAttempts 3, intervalMs 80. |
redactSensitive | boolean | string[] | false | Mask password, credit-card (autocomplete^="cc-"), one-time-code, and [data-frontguard-redact] / [data-sensitive] elements (plus any custom selectors) before capture. |
freezeTime | boolean | number | string | undefined | Freeze page.clock and Date.now() via epoch ms or ISO 8601 string (e.g., "2026-01-01T00:00:00Z"). |
seedRandom | boolean | number | undefined | Override Math.random() with a deterministic Mulberry32 PRNG (true uses seed 42). |
blockUrls | string[] | undefined | Abort matching network requests via page.route() during capture and clean up afterward. |
captureAriaSnapshot | boolean | false | Store the ARIA tree beside the PNG and diff it as text. A mismatch does not change passed. axe-core remains the accessibility plugin. |
textSnapshot | { json?: string, markdown?: string } | undefined | Selectors whose text is stored as .json or .md beside the PNG. A mismatch does not change passed. |
mask | string[] | undefined | CSS selectors to cover with solid neutral boxes before screenshot capture. |
maskRegions | Array<{ x, y, width, height }> | undefined | Explicit pixel bounding boxes to mask out of comparison. |
ai | boolean | { provider: 'openai'|'anthropic'|'gemini', model?, baseUrl?, maxOutputTokens?, timeoutMs? } | false | Run optional BYOK vision analysis when a diff exceeds threshold. A failure is returned as aiError and logged once per run. |
baselineDir | string | '__visual_baselines__' | Directory where baseline, actual, and diff PNGs are stored. |
update | boolean | process.env.FRONTGUARD_UPDATE === "1" | Overwrite the existing baseline PNG with the current capture. |
Result
The result includes passed, diffPercentage, baselinePath, currentPath, optional diffPath, boolean settled when waitForStable is enabled, clusters with bbox/rawDiffPixels/targetSelector, optional ariaSnapshot and AI output, SSIM, and isNewBaseline. Compare the returned result in your test; the function does not call a Playwright assertion for you.
| Field | Type | Description |
|---|---|---|
passed | boolean | True if diffPercentage <= threshold (or if a new baseline was created). |
diffPercentage | number (0-1) | Ratio of changed pixels to total pixels (0.015 = 1.5%). |
ssim | number (0-1) | Structural similarity score between baseline and current image (1.0 = identical). |
isNewBaseline | boolean | True when no prior baseline existed and a new baseline PNG was written. |
baselinePath | string | File path to the baseline PNG. |
currentPath | string | File path to the current PNG. |
diffPath | string | undefined | File path to the diff PNG when one was written. |
clusters | PlaywrightDiffCluster[] | 8-connected spatial diff regions: { id, bbox: { x, y, width, height }, rawDiffPixels, targetSelector? }. |
settled | boolean | undefined | Whether captures converged within maxAttempts; present when waitForStable is enabled. |
blockedRequestsCount | number | Number of network requests aborted by blockUrls. |
ariaSnapshot | string | Playwright ARIA tree YAML/text snapshot when captureAriaSnapshot: true. |
textSnapshots | Array<{ kind, status, path, excerpt? }> | Text diff beside the PNG. status is match, mismatch, new, or error. A mismatch excerpt does not change passed. |
ai | { classification: string, severity: string, explanation: string } | undefined | Optional vision model triage result when ai is enabled and a diff occurred. |
