Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Reference / Playwright Plugin(7 of 37)

Playwright Plugin

SEPARATE BASELINE MODEL. The Playwright package stores files in __visual_baselines__ by default. Unlike ordinary CLI runs, visualTest creates a missing baseline and reports isNewBaseline: true.

@frontguard/playwright lets you run perceptual visual regression assertions directly inside your existing @playwright/test suites: right after complex multi-step user journeys, authenticated session setups, or mocked network responses.

Playwright and Storybook Visual Workflow
FIG 01 · @FRONTGUARD/PLAYWRIGHT & STORYBOOK — COMPONENT-SCOPED CAPTURE, SPATIAL CLUSTERS & MULTI-VIEWPORT DIFFING

Behavior

When you call visualTest(page, name, options) inside a Playwright test, Frontguard captures the page (or a specific component via selector), applies any requested anti-flake overrides (freezeTime, seedRandom, blockUrls, waitForStable, redactSensitive), and compares the capture against __visual_baselines__/<name>-baseline.png using Pixelmatch + SSIM + 8-connected spatial diff clustering.

Example

visual.spec.ts
import { test, expect } from '@playwright/test'
import { visualTest } from '@frontguard/playwright'

test('home', async ({ page }) => {
  await page.goto('/')
  const result = await visualTest(page, 'home')
  expect(result.passed).toBe(true)
})

Baseline model

Set FRONTGUARD_UPDATE=1 or pass update: true to replace Playwright-package baselines deliberately. Commit those baseline files according to your repository policy.

terminal: updating Playwright baselines
# First run creates missing baselines in __visual_baselines__/ (isNewBaseline: true)
$ npx playwright test

# When a UI change is intentional, refresh baselines explicitly:
$ FRONTGUARD_UPDATE=1 npx playwright test

When to use Playwright vs CLI

ScenarioRecommended PackageWhy
Testing 10–100+ public or sitemap routes across 3 viewports@frontguard/cliAuto-discovers routes, runs a parallel worker pool, stores baselines on the frontguard-baselines orphan branch, and generates the 4-mode HTML workbench.
Testing complex stateful flows (checkout wizard, drag-and-drop, mocked GraphQL errors) already written in Playwright@frontguard/playwrightReuses your existing Playwright Page fixture, auth storageState, and page.route() mocks without duplicating setup in frontguard.config.ts.