Storybook visual testing compares screenshots of rendered stories with earlier baselines, helping a team spot changes in a component’s appearance. A difference is a prompt for review—not proof of a defect: accept an intentional change as the new baseline, or fix an unintended one and rerun the test.
What Storybook visual testing checks
A visual test captures a story’s rendered output and compares its pixels with a previous capture. Because stories represent UI states, this lets a team inspect appearance changes across components and states, including changes to layout, color, size, and other visible details. Storybook describes the purpose directly: “Visual tests catch bugs in UI appearance.” Storybook’s visual testing documentation explains the workflow.
Visual comparison does not establish that a component behaves correctly, is accessible, or has unchanged markup. It answers a narrower question: does the rendered appearance differ from the accepted baseline?
Set up visual tests with Storybook
Check your Storybook version
Storybook’s version 8 visual-testing guide documents @chromatic-com/storybook and says Storybook 7.6 or higher is required for this setup. That is the requirement stated on that guide, not a universal minimum for every Storybook testing feature. Check the instructions for your installed version and framework before changing dependencies.
#1 Best Overall
Add the integration
From your project directory, run the documented command:
npx storybook@latest add @chromatic-com/storybookFollow the prompts and the instructions shown for your project. Then start Storybook and open the Visual Tests panel to inspect the available visual-test workflow. The official guide is the reference for setup details that depend on your project: Visual tests.
Connect CI
For CI, Storybook’s guide directs you to configure authentication with a Chromatic project token. Keep the token in your CI provider’s secret storage; do not commit it to the repository or expose it in logs. Configure the workflow using the instructions for your CI environment and the project’s current integration. A CI result can then flag test errors and visual changes for review before merge.
Review visual changes and update baselines
- Open the reported changes. Inspect which stories differ and review the highlighted visual changes rather than treating every difference as a failure.
- Decide whether each difference is intended. Check the relevant component, story state, and change being proposed. A screenshot diff signals a change; it does not tell you whether that change is acceptable.
- Update the baseline for intentional changes. Accept the new appearance when it reflects the intended UI.
- Fix and rerun unintended changes. Make the necessary code or story correction, then rerun the visual tests to confirm the result.
- Put the check in the merge path. Storybook recommends running visual tests in CI before merge. If your repository supports required checks, consider requiring the visual-test check so a change is reviewed before it is merged.
This review loop is useful only when the baseline reflects an appearance the team has actually approved. Updating a baseline without examining the difference can preserve an accidental regression.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallVisual tests versus snapshots and other checks
| Test type | What it checks | What it does not establish by itself |
|---|---|---|
| Visual test | Rendered pixels compared with a prior visual baseline. | Correct behavior, accessibility, or unchanged markup. |
| Markup snapshot | Rendered markup compared with a saved snapshot. | That the rendered pixels look right. |
| Interaction or behavior test | Whether specified interactions or component behavior meet the assertions being tested. | That every visual state matches an approved appearance. |
| Accessibility test | Accessibility issues covered by the checks being run. | That the component’s appearance or all user interactions are correct. |
Storybook presents component behavior, visual appearance, accessibility, and snapshot tests as distinct testing approaches in its testing overview. Passing one category does not imply that the others pass. In particular, Storybook contrasts visual tests, which compare rendered pixels, with snapshots that compare rendered markup.
Chromatic or a test runner?
These options serve different purposes, and a team can use both. Storybook describes Chromatic as a hosted visual and interaction testing service, while the Storybook test-runner is a generic tool that can run locally or in CI and be configured or extended. Chromatic’s documented capabilities include git-provider synchronization and access controls; the runner can suit teams that need custom tests or control over how tests are run. See the test-runner documentation and the version-appropriate visual-testing guide when choosing an integration.
- Choose a hosted workflow if you want visual diffs and review in a hosted service integrated with your development workflow.
- Use a runner when you need local or CI execution for custom testing and are prepared to configure or extend it.
- Combine them if you want the runner for local work or custom checks and Chromatic for hosted visual review in CI.
Storybook’s current test-runner documentation says the runner has been superseded by the Vitest addon for Vite-powered Storybook frameworks. The right guidance therefore depends on your framework and Storybook version; follow the matching documentation rather than assuming the older runner is the current recommendation for every project.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Where ScreenshotNeo fits
ScreenshotNeo is a website screenshot API and MCP server, not a Storybook visual-testing integration: a one-off screenshot request does not create story-based baselines, compare pull requests, or replace a visual-test review workflow. It can be an alternative to try first when your separate need is to capture a website page through an API or an AI agent. Its stated differentiators are that it removes cookie banners, newsletter popups, and chat widgets before capture, and bills only clean shots—not bot checks or CAPTCHAs, blank pages, timeouts, failed loads, or cache hits.
Or skip the browser setup:
For a standalone page capture, make one GET request (replace YOUR_API_KEY with your key and change the target URL as needed):
Best Value
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are not billed. An MCP server provides screenshot tools for AI agents, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Troubleshooting setup and review
- The add command or addon does not work with the installed project. Check the Storybook version and framework-specific instructions. The cited visual-testing guide documents a 7.6-or-higher requirement for this integration; do not apply requirements for another testing feature to visual tests.
- CI cannot authenticate. Confirm that the Chromatic project token is configured as a CI secret and that the workflow uses the correct secret name. Do not put the token in source control.
- A visual test reports a difference. Inspect the affected story and diff, then decide whether the change is intentional. Update the baseline only for an approved appearance; otherwise fix the cause and rerun.
- You expected a visual test to catch an interaction or accessibility issue. Add the relevant behavior or accessibility checks. Pixel comparison does not replace those test categories.
- You are following a test-runner guide that does not match your framework. Check the documentation for your Storybook version and framework. For Vite-powered frameworks, Storybook’s current test-runner page points to the Vitest addon as its successor.
Frequently Asked Questions
Does a visual difference mean the change is a bug?
No. It means the rendered output differs from the baseline; a developer must decide whether that difference is intentional.
Can visual tests replace accessibility tests?
No. They check rendered appearance, while accessibility checks cover a different category of issues.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
