How to Run Storybook Visual Tests with Vitest
Set up Storybook stories as Vitest browser component tests, understand when you need screenshot baselines, and run the right checks in CI.
Storybook’s Vitest addon runs your stories as browser-based component tests: it checks that stories render and runs their interaction tests. It does not, by itself, compare screenshots with accepted visual baselines. For screenshot-based visual regression tests, configure Storybook’s separate visual-testing workflow, such as the Chromatic visual addon. You can use both workflows together.
This guide covers both meanings of “visual tests,” shows the current Vitest setup, and explains what to add when you need screenshot comparisons.
1. Choose the check you need
| Need | Use | What it checks |
|---|---|---|
| Check that a story renders and its interaction assertions pass | Storybook Vitest addon | Story rendering and a story’s play function |
| Catch changes in appearance by comparing screenshots | A visual-testing workflow, such as the Storybook visual addon with Chromatic | Story screenshots against accepted baselines |
| Check interaction behavior and catch appearance changes | Both workflows | Component test results and screenshot differences |
Storybook describes the Vitest integration as component testing and documents visual testing as a separate workflow. The visual addon can show visual tests alongside component tests in Storybook’s testing widget. [Vitest addon documentation; visual testing documentation]
2. Check compatibility first
- Your Storybook framework must be Vite-based. The documented examples include React, Vue, Preact, SvelteKit, and Next.js with Vite.
- Use Vitest 3.0 or newer.
- For the documented Next.js route, use Next.js 14.1 or newer with
@storybook/nextjs-vite. - If the project uses MSW, use version 2.0 or newer to avoid the dependency conflict noted in Storybook’s guide.
- Projects on Webpack or Rsbuild should continue to use
@storybook/test-runnerfor component tests unless they migrate to a supported Vite framework.
These are compatibility details from the cited Storybook documentation, checked on October 3, 2026. Framework support and versions can change, so confirm the current requirements in the Vitest addon guide and migration guide before upgrading.
3. Install and run the Vitest addon
From your project root, run Storybook’s setup command:
npx storybook add @storybook/addon-vitestThe command installs and registers the addon, inspects the project’s Vite and Vitest configuration, and sets up defaults that include Vitest browser mode with Playwright Chromium. It may prompt you to install Playwright’s browser binaries. Review the generated changes, including the Vitest configuration and setup file, before committing them.
Add or use a package script for the Storybook Vitest project:
{
"scripts": {
"test:storybook": "vitest --project=storybook"
}
}Run it locally with:
npm run test:storybookThe project name and generated configuration come from the setup. The addon can run the tests without a separate Storybook server running. The transformed story tests use portable stories: the test renders each story and runs its play function, including its assertions, when present.
What happens in the browser
The default setup uses Playwright Chromium. Browser mode is useful for components that depend on browser APIs because it tests in a real browser rather than a simulated environment such as JSDOM or Happy DOM. Keep your story fixtures representative: provide the required providers, stable mock data, and any interaction setup the component expects.
4. Configure manually if the setup command cannot
Use the generated setup as the reference for your Storybook and Vitest versions. The manual path has four parts:
- Make sure the project has a supported Vite-based Storybook framework and a working Vite/Vitest configuration.
- Configure Vitest browser mode and make Playwright Chromium available in the development and CI environments.
- Install and register
@storybook/addon-vitestin Storybook’s addon configuration. - Add
.storybook/vitest.setup.tsand include Storybook’s Vitest plugin in the Vitest configuration so stories are discovered and transformed into tests.
Storybook’s plugin and setup APIs are version-sensitive, so copy the current configuration shape from the official Vitest addon guide rather than pasting an older configuration from an unrelated Vitest release. If you already run ordinary Vitest tests, use an isolated test project or workspace for Storybook so its browser settings and story discovery do not interfere with the existing suite.
5. Add screenshot-based visual tests and baselines
To detect visual changes, add a visual-testing workflow; passing Vitest component tests alone does not create or compare screenshot baselines. Storybook documents its @chromatic-com/storybook addon and Chromatic service for this purpose.
- Install and configure the visual-testing addon using the Storybook visual testing guide.
- Sign in to Chromatic and link the project as its setup requires.
- Run the first visual build. It creates the initial screenshot baselines.
- On later runs, inspect the Visual Tests panel for highlighted changes.
- Accept a change as the new baseline only when it is intentional. Otherwise, fix the UI or test setup and run the checks again.
A baseline is the previously accepted screenshot used for comparison. Changes can result from an intentional design update or an unintended regression, so review the highlighted difference in context before accepting it. Storybook’s documentation summarizes the purpose this way: “Visual tests catch bugs in UI appearance.” [Storybook visual tests]
6. Run the checks in CI
Use the same Storybook Vitest project command in CI that you use locally:
npm run test:storybookEnsure the CI environment has Playwright and the Chromium browser dependencies available. Storybook’s CI guide uses Playwright container images in its examples; follow the guide for the environment you run. [Storybook testing in CI]
Make failure links useful
For clickable story links in watch mode, configure the addon’s storybookScript so it can start Storybook. For links from CI failures to a published Storybook, build and publish Storybook first, then set storybookUrl to that published instance in the Vitest addon configuration. Check the current configuration syntax in the addon guide.
Results can differ between Vitest CLI or addon execution and the Storybook Interactions panel. When debugging, reproduce the failure with the same runner and environment used by CI before concluding that the test is flaky.
7. Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| The addon cannot configure or discover the project | The Storybook framework is not Vite-based, or the project configuration is incompatible | Confirm the framework and follow the migration guidance for Webpack or Rsbuild projects. |
| Vitest reports missing browser or Playwright errors | Browser mode or Chromium binaries are unavailable | Complete the Playwright browser installation locally and ensure the CI image has the browser dependencies. |
| A story fails during rendering | The story lacks a provider, fixture, or browser environment assumption needed by the component | Open the story, check its decorators and data setup, then reproduce through the same Vitest project. |
A play test fails |
An interaction or assertion failed, or the test runs differently in the chosen runner | Inspect the failing assertion and debug with the same CLI/addon execution path used in CI. |
| Visual changes appear even though component tests pass | Component assertions do not compare screenshots; a visual change may also be intentional | Run the visual-testing workflow, inspect its highlighted diff, and accept a new baseline only for an intended change. |
| CI failures do not link to a story | The Storybook URL or script is not configured, or the published Storybook is unavailable | Set storybookScript for watch-mode links or publish Storybook and configure storybookUrl for CI. |
| MSW causes dependency issues | The installed MSW version is below the guide’s stated requirement | Check that MSW is 2.0 or newer and review the current compatibility guidance. |
8. Reliability, runtime, and cost
Keep the workflow deterministic: use stable story data, avoid depending on external services during interactions, and keep browser and dependency versions consistent between local development and CI. If screenshot baselines vary, first check whether the environment, fonts, browser, or story data differ before accepting an update. The cited setup guides do not publish a general runtime benchmark or a universal CI cost, so measure your suite in your own runner.
Vitest component tests and hosted visual screenshot testing are distinct workflows with their own setup. The reviewed Storybook sources document the Chromatic visual-testing service but do not establish pricing or referral terms; check the service’s current terms before budgeting.
Or skip the browser setup
If you need a screenshot of a web page rather than Storybook’s story-baseline workflow, ScreenshotNeo is a website screenshot API and MCP server. Its one-call API returns an image or PDF; see the API documentation.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses identify the page verdict and billing status in headers.
- An MCP server lets AI agents, including Claude and Cursor, use screenshot tools.
- 1,000 screenshots a month are free with no card. Paid plans start at $5 for 3,000 screenshots.
Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.
FAQ
Does the Vitest addon create visual screenshot baselines?
No. It runs story-based browser component tests. Add a visual-testing workflow to capture and compare screenshots with baselines.
Can I run the addon without starting Storybook?
Yes. The addon’s Vitest project runs tests without a separately running Storybook server. A Storybook script can be configured to provide clickable failure links in watch mode.
Should I use the Vitest addon on a Webpack Storybook?
The documented addon requires a Vite-based Storybook framework. Storybook’s migration guide recommends continuing with @storybook/test-runner for Webpack or Rsbuild projects unless you migrate.
Can ScreenshotNeo replace Chromatic baselines?
No. ScreenshotNeo captures web pages through an API; the documented visual-testing workflow compares Storybook story screenshots against accepted baselines. They serve different needs.
