How to Review UI Changes Visually in Storybook
Review Storybook UI changes with visual tests: establish trusted baselines, inspect pixel diffs, and handle intentional changes before they reach users.
To review UI changes visually in Storybook, compare rendered stories against an intentional baseline, inspect every flagged pixel difference, then accept the change if it is expected or fix the code and rerun if it is a regression. Run the same check in CI before merge. A visual diff shows that appearance changed; a person still decides whether the change is correct.
Storybook visual tests capture story screenshots and compare them with previous versions. They are useful for spotting changes to layout, color, size, contrast, and other appearance details. Pair them with component, accessibility, and end-to-end tests when you need to check behavior, accessibility, or whole user journeys. Storybook’s visual testing guide explains the workflow and how it differs from snapshot tests.
1. Make stories useful review cases
A visual test can only catch what a story renders. Before relying on the results, make sure your stories cover the component states and configurations likely to reveal the change. Include relevant variants, representative content lengths, and meaningful states within your project. Stories are reusable UI test cases, so treat them as a deliberate sample of the component’s appearance, not just a gallery of defaults. See Storybook’s testing overview.
- Include the variants that have different visual structure, such as compact and expanded states, where applicable.
- Use content that exposes wrapping, truncation, spacing, and overflow issues.
- Represent states that change appearance, such as loading, disabled, selected, or error, when the component supports them.
- Review the themes and viewport configurations your project considers important; the coverage depends on your setup.
Do not add states just to increase the count. Choose examples that make likely regressions visible and keep them stable enough to compare over time.
2. Create and verify the baseline
The first capture becomes useful only after someone has inspected it and confirmed that it represents the intended UI. Run the initial visual test, inspect the rendered stories, and then treat those reviewed images as the known-good comparison point. If the baseline already contains a broken layout or unexpected content, future comparisons can faithfully preserve the wrong result.
- Start Storybook with the project configuration and stories you intend to cover.
- Run the visual test workflow provided by your integration.
- Open the resulting captures and inspect the important states at their rendered size.
- Resolve setup or rendering problems before considering the captures a baseline.
- Have the appropriate reviewer accept the baseline as intentional.
Storybook’s documented visual testing integration can send stories to cloud browsers and report visual changes. The exact controls depend on the integration and its current version. The current Storybook 8 documentation says the @chromatic-com/storybook addon requires Storybook 7.6 or later; check the current addon listing and project documentation when setting it up.
3. Run visual tests after a UI change
After changing a component or its styles, rerun visual tests against the established baseline. In Storybook’s documented workflow, you can launch visual tests from the Visual Tests panel or testing widget. The integration renders stories and reports those whose appearance differs from the prior captures.
For each changed story, open the story and inspect its visual-test panel and pixel diff. Look at the component in context as well as the highlighted difference. The diff is evidence of a change, not a design verdict.
- Identify which story and state changed.
- Inspect the full rendered image, not just the highlighted pixels.
- Check whether the changed region matches the intended design or code change.
- Consider whether nearby layout, text wrapping, or other states changed unexpectedly.
- Record the decision through your team’s review process.
4. Accept intended changes or fix regressions
If the visual change is intentional, accept it as the new baseline through your visual testing integration. If it is unintended, correct the component or styling code and run the tests again. Review the new diff after the correction rather than assuming the fix only changed the intended pixels.
| What you see | Review action |
|---|---|
| The diff matches an approved design or intended component update | Accept the updated baseline according to the team’s review practice. |
| The diff shows an unexpected spacing, color, size, or layout change | Fix the implementation and rerun the visual tests. |
| The capture is blank, incomplete, or rendered in the wrong state | Investigate story setup and rendering first; do not accept it as a trustworthy baseline. |
| The difference is hard to judge from a single story | Inspect related stories and the relevant viewport or theme configuration. |
5. Put the review in CI
Run visual checks during development and in CI as a change approaches merge. A pull-request check can surface changed stories and visual updates while reviewers still have the code change in front of them. Storybook recommends this development-to-CI workflow in its visual testing automation tutorial.
Define team ownership for baseline updates. A useful review policy states who may accept intentional changes, how reviewers should handle uncertain diffs, and whether a pull request can merge with unreviewed visual changes. Keep the check aligned with the stories and configurations your team intends to protect.
6. Choose the test that answers the question
Visual tests, snapshot tests, component tests, and end-to-end tests cover different concerns. Storybook describes visual tests as rendered pixel comparisons and snapshot tests as rendered markup comparisons. Component tests can cover rendering and simulated interaction; end-to-end tests cover full workflows. Combine them when the change needs more than an appearance check. Storybook’s testing overview describes these test types and the test runner options.
| Approach | Question it helps answer | Typical review signal |
|---|---|---|
| Visual test | Did the rendered appearance change? | Screenshot comparison and pixel diff. |
| Snapshot test | Did the rendered markup change? | Markup snapshot difference. |
| Component test | Does the component render and respond as expected? | Assertions and simulated interactions. |
| End-to-end test | Does a full user workflow work? | Browser-driven workflow result. |
7. Troubleshoot common visual review problems
A baseline exists, but every run reports changes
Possible cause: The captured rendering or test configuration is not consistent with the baseline, or the UI has genuinely changed. Fix: Compare the changed story and its rendered output, verify the intended project configuration and state, then decide whether the change is intentional. Accept a new baseline only after review.
A story capture is blank or incomplete
Possible cause: The story did not render the expected state or the page did not finish rendering in the test environment. Fix: Open the story directly, confirm its setup and content, and check the integration’s reported result before treating the capture as a UI regression or accepting it.
The diff points to more pixels than expected
Possible cause: A small layout or typography change can shift downstream content, making a larger area differ. Fix: Inspect the first changed region and the full story. Check wrapping, sizing, and surrounding layout before attempting to silence the diff.
The visual test passes, but an interaction is broken
Cause: A pixel comparison checks appearance; it does not establish that behavior or a user journey works. Fix: Add or run the component interaction and end-to-end checks that cover the relevant behavior. Visual tests complement those checks.
The addon setup does not match the installed Storybook version
Cause: Integration requirements and documentation can change between versions. Fix: Check the current addon prerequisites and the documentation matching the project’s Storybook version. The Storybook 8 page lists Storybook 7.6 or higher for @chromatic-com/storybook; verify compatibility before installing or upgrading.
8. Performance, reliability, and cost considerations
Visual review adds browser rendering and comparison work for the stories and configurations you run. Keep the selected coverage focused on meaningful variants and states, and use the CI workflow your team can consistently maintain. Storybook describes its test runner as usable locally or in CI and Chromatic as a cloud visual and interaction testing service; the best execution location depends on your project’s setup and review needs.
Reliability depends on representative stories, a reviewed baseline, and consistent test configuration. A visual test can produce a clear diff and still require human judgment. It also cannot substitute for accessibility checks, interaction assertions, or end-to-end coverage.
Account for the work required to maintain stories, review updates, run CI, and maintain any chosen service. The cited Storybook guidance does not establish a universal runtime or price for a team’s configuration, so compare tools using your actual story coverage, execution needs, baseline ownership, and service pricing.
Or skip the browser setup
For an individual webpage screenshot outside your Storybook story suite, ScreenshotNeo provides a website screenshot API and MCP server. It does not replace Storybook’s baseline review workflow: use Storybook visual tests to compare stories over time, and use a page screenshot API when you need a rendered capture of a URL. See the ScreenshotNeo 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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000. This one-call page capture is separate from maintaining and reviewing Storybook baselines.
Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Should I accept or reject a visual diff?
Accept it when the rendered change is intentional and reviewed. If it is an unexpected regression, fix the code and rerun the visual test.
Do visual tests replace snapshot tests?
No. Visual tests compare rendered pixels; snapshot tests compare markup. They reveal different kinds of changes.
Can visual tests tell whether a design change is correct?
No. They identify differences from a baseline. A reviewer decides whether the difference matches the intended design.
Should I run visual tests locally or in CI?
Use the workflow that supports review during development and before merge. Storybook describes its test runner as usable locally or in CI, and documents cloud visual testing through Chromatic.
