Skip to content

Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.

2.6 KB
Raw Blame

Visual regression testing

The visual regression runner indexes the existing Storybook CSF files, builds and serves a lightweight browser app with Vite, and renders the merge base and current working tree in Chromium. It compares screenshots with Webstudio's shared vision engine and does not require a hosted service.

Run the full comparison and open the visual report:

pnpm visual-regression:ui

Limit a local run while working on one area:

pnpm visual-regression:ui -- --grep "Design system/Button"

Use --base <ref> to compare with a branch other than origin/main. Reopen the most recent report without rerunning the comparison with pnpm visual-regression:report.

The HTML report shows baseline, current, and diff images for every mismatch, plus OCR evidence for changed text. CI uploads the same self-contained report as a visual-regression-report artifact. When a comparison fails, the CI log also lists each affected story, source file, pixel mismatch, changed regions, warnings, errors, and report artifact paths.

Pixel sensitivity (0.1), mismatch tolerance (0.001%), viewport, capture, server, and cache settings live in config.ts. Add story-specific deterministic rendering options to the story's parameters.visualRegression object. Intervals and Web Animations are disabled by default after React effects settle so concurrent screenshots cannot capture different frames. External iframe contents are hidden because their rendering is outside the revision under test. Set disableAnimations: false or disableIntervals: false only when a story establishes its own deterministic state.

Story scopes are data in .storybook/story-sources.json. Each compared revision loads its own copy so removing or changing a scope remains visible to the comparison.

GitHub Actions runs the complete suite in one job and caches screenshots from successful revisions for use as PR baselines. The runner produces the baseline on the fly when the cache is missing, and keeps both the cache and a reusable baseline worktree ignored locally. CI uses the Playwright Chromium version pinned by the lockfile so those screenshots remain reusable across hosted runners. Changes anywhere in the visual harness or shared vision source automatically invalidate cached screenshots. Capture concurrency adapts to the available CPUs and can be overridden with VISUAL_CAPTURE_CONCURRENCY.

Visual differences fail the pull request. After reviewing an intentional change, add the visual-change-approved label to rerun the same comparison as approved. A new commit removes that approval. Fork pull requests run only after the safe-to-deploy label is added.