Snapvisor
Start free

Guide

Visual regression testing for Storybook

@snapvisor/storybook runs your stories in a real browser and captures one screenshot per story, so the story list stays in Storybook and nothing is duplicated in a visual-testing config. Snapvisor compares each screenshot with the approved baseline and posts the result on your pull request.

Install the package

shell
npm install --save-dev @snapvisor/storybook

Create a project in the Snapvisor app and copy its project token (ARGOS_TOKEN) from the project settings. Store it as a CI secret, never in the repository.

Capture with the Storybook Vitest addon

This is the recommended route. Register the plugin in your Vitest config:

vitest.config.ts
// vitest.config.ts
import { defineConfig } from "vitest/config";
import { argosVitestPlugin } from "@snapvisor/storybook/vitest-plugin";

export default defineConfig({
  plugins: [
    argosVitestPlugin({
      // Upload the screenshots only on CI.
      uploadToArgos: process.env.CI === "true",
    }),
  ],
});

A screenshot is captured for every story automatically. To capture extra screenshots at different steps of an interaction, call argosScreenshot from @snapvisor/storybook/vitest inside a story's play function.

Or capture with the Storybook Test Runner

If you run your stories with the Storybook Test Runner instead, call argosScreenshot from @snapvisor/storybook/test-runner after each visit:

.storybook/test-runner.ts
// .storybook/test-runner.ts
import { argosScreenshot } from "@snapvisor/storybook/test-runner";

export default {
  async postVisit(page, context) {
    await argosScreenshot(page, context);
  },
};

Every story the test runner visits produces a screenshot.

Stories in more than one state

If a component needs a screenshot in a second state, give that state its own story, or take an extra argosScreenshot in the story's play function.

Run it in CI

Nothing wraps your test command. Run your Vitest or Test Runner step as you normally do, with ARGOS_TOKEN set as a CI secret in the job that runs it. On GitHub Actions you can skip the token with tokenless authentication.

A green CI job after the upload means the screenshots arrived, not that they are unchanged. The gate is the status check Snapvisor posts to the pull request, so require it in your branch protection rules.

A project can produce several builds on the same commit, such as separate Storybook and end-to-end runs. A summary check rolls them into one pass or fail status you can require before merge.

Read more: GitHub tokenless authentication, Summary checks, GitHub, GitLab.

What the first build does

The first build on your base branch has nothing to compare against, so it becomes the baseline and is approved automatically. Run it on a base branch that already looks right. Later builds are diffed against the last approved build on the base branch, and approving a change promotes it to the new baseline for that branch.

Read more: Baseline builds, Review workflow.

Frequently asked questions

No. With the Storybook Vitest addon a screenshot is captured for every story automatically. You only call argosScreenshot yourself to capture extra steps inside a play function.

The Storybook Vitest addon is the recommended route. Use the Storybook Test Runner integration if that is how you already run your stories.

Give that state its own story, or take an extra argosScreenshot in the story's play function.

They land in Snapvisor as builds on the same commit, and a summary check rolls them into one pass or fail status. The same review workflow applies to Playwright and Cypress screenshots.

Chromatic pairs visual testing with a deep Storybook workflow. Snapvisor is CI-first and takes Storybook, Playwright and Cypress screenshots into one review. The sourced comparison is on the Snapvisor vs Chromatic page.

Where to go next

Snapvisor vs ChromaticPricing, Storybook depth, browsers and AI-agent access side by side.
Self-hosted visual regression testingRunning the open-source engine on your own infrastructure.
Playwright visual regression testingThe same workflow for Playwright.
Cypress visual regression testingThe same workflow for Cypress.

Sources

Every command, package name and option on this page comes from the Snapvisor documentation and the published @snapvisor packages:

Try Snapvisor free

Start free Getting started guideAll SDKs