How to Run Visual Testing with Storybook
Set up Storybook visual tests with Chromatic, create and review screenshot baselines, and run checks locally and in CI.
Storybook visual testing renders your stories and compares screenshots with previously accepted baselines. The documented Storybook workflow uses the official @chromatic-com/storybook addon and Chromatic’s cloud service. Your first visual test build establishes baselines; later builds show differences for review. Accept a difference when the UI change is intentional, or fix the component and rerun when it is unexpected.
Visual tests answer “Does this story look different?” They do not replace interaction tests, which simulate actions and assert behavior, or render tests, which check that a story renders without an error. Accessibility checks and markup snapshots are separate test types.
1. Install the visual testing addon
From your project directory, run Storybook’s documented setup command:
npx storybook@latest add @chromatic-com/storybookThe official addon connects Storybook to Chromatic for visual testing. Follow the setup prompts, then start Storybook using the command already configured in your project, commonly npm run storybook. Open the Visual Tests panel, or its section in the testing widget if you use the Vitest addon.
Sign in to Chromatic and select an existing project or create one. The project associates your stories and snapshots with the visual test builds.
2. Create the initial baseline
Run the first visual test build from the Visual Tests panel. This run creates baseline snapshots for the stories in the project. Those accepted snapshots are the reference for future comparisons.
Review the initial output rather than treating the baseline as automatically correct. A baseline captures the current rendered state, including any accidental styling issues or unstable content already present. Fix known problems before accepting the snapshots as the reference.
3. Run visual tests after a UI change
After changing a component, its styles, or a story, run the visual tests from the expanded testing widget or Visual Tests addon panel. The stories are sent to the cloud for snapshots and visual-change detection. The resulting build reports stories whose appearance differs from their accepted baselines.
Keep the story set meaningful: stories should represent the important component states and variants your team wants to protect. A visual test can only compare states represented by stories that are included in the run.
4. Review and resolve each visual diff
- Open each highlighted story and inspect the changed pixels in context.
- Decide whether the difference is an intended design change or an unexpected regression.
- If it is intentional, accept the change as the new baseline.
- If it is unexpected, fix the component or story, rerun the visual tests, and review the updated result.
A passing build means the tested stories match their accepted visual references according to the comparison. It does not prove that a user interaction works or that an unrepresented state renders correctly. Add interaction assertions for behavior that matters.
5. Run visual tests in CI before merge
Run visual checks during development and in continuous integration so a pull or merge request surfaces visual changes before merge. Configure the Chromatic project token as CI authentication, following the setup instructions in the project’s addon and Chromatic workflow. Keep the token in your CI secret store rather than committing it to source control.
Use the pull or merge request check to surface errors and changes awaiting review. A useful team workflow assigns someone to inspect diffs and accept intentional updates; changed screenshots need human judgment about whether the design change is expected.
Visual tests, interaction tests, and render tests
| Test type | Question it answers | Storybook mechanism |
|---|---|---|
| Render test | Did the story render without an error? | Story rendering check |
| Interaction test | Does the component behave correctly after actions? | A story’s play function simulates actions and asserts behavior |
| Visual test | Does the rendered appearance differ from the accepted reference? | Snapshot comparison and visual diff |
| Accessibility or markup snapshot test | Does the story meet the relevant accessibility or markup checks? | Separate Storybook testing capabilities |
Use visual checks for appearance and targeted interaction assertions for behavior. A screenshot diff may reveal a changed button, but it does not establish that clicking the button produces the intended result.
Test runner compatibility note
Do not copy an old @storybook/test-runner setup into a new project without checking its Storybook version and current support status. The official addon listing says support for Storybook Test Runner has ended and points Vite-based projects toward Storybook’s Vitest integration. The listing also identifies different compatible test-runner package versions for Storybook 6, 7, 8, 9, and 10.
For visual regression coverage, use the documented Chromatic addon workflow above. For story interaction tests, Storybook’s current interaction guide describes running tests through the Vitest addon in the UI, editor, CLI, or CI.
Performance, reliability, and cost considerations
- Scope the story set: Include the states that matter for your UI. Every additional story is another visual state to render and review.
- Keep stories repeatable: Avoid changing content or state between runs when that content is meant to stay fixed; otherwise diffs may reflect changing inputs rather than a code change.
- Expect review work: Snapshot comparisons detect changes, but a person must decide whether each meaningful difference is intended.
- Use CI as a merge checkpoint: Running the check before merge makes visual changes visible while the related code review is active.
- Check current service terms: The research sources establish the Chromatic workflow, but do not establish current plan limits or prices. Consult Chromatic’s current documentation for those details.
Common problems and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
| The addon setup command fails | The command is being run outside the project or the existing Storybook setup is incompatible with the expected configuration. | Run it from the project root, inspect the reported Storybook version and setup error, and use the installation guidance for that project version. |
| The Visual Tests panel or widget section is missing | The addon setup may not have completed, or the project is using a different testing integration. | Confirm the addon was added successfully, restart Storybook, and check the panel or the testing widget section for your setup. |
| You cannot select the intended Chromatic project | You may be signed into a different account or the project has not been created for that account. | Sign in with the account that owns the project, or create a project before running the first build. |
| CI cannot authenticate | The project token is missing, invalid, or unavailable to the job. | Set the token in the CI secret store, expose it to the visual test job, and verify the workflow uses the correct project credentials. |
| Many diffs appear after an unrelated change | The rendered output changed across stories, or a story includes content that varies between runs. | Inspect representative diffs, identify the shared cause, make the stories repeatable where possible, then rerun and review. |
| A visual test passes but a control is broken | Visual comparison checks appearance, not the full behavior of a control. | Add or update a story interaction test with a play function and assertions for the action and expected result. |
| Old Test Runner instructions do not fit the project | Official support has ended, and compatibility differs across Storybook versions. | Check the official addon listing for the project version; for Vite-based interaction testing, use the Vitest integration guidance. |
Or skip the browser setup
If you need a screenshot of a live page as part of a separate visual review workflow, ScreenshotNeo provides a screenshot API and MCP server. It can capture a URL in one GET request. This does not replace Storybook’s story-based baseline workflow; it is an option for capturing website pages directly.
See the ScreenshotNeo API documentation. Example request:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.
Sign up for ScreenshotNeo’s free 1,000 screenshots per month, with no card required.
FAQ
Does Storybook visual testing require writing a test for every screenshot?
Stories are the units under test. Once visual testing is enabled, the stories included in a build can be rendered and compared with their baselines.
Should I accept every diff that appears?
No. Accept a diff when the visual change is intended. Fix and rerun when it shows an unexpected change.
Can visual testing replace interaction tests?
No. Use visual snapshots to check appearance and interaction tests to simulate actions and assert behavior.
When should I run the checks?
Run them while developing and in CI before a change is merged, so diffs can be reviewed alongside the code change.
