Chromatic: Setup, Snapshots & Review Workflow

Chromatic is a visual testing platform built by the Storybook team. It renders every Storybook story in standardized cloud browsers, captures a screenshot, and diffs it against the last accepted baseline — catching visual regressions functional tests can't.

Setup

npm install --save-dev chromatic

# One-off local run — uploads Storybook build, captures/diffs snapshots
npx chromatic --project-token=<token>

# GitHub Actions — the common CI setup
# .github/workflows/chromatic.yml
# name: Chromatic
# on: push
# jobs:
#   chromatic:
#     runs-on: ubuntu-latest
#     steps:
#       - uses: actions/checkout@v4
#         with:
#           fetch-depth: 0   # required for TurboSnap's git history diffing
#       - uses: actions/setup-node@v4
#       - run: npm ci
#       - uses: chromaui/action@latest
#         with:
#           projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
#           # onlyChanged enables TurboSnap — skip stories unaffected by this commit
#           onlyChanged: true

How a Snapshot Becomes a Test

• Every Storybook story (a specific component state, e.g. Button/Disabled) automatically becomes one visual test case — no separate test-writing step.

• Each story is rendered in a standardized cloud browser and captured as a screenshot (the snapshot).

• The new snapshot is diffed pixel-by-pixel against the story's baseline — the last snapshot explicitly accepted as correct.

• A detected pixel difference surfaces as a UI change requiring human review — accept (promotes it to the new baseline) or deny (flags it as a regression to fix).

• Cross-browser mode captures the same story across multiple engines (Chrome/Firefox/Safari) to catch browser-specific rendering bugs.

• Viewport configuration captures a story at multiple screen widths to catch responsive-layout regressions.

PR Integration & Review

// Chromatic runs as a required status check on every PR push.
// Pending UI changes block the check from passing until reviewed in
// Chromatic's UI -- ensuring visual regressions get eyes on them
// before merge, not discovered after shipping.

// A build has three possible outcomes per story:
// - No visual changes  -> passes automatically
// - Visual changes detected -> pending review (accept/deny)
// - New/removed story -> flagged for review too

// .storybook/main.ts -- viewports and cross-browser config live in
// Chromatic project settings (chromatic.config.json or the dashboard),
// not in Storybook config itself
// chromatic.config.json
// {
//   "projectId": "Project:...",
//   "viewports": [320, 768, 1200],
//   "diffThreshold": 0.063
// }