Catch UI regressions in Storybook by comparing rendered stories with approved visual baselines. A screenshot diff shows what changed; a reviewer decides whether the change is intended. Build representative stories, inspect and approve a clean first baseline, then run visual checks during development and in CI before merge.
What Storybook visual testing checks
Visual tests compare a story’s rendered appearance with a previously approved reference. They can reveal changes in layout, color, size, spacing, and contrast that may not be obvious in a code review. Storybook describes this as comparing rendered pixels against known baselines: Visual tests documentation for Storybook 8 and Visual tests documentation for Storybook 9.
A difference is a review signal, not a verdict. Approve a new baseline when the visual change is intentional; otherwise correct the code or story and run the check again. Screenshot comparison cannot determine whether a design decision is correct.
Choose the right test for the question
| Approach | What it checks | Best used for |
|---|---|---|
| Visual test | Rendered pixels and appearance compared with a baseline | Finding unintended visual changes to represented story states |
| Markup snapshot | Serialized HTML or markup output | Checking structural output; a markup change does not necessarily change what users see |
| Component or interaction test | Behavior, such as responses to user actions | Verifying functionality; use alongside visual checks when both behavior and appearance matter |
Storybook’s general-purpose Test Runner has a separate role from hosted visual testing. Its integration listing says official support for the standalone runner has ended and points Vite-based projects toward the Vitest integration. Consult the Test Runner integration listing and the documentation for your Storybook version before planning a migration. The versioned Storybook 8 Test Runner guide and Storybook 11 Test Runner guide may not describe the same current setup.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows 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 reinstallSet up a visual testing workflow
1. Make stories cover the states you care about
Visual checks work on rendered stories, so include the component states, realistic content, themes, and variations that matter to your team. As a practical consequence, a state without a story is not included in this story-based visual check. Stories should be stable and representative rather than dependent on changing live data.
2. Add the documented Chromatic integration
Storybook documents @chromatic-com/storybook as its official addon for Chromatic’s hosted visual-testing service. Its v8 guide specifies Storybook 7.6 or higher; verify the current instructions for your installed Storybook release before applying a version-specific setup.
- From the project directory, run
npx storybook@latest add @chromatic-com/storybook. - Follow the prompts to sign in or select the Chromatic project associated with the Storybook you intend to test.
- Review the generated configuration and follow the current project instructions for running a build locally and in CI.
See Storybook’s versioned visual testing guide for the setup flow. Do not assume that a command or prerequisite documented for one major version applies unchanged to another.
3. Inspect the first run before treating it as the baseline
The first build captures reference snapshots; later builds compare new captures with earlier approved snapshots. Check that the stories render correctly and that their content and states are the ones you want to protect before approving that initial reference. A flawed baseline makes later comparisons less useful.
4. Compare subsequent runs and review diffs
After a UI change, run the visual check again. Inspect the changed stories and their highlighted pixel differences. Decide story by story whether the update is intended: accept the changed baseline for an intentional design change, or fix the implementation and rerun when it is not.
5. Run checks locally and in CI before merge
Use local runs while developing to catch and inspect changes early. Then configure CI to run the visual check for proposed changes. Storybook’s CI guidance describes pull- or merge-request checks and authenticating with a Chromatic project token: Storybook visual testing and CI guidance.
Rank #4
- Store the project token as a secret or environment variable in your CI provider, following the service’s current security instructions. Do not commit the token to the repository.
- Run the documented visual-test build in the CI job for the relevant branch or pull/merge request.
- Review the resulting check and diffs. Make it a merge requirement if that fits your team’s review policy.
CI makes the comparison repeatable, but it does not replace review: the team still needs to approve intended visual changes and investigate unexpected ones.
Keep comparisons dependable
- Control story inputs. Prefer fixed content and deterministic component states so unrelated data changes do not dominate diffs.
- Protect meaningful coverage. Add stories for important variants, themes, and edge states; the visual test can only compare what the story set renders.
- Review changes rather than auto-accepting them. A changed baseline should reflect an intentional UI decision, not simply a desire to clear a failing check.
- Separate appearance and behavior coverage. Pair visual tests with interaction or component tests when a change could break functionality without visibly changing the captured state.
- Apply runner-specific resource advice only to that runner. Storybook’s Test Runner documentation discusses limiting worker counts when many stories or low-memory CI cause timeouts. This is guidance for the general-purpose runner, not a universal setting for every Chromatic build. See the Test Runner documentation.
Or skip the browser setup
For an isolated screenshot of a page or component preview, ScreenshotNeo offers a one-request screenshot API. It is not a replacement for Storybook’s per-story baseline review and CI workflow, but it can capture a URL without setting up a browser automation script.
Recommended Free Tools
Best Value
cURL:
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. The call returns an image or PDF according to the request. ScreenshotNeo can accept cookie/consent banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with the page verdict and billing status included in response headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for Claude, Cursor, and other MCP clients. The free plan includes 1,000 shots per month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo to try 1,000 free screenshots a month with no card.
Frequently Asked Questions
Does a visual diff tell me whether a UI change is a bug?
No. It identifies a difference from the approved appearance; a reviewer must decide whether that difference is intentional.
Can I use visual testing without Chromatic?
This guide covers Storybook’s documented Chromatic addon workflow. The sources cited here do not establish a fully sourced comparison of alternative visual-testing services.
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.
