Claude Code for Chromatic Visual Test — Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using Chromatic for visual regression testing — the cloud service from the Storybook team that captures screenshots of every component story and diffs them against baselines. Chromatic catches unintended visual changes in CSS, layout, and component rendering. Claude Code can set up testing, but it generates unit tests instead of visual test workflows.

What Claude Code Gets Wrong By Default

  1. Writes snapshot tests instead of visual tests. Claude creates Jest snapshot tests with toMatchSnapshot(). Chromatic captures actual rendered screenshots in a real browser — snapshot tests check serialized HTML, not visual appearance.

  2. Adds screenshot libraries locally. Claude installs puppeteer or playwright for local screenshot comparison. Chromatic handles screenshot capture, diffing, and baseline management in the cloud — no local screenshot infrastructure needed.

  3. Ignores Storybook story organization. Claude creates test files separate from stories. Chromatic uses your existing Storybook stories as test cases — every story becomes a visual test automatically.

  4. Skips interaction testing before capture. Claude writes static stories only. Chromatic supports play functions that interact with components (click, type, hover) before capturing — testing different states visually.

The CLAUDE.md Configuration

# Chromatic Visual Testing

## Testing
- Service: Chromatic (cloud visual regression)
- Stories: Storybook stories are test cases
- Baseline: First capture becomes the baseline
- Diff: Pixel-level comparison on every push

## Chromatic Rules
- Write Storybook stories for every visual state
- Use play functions for interactive states
- Args/argTypes for component prop variations
- Each story = one visual test case
- CI: npx chromatic --project-token=TOKEN
- Review: approve/deny changes in Chromatic UI
- TurboSnap: only test changed components

## Conventions
- Story per visual state: Default, Hover, Error, Loading
- Use decorators for layout/theme context
- Play function: click, type, hover before capture
- Use args for prop variations, not separate stories
- Enable TurboSnap for faster builds
- Set viewports: chromatic: { viewports: [320, 1200] }
- Ignore flaky elements: chromatic: { diffThreshold: 0.2 }

Workflow Example

You want to add visual regression testing for a pricing card component. Prompt Claude Code:

“Create Storybook stories for the PricingCard component that Chromatic can use for visual regression testing. Cover the free tier, pro tier, and enterprise tier variants. Add a play function for the hover state on the CTA button. Configure viewport testing for mobile and desktop.”

Claude Code should create stories with args for each pricing tier, add a play function that uses userEvent.hover on the CTA button, and set chromatic: { viewports: [375, 1280] } in the story parameters for multi-viewport testing.

Common Pitfalls

  1. Flaky tests from animations. Claude adds CSS animations to components without disabling them in Storybook. Chromatic captures at a specific moment — animations cause false positives. Use chromatic: { pauseAnimationAtEnd: true } or disable animations in the Storybook decorator.

  2. Missing font loading. Claude uses custom fonts that load asynchronously. Chromatic may capture before fonts load, causing baseline diffs. Add font preloading in .storybook/preview.ts to ensure consistent rendering.

  3. Not using TurboSnap. Claude runs Chromatic on every story for every commit. TurboSnap only tests stories affected by code changes — enable it with --only-changed to reduce snapshot count and cost.