Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsTo catch visual regressions in Storybook, compare rendered stories against approved visual baselines. The comparison shows where the appearance changed; a reviewer decides whether the change is intended. Start by choosing representative stories, establish a baseline you have inspected, then run visual checks locally and in CI before merging.
What Storybook visual tests catch
A visual test captures how a story renders and compares its pixels with a known baseline. Differences can reveal changes in layout, color, size, spacing, or contrast that may otherwise escape component tests. Storybook describes the goal as comparing rendered pixels for stories against known baselines: Visual tests documentation for Storybook 8 and Visual tests documentation for Storybook 9.
As an Amazon Associate I earn from qualifying purchases.
A detected difference is a review signal, not an automatic failure verdict about design quality. If the change is intentional, approve the updated baseline. If it is accidental, fix the implementation and run the check again.
Choose stories that represent the UI you want to protect
Visual checks can only compare rendered stories that are part of the test run. Include meaningful component states and variations: for example, default, disabled, error, loading, long-content, and themed states where relevant to your product. Missing stories mean those states are not represented in the visual comparison; this follows from the per-story workflow, rather than being a guarantee about overall test coverage.
Keep story data and rendering conditions sufficiently consistent between runs. If the story itself changes unexpectedly—for example, because its content or environment varies—the resulting diff may be noisy and harder to interpret.
Set up Chromatic visual testing
Storybook documents @chromatic-com/storybook as its official addon for the hosted Chromatic visual-testing service. The Storybook 8 guide specifies Storybook 7.6 or later; check the documentation for the release actually used by your project before following version-specific setup steps.
- Install and connect the addon. From the project directory, run
npx storybook@latest add @chromatic-com/storybook. Follow the prompts to sign in or select the Chromatic project. Consult the Storybook 8 setup guide or Storybook 9 setup guide as appropriate. - Inspect the stories before establishing the reference. The initial build captures the snapshots that later runs will compare against. Review the rendered UI first so that the baseline represents the intended appearance, rather than accidentally treating an existing defect as the target.
- Run a build after meaningful UI changes. The service renders stories and compares them with previously approved snapshots. Review the flagged stories and visual differences rather than treating every changed pixel as a bug.
- Resolve each difference. Approve a change when it is intentional. Otherwise, update the component, styles, story data, or rendering conditions as needed, then rerun the check.
Run visual checks locally and in CI
Run visual checks during development to catch unexpected changes while the relevant code is fresh. Also run them in continuous integration before merging, so reviewers can examine the results alongside the proposed code change. Storybook documents CI integration and pull- or merge-request checks in its visual testing guide.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →- Create a project token using the current instructions for your Chromatic project.
- Store it as a CI secret or environment variable. Do not commit credentials to the repository. Follow the provider’s current guidance for the CI system you use.
- Run the configured visual-test build as part of the pull- or merge-request workflow.
- Make the check a merge gate if it fits your review policy. Have the team review diffs and approve intentional updates before merging; configure required checks in your repository host according to its current UI and policy.
Exact token names and CI configuration vary by project and provider, so use the current instructions for your Storybook release and CI platform rather than copying an example from a different setup.
Know how visual tests differ from other tests
| Test approach | What it compares or checks | Useful for |
|---|---|---|
| Visual regression test | Rendered pixels or appearance against an approved visual baseline | Spotting visible changes such as layout, color, and sizing |
| Markup snapshot | Serialized HTML or other markup output | Asserting output structure; markup may change without a visible difference |
| Component or interaction test | Component behavior and interactions | Checking that controls and flows work, not just how they look |
These approaches answer different questions. A markup change does not necessarily imply a visual regression, and a pixel diff does not establish that interaction behavior still works. Combine visual checks with behavior tests when both appearance and functionality matter. Storybook’s Test Runner documentation describes the separate story-based browser testing role.
Choose the right Storybook testing integration
Chromatic’s hosted visual workflow is distinct from the general-purpose Storybook Test Runner. Storybook’s current integration listing says official support for the standalone Test Runner has ended and points Vite-based projects toward the Vitest integration. Check the listing and migration details that match your Storybook version before choosing or changing integrations: Test Runner integration listing and Test Runner documentation for Storybook 11.
Rank #4
The Test Runner documentation also notes that reducing worker count can help when many stories or low-memory CI environments cause timeouts. That advice applies to the general-purpose runner discussed there; it should not be assumed to describe Chromatic build performance.
Troubleshoot visual diffs and failed runs
- A diff appears after a deliberate redesign: inspect the affected stories and approve the new baseline once the intended appearance is confirmed.
- A diff appears after a change that should not affect appearance: inspect the changed component styles, story inputs, and rendering conditions. Correct the source of the unexpected visual change, then rerun.
- A state is not represented in results: check that the state has a story and that the story is included in the visual-test build.
- The CI check cannot authenticate: confirm that the project token is present as a CI secret/environment variable and that the workflow uses the current project-specific setup.
- The general-purpose Test Runner times out in constrained CI: consult its documentation about worker limits and adjust the runner configuration for the available memory. Do not apply this as a blanket fix for a different service’s visual build.
- You are unsure which setup applies: verify the Storybook version and framework, then use the matching official documentation; versioned guides can differ.
Or skip the browser setup
For standalone screenshots outside the Storybook baseline workflow, ScreenshotNeo offers a website screenshot API and MCP server. Its one-request API returns an image or PDF, but it does not replace story-based baselines and review in CI.
Best Value
For example, this cURL request saves a screenshot of the public Stripe homepage as WebP; replace the URL with the page you want to capture:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp (API documentation)
Quick Recap
Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; those steps can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify page verdict and billing status in headers. The MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo free.
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.
