For screenshot-based visual regression, add Storybook’s @chromatic-com/storybook integration, store its project token in a GitHub Actions secret, and run the visual check in CI. It compares rendered stories with accepted visual baselines and reports changes for review. Use Storybook’s Vitest addon or test-runner for render, interaction, and accessibility tests; those serve different purposes and can complement visual comparison.
Choose the right kind of Storybook test
“Visual test” can mean different things. Select a tool based on what you need CI to detect:
| Need | Suitable path | What it checks | Trade-off |
|---|---|---|---|
| Detect changes in how stories look | Chromatic visual testing through @chromatic-com/storybook |
Rendered pixels compared with visual baselines | Uses a cloud service and project token; reviewing and deciding whether to accept diffs is part of the workflow. |
| Test story rendering, interactions, or accessibility | Storybook Vitest addon | Story tests executed through Vitest | Runs in repository CI and requires a correctly configured Storybook project and browser/runtime setup. |
| Run custom tests against a built or published Storybook | Storybook test-runner | Tests against a running Storybook | Typically requires building or publishing Storybook, serving it, and waiting until it is available. |
| Exercise full application journeys | A separate end-to-end tool such as Cypress or Playwright | End-to-end flows | Complements component and story checks; it does not replace visual diffs. |
A pixel comparison can flag a visible change even when the markup is unchanged. A markup snapshot can flag an HTML change that does not affect appearance. Choose the check that corresponds to the regression you want to catch. Storybook’s testing overview describes the different test types.
Set up Chromatic visual tests
Requirements and project setup
Storybook’s visual-testing documentation says @chromatic-com/storybook requires Storybook 7.6 or higher. The separate Chromatic integration page lists Storybook 6.5+ among requirements for its CLI/action system. These describe different parts of the integration; check both pages against the versions in your repository rather than treating them as one minimum version.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
-
From the repository root, run the documented setup command:
npx storybook@latest add @chromatic-com/storybook -
Create or select a Chromatic project when prompted. Setup adds project configuration to Storybook. Review the generated files and settings, including
chromatic.config.jsonif present; it can contain a project ID and optional build-script name, debug setting, or zip option. -
In Chromatic, obtain the project token for CI. Add it to the repository’s GitHub Actions secrets, for example as
CHROMATIC_PROJECT_TOKEN. Do not commit the token into workflow YAML, application code, or other repository files.
Add a GitHub Actions step
Add the Chromatic invocation to the workflow that runs for pull requests or other changes you want checked. Pass the token from the secret as an environment variable. Action syntax and inputs can change, so use the current Chromatic action documentation and the setup output for the exact invocation; Storybook’s visual testing guide documents the integration and CI review flow.
Keep the workflow aligned with your repository’s package manager, install command, Storybook version, and security policy. Pin or update Node and GitHub Action versions according to versions you have verified for your project; an example workflow should not be treated as a permanent version or permissions policy. The Storybook GitHub Actions tutorial provides broader workflow context.
Review results before merging
When CI reports visual changes, inspect the highlighted stories and pixel differences. Accept the new baseline only when the appearance change is intentional; otherwise, fix the component or styling issue and rerun the check. Storybook documents that accepted baselines are synchronized for CI. Teams can configure the resulting Git-provider check as required before merging.
Run story behavior tests with Vitest instead
If your goal is to exercise stories and their render, interaction, or accessibility assertions rather than compare screenshots, Storybook’s Vitest addon is the closer fit. The documented CI script is:
{
"scripts": {
"test-storybook": "vitest --project=storybook"
}
}The project name assumes the default Storybook Vitest project. Change it if your repository uses another name. In GitHub Actions, the usual shape is checkout, set up a Node version appropriate for the project, install dependencies with the repository’s package manager, and run the script. Storybook’s example uses a Playwright container/image; match browser dependencies and runtime to your own framework and CI environment. See Storybook’s CI guide for the documented workflow and debugging options.
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 matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Use the test-runner when the Vitest addon does not fit
The test-runner is an alternative for automated story tests against a running Storybook, including cases where you need to test a prebuilt or published instance. The local-built pattern is to check out the source, configure Node, install dependencies and Playwright, build Storybook, serve the static output, wait for the server, and run test-storybook. For a deployed Storybook, another documented pattern runs after a deployment-status event and points the command at the published URL; Storybook’s Storybook 8 example requires that published Storybook to be publicly available.
Rank #4
Consult the test-runner documentation for current command details. Large story counts or low-memory CI can lead to timeouts; reducing worker parallelism, for example with --maxWorkers=2, is a diagnostic option rather than a universal setting.
Troubleshoot common CI problems
-
The visual integration does not match the Storybook version. Check the visual addon’s 7.6+ requirement separately from the Chromatic integration page’s 6.5+ CLI/action requirement. Confirm the versions supported by the pages and packages you are using before changing dependencies.
-
The CI result links to localhost. A localhost URL on the CI runner is not accessible to you. For Vitest debugging, publish Storybook and provide its URL using the documented
SB_URLapproach where useful.Free tools Windows power users keep installed
One-click scans. No signup required.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.Best Value
-
The test-runner times out or exhausts memory. A large number of stories or limited CI memory can be responsible. Try lowering worker parallelism, such as
--maxWorkers=2, then adjust based on the runner’s available resources. -
A markup snapshot changes but the UI looks the same. Snapshot tests inspect markup, not rendered pixels. Use a visual baseline comparison when appearance is the intended target.
-
The CI job cannot authenticate with Chromatic. Verify that the project token is stored as a GitHub Actions secret and exposed to the Chromatic step under the variable name expected by its current action or CLI configuration. Keep the secret out of committed files.
Or skip the browser setup
For standalone website screenshots outside Storybook’s story-baseline workflow, ScreenshotNeo offers a screenshot API and MCP server. A single GET request returns an image or PDF; for example, this cURL request saves a WebP screenshot:
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 options and response details. It removes cookie/consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its 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. It is an alternative for capturing pages, not a replacement for Chromatic’s Storybook visual-baseline review.
Sign up for 1,000 free screenshots a month with no card.
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.
