Storybook Visual Testing: A Developer’s Guide

Storybook visual testing captures rendered stories as screenshots and compares them with earlier baselines to reveal changes in appearance. A difference is a signal for a person to review: accept it as an intentional update or fix the unintended change. It does not, by itself, prove that behavior, accessibility, or markup is correct.

For Storybook’s documented hosted workflow, add @chromatic-com/storybook, inspect visual changes during development, and run checks in CI before merging. The documented add command is npx storybook@latest add @chromatic-com/storybook; the referenced visual-testing page requires Storybook 7.6 or later. Check the documentation for your installed Storybook version and framework before upgrading or applying version-specific setup.

1. What Storybook visual testing checks

A story represents a component in a particular state, such as a primary button, a disabled button, or a dialog with content. A visual test renders that story and compares its pixels with a baseline. This makes changes to layout, color, size, typography, and other visible details easier to spot across many component states. Storybook describes the purpose simply: “Visual tests catch bugs in UI appearance.” (Storybook visual testing documentation.)

The practical loop is:

Define the component states your team wants to keep an eye on as stories.
Capture those stories and compare them with accepted baselines.
Review changed stories and their diffs.
Accept intended visual changes as new baselines, or fix unintended changes and rerun.

A pixel difference does not explain why the page changed or whether the change is wrong. A font update, intentional redesign, missing asset, or layout regression can all produce a diff. Human review supplies that context.

2. Set up the documented Storybook integration

Check your installed Storybook version and framework. The visual testing page linked above documents Storybook 7.6 or higher for the @chromatic-com/storybook addon. The command uses storybook@latest, so review its effects in your project and follow the documentation for your version.
From your project root, run the documented add command:

npx storybook@latest add @chromatic-com/storybook

Start Storybook using your project’s configured script, commonly npm run storybook or npm run storybook -- --port 6006. Script names vary by project; check package.json.
Open the Visual Tests panel and follow its setup prompts to connect the project and inspect story changes. The exact panel and onboarding steps can vary with the installed addon version.
Configure CI authentication using a Chromatic project token as directed by the documentation. Store the token as a CI secret or protected environment variable. Do not commit the token to source control or put it in a public build log.
Run the visual check for changes before merge. Storybook recommends checking changes during development and running visual tests in CI; its workflow surfaces test errors and UI changes for review.

Consult the version 8 visual testing guide and the documentation matching your project’s installed version for current installation and CI details. Do not assume an add command or configuration shown for one Storybook version applies unchanged to another.

3. Review changes and update baselines

When a check reports changed stories, inspect the affected story and its highlighted diff. Confirm whether the change is expected and whether the component still looks correct in the relevant states.

Expected change: accept the visual update as the new baseline after review.
Unexpected change: fix the component, styles, assets, or test setup, then rerun the check.
Unclear change: inspect the story’s inputs and surrounding changes before accepting it. A baseline update records a new reference; it does not establish that the design is correct.

Storybook recommends running checks before merge and describes PR checks as a way to flag errors and UI changes for team review. If your repository supports required checks, consider making the visual check a merge requirement so an unresolved result cannot pass unnoticed. Agree on who reviews and approves baseline updates, especially for shared design-system components.

4. Visual tests, interaction tests, accessibility tests, and snapshots

These test types answer different questions. Passing one does not establish that the others pass.

Test type	What it checks	What it does not establish alone
Visual regression	Whether rendered pixels differ from an accepted baseline.	Whether a control behaves correctly or the page meets accessibility requirements.
Interaction or behavior	Whether actions and expected component behavior work.	Whether the final appearance matches its intended design.
Accessibility	Accessibility issues covered by the configured checks.	Whether all visual differences are intentional or all user flows work.
Markup snapshot	Whether rendered markup differs from a saved snapshot.	Whether the pixels on screen look the same.

Storybook distinguishes visual tests, which compare rendered pixels, from snapshot tests, which compare rendered markup. Its testing overview also treats component behavior, visual appearance, accessibility, and snapshot tests as separate approaches. Choose checks based on the failure you want to detect; a screenshot diff is not a substitute for interaction assertions or accessibility checks. (Storybook testing overview.)

5. Chromatic or the Storybook test-runner?

Storybook describes the test-runner as a generic tool that can run locally or in CI and can be configured or extended. It describes Chromatic as a hosted visual and interaction testing service with git-provider synchronization and access controls. The choice depends on what you want to operate and which checks you need; the documentation does not make either universally best.

Consideration	Chromatic	Test-runner
Execution model	Hosted service.	Generic local or CI testing tool.
Visual review	Provides hosted visual testing and review workflow.	Can be configured or extended; teams may need to implement the visual comparison workflow they require.
Other checks	Storybook describes visual and interaction testing.	Useful for custom tests and broader local or CI tasks.
Possible combination	Run hosted visual checks in CI.	Run locally for development or use for custom tests alongside hosted checks.

Storybook’s current test-runner documentation says the runner has been superseded by the Vitest addon for Vite-powered Storybook frameworks. Integration guidance changes with framework and version, so use the page matching your setup before adopting a runner or migrating. (Storybook test-runner documentation.) Chromatic’s interaction-testing docs describe a separate Storybook version requirement of 6.5.10 or later for that feature; that requirement should not be confused with the visual testing page’s 7.6-or-later note. See Chromatic interaction tests for the feature-specific guidance.

6. When a generic screenshot workflow helps

Storybook stories are useful when the target is a component state inside a Storybook project. A generic screenshot API can complement that workflow when you need captures of published pages, a URL outside Storybook, or image and PDF output from a URL. It does not replace Storybook’s story-based baseline review or the other test categories above.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Send one GET request for a URL to receive a PNG, JPEG, WebP, or PDF. Its API accepts the parameters other screenshot APIs use, which can make switching easier. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://storybook.js.org/docs/8/writing-tests/visual-testing -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={
        "access_key": "YOUR_API_KEY",
        "url": "https://storybook.js.org/docs/8/writing-tests/visual-testing",
    },
    timeout=90,
)
r.raise_for_status()
with open("shot.webp", "wb") as f:
    f.write(r.content)

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://storybook.js.org/docs/8/writing-tests/visual-testing',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie and consent banners are accepted like a visitor, and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before the shot. Each step can be turned off.
Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses include X-Page-Verdict and X-Billed headers to indicate the result.
An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients.
The free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots; yearly billing gives two months free. Every feature is on every plan.

7. Reliability, performance, and cost considerations

Keep stories representative: cover the important visual states your team wants reviewed. A screenshot workflow only covers the stories or pages it captures.
Make review part of the process: baseline diffs need a decision. Establish ownership for intentional updates and make CI results visible before merge.
Account for version and framework changes: Storybook’s integration guidance and runner recommendations are version-specific. Check the matching docs when upgrading or changing frameworks.
Separate check types: visual checks detect appearance changes, not every behavioral or accessibility problem. Add the checks that match those risks.
Budget with verified terms: the research sources do not establish Chromatic prices, quotas, or current plan limits, so check its current official terms before estimating spend. For ScreenshotNeo, the stated plans are 1,000 monthly free shots with no card, then $5 for 3,000, $15 for 15,000, $39 for 60,000, $99 for 250,000, or $249 for 1,000,000; annual billing gives two months free. All features are on every plan.

No benchmark or runtime figure is established by the cited Storybook material. Execution time depends on the project and configured workflow; use your CI results to assess whether its capture and review steps fit your merge process.

8. Troubleshooting

Symptom	Likely cause	What to do
The addon command or setup does not match your project.	The documented command and minimum version are version-specific; the project may use another Storybook version or framework.	Check the installed version and follow the matching Storybook visual testing documentation before upgrading or changing configuration.
CI cannot authenticate.	The project token may be missing, invalid, or unavailable to the job.	Configure the token as a CI secret and ensure the workflow exposes it to the intended check. Do not print it in logs.
A story is flagged after an intentional design change.	The rendered pixels no longer match the accepted baseline.	Review the diff. If the change is intended and correct, accept the updated baseline through the configured workflow.
A diff appears unrelated to the code change.	A changed input, asset, style, or test environment can affect rendered output; the diff alone does not identify the cause.	Inspect the affected story, its inputs, and the highlighted pixels. Fix the source of an unintended change, then rerun.
A visual check passes but a control is broken.	Appearance comparison does not establish interaction behavior.	Add or run interaction or component behavior tests for the relevant action.
A visual check passes but accessibility concerns remain.	Visual comparison is a separate testing approach from accessibility checks.	Run the accessibility checks appropriate to your project; do not infer accessibility from a matching screenshot.
Test-runner advice conflicts with a Vite-based Storybook setup.	Storybook says the test-runner has been superseded by the Vitest addon for Vite-powered frameworks.	Use the current test documentation for your framework and version and evaluate the Vitest addon guidance.

9. Frequently asked questions

Does a visual diff mean the change is a bug?

No. It means the rendered output differs from its baseline. Review the change and decide whether to update the baseline or fix the cause.

Do visual tests replace markup snapshots?

No. Visual tests compare rendered pixels; markup snapshots compare rendered markup. They detect different kinds of change.

Can I use the test-runner and Chromatic together?

Yes. Storybook documents combinations such as running the test-runner locally and Chromatic in CI, or using the runner for custom tests. Check current guidance for your framework and Storybook version.

Does a screenshot of a published page replace a Storybook visual test?

No. A URL screenshot captures that page at a point in time. Storybook visual testing compares story output with baselines in its review workflow; use each for the target and question it covers.