How to Set Up Visual Regression Testing in Chromatic
CSS changes are notoriously unpredictable. A one-line tweak to fix padding on a button can break the layout of a card component three pages away. Unit tests do not catch visual regressions because they test logic, not appearance. Manual QA catches some issues but cannot possibly verify every component at every viewport on every page. Visual regression testing fills this gap by comparing screenshots of your UI before and after every change.
Chromatic, built by the Storybook team, automates visual regression testing by capturing screenshots of every Storybook story and comparing them against a baseline. When a visual change is detected, it flags the diff for human review — so intentional changes get approved and unintentional changes get caught. This guide covers setting up Chromatic from scratch, integrating it with CI, and building a review workflow that your team will actually follow.
Step-by-step guide
Ensure Storybook coverage for critical components
Chromatic tests what Storybook renders, so your Storybook coverage determines your visual regression coverage. Audit your component library and ensure stories exist for every component that appears in user-facing screens. Each story should render the component in a meaningful state: default, loading, error, empty, and populated with realistic data. Focus on the components that appear most frequently and the ones with the most complex CSS.
- List your 20 most important UI components and verify each has Storybook stories
- Add stories for key states: default, loading, error, empty, and edge cases (long text, many items)
- Ensure stories use realistic data rather than placeholder text for accurate visual comparison
Create a Chromatic account and connect your repository
Sign up at chromatic.com and create a new project. Connect your GitHub, GitLab, or Bitbucket repository. Chromatic will provide a project token that you will use to authenticate builds. Store this token as a secret in your CI environment (e.g., CHROMATIC_PROJECT_TOKEN in GitHub Secrets). Install the Chromatic CLI as a dev dependency in your project: npm install --save-dev chromatic.
- Create a Chromatic account and link it to your repository
- Copy the project token and add it as a CI secret
- Install the chromatic npm package: npm install --save-dev chromatic
- Test locally by running npx chromatic --project-token=<token> to verify the connection
Configure Chromatic in your CI pipeline
Add a Chromatic step to your CI workflow that runs on every pull request. In GitHub Actions, create a job that checks out the code, installs dependencies, and runs npx chromatic --auto-accept-changes=main --exit-zero-on-changes. The auto-accept-changes flag automatically updates baselines when changes merge to main. The exit-zero-on-changes flag prevents CI from failing on detected changes — instead, it reports them for review in the Chromatic dashboard.
- Add a chromatic.yml workflow file to .github/workflows/
- Configure the job to run on pull_request events targeting main
- Set --auto-accept-changes=main to keep baselines updated on merge
- Add --exit-zero-on-changes so visual diffs are flagged but do not block CI
Establish your baseline snapshots
Run Chromatic against your main branch to capture the initial baseline. This first run establishes the reference screenshots that all future changes will be compared against. Review the captured snapshots in the Chromatic dashboard to verify they look correct. If any stories render incorrectly (missing data, wrong viewport, broken styles), fix them before establishing the baseline — an incorrect baseline will generate false positives on every future build.
- Run npx chromatic on the main branch to capture initial baselines
- Review every captured screenshot in the Chromatic dashboard
- Fix any stories that render incorrectly before accepting the baseline
- Accept all correct snapshots to establish the baseline
Set up the visual review workflow
When a pull request triggers visual changes, Chromatic posts a status check on the PR with a link to the review. Define your team's review workflow: the PR author reviews all visual changes in Chromatic, approves intentional changes, and flags unintentional ones for investigation. For critical UI components (checkout, auth flows), require a second reviewer. Chromatic's side-by-side diff view highlights exactly which pixels changed, making review fast and precise.
- Configure Chromatic to post PR status checks via the GitHub integration
- Document the review process: author reviews first, then requests approval for critical component changes
- Set up Chromatic's UI Review feature for team-level approval workflows
- Create a rule that PRs with unreviewed visual changes cannot be merged
Handle responsive and interaction states
Configure Chromatic to capture snapshots at multiple viewports to catch responsive regressions. In your Storybook configuration, add viewport parameters for mobile (375px), tablet (768px), and desktop (1440px). For interaction states like hover, focus, and expanded menus, use Storybook's play functions to trigger the interaction before Chromatic captures the screenshot. This ensures your visual regression tests cover the full range of how components appear to users.
- Add viewport parameters in .storybook/preview.js for mobile, tablet, and desktop
- Use Storybook play functions to capture hover, focus, and expanded states
- Configure Chromatic's --only-changed flag to speed up builds by testing only affected stories
Monitor and optimize your Chromatic usage
Chromatic charges based on the number of snapshots per month. Monitor your usage in the Chromatic billing dashboard. Optimize by using TurboSnap, which only re-captures stories affected by code changes rather than the entire library. Remove duplicate or redundant stories that do not add visual regression value. Set up snapshot limits and alerts so you are notified before exceeding your plan.
Common mistakes
Establishing baselines from a broken state
If your initial baseline includes stories with missing fonts, broken layouts, or incorrect data, every future build will be compared against these flawed references. Take the time to fix every story before accepting the initial baseline. Future you will thank present you.
Not testing responsive viewports
Testing only at desktop resolution misses the majority of visual regressions that occur at smaller viewports. CSS breakpoints, text overflow, and image scaling all behave differently at mobile and tablet widths. Configure at least three viewports in your Storybook settings.
Ignoring Chromatic review results
If the team routinely approves all visual changes without looking because they are in a rush to merge, the visual regression system provides zero value. Make visual review a required step in your PR process, and assign specific reviewers for critical component changes.
Testing with dynamic or randomized data
Stories that use random dates, animated content, or live API data will produce different screenshots every build, creating false positives. Use fixed mock data, freeze timers, and disable animations in Storybook's test environment to ensure deterministic screenshots.
Tips
Use Chromatic's TurboSnap feature to only capture snapshots for stories affected by your code changes — this dramatically reduces build times and snapshot costs.
Add a .chromatic.delay parameter to stories that have CSS animations so Chromatic waits for the animation to complete before capturing.
Create a 'Visual Regression Fixed' label in your issue tracker and apply it to bugs caught by Chromatic — this quantifies the value of the system at renewal time.
Schedule a monthly review of your Storybook stories to ensure coverage keeps up with new components and remove stories for deprecated components.
How Vantage helps
Vantage helps product teams define quality requirements alongside functional ones. When generating tickets, Vantage can include visual regression testing criteria in acceptance conditions, ensuring that every UI change is validated against visual baselines before reaching production.