chromatic-visual-regression-testing

Overview

Chromatic is a visual testing platform built by the team behind Storybook (chromatic-overview (opens in new window)). It works in three modes:

• Storybook (default): every story becomes a snapshot.
• Playwright: snapshots are captured during Playwright test runs via the --playwright flag.
• Cypress: snapshots are captured during Cypress runs via --cypress.

The CLI shape: chromatic is one binary; everything (auth, framework choice, TurboSnap) is a flag or env var.

When to use

• The project uses Storybook and wants a hosted UI for visual review with team sign-off on baseline changes.
• The team needs TurboSnap - a per-PR speedup that snapshots only stories whose dependency graph changed (turbosnap (opens in new window)).
• The repo already has chromatic in devDependencies or a chromatic.config.json at the root.
• Visual coverage is story-driven, not full-page-driven (in contrast to Percy or Playwright snapshots, which are page-driven by default).

Authoring

Install

npm install --save-dev chromatic

(Per the Chromatic quickstart (opens in new window).)

Connect to a project

The first run uploads the Storybook build, captures a snapshot of each story, and establishes those snapshots as the project baseline (quickstart (opens in new window)):

npx chromatic --project-token <your-project-token>

Subsequent runs compare new snapshots to the baseline; visual changes must be explicitly accepted in the Chromatic UI before the build passes.

Authoring stories (Storybook mode)

Chromatic snapshots whatever your Storybook indexes, so authoring is "add a story." Per-story knobs that affect snapshots are passed in the story's parameters.chromatic block (e.g. viewports, delay, pauseAnimationAtEnd).

Authoring tests (Playwright / Cypress mode)

When invoked with --playwright or --cypress, the CLI captures snapshots from your existing Playwright / Cypress test runs (cli (opens in new window)); no per-test code changes are required beyond running the matching framework's archive output through Chromatic.

Running

CLI invocation

The canonical invocation in CI, with the token sourced from an env var (cli (opens in new window)):

export CHROMATIC_PROJECT_TOKEN=<token>
npx chromatic

Useful flags (cli (opens in new window)):

Configuration file

chromatic.config.json at the project root - config keys mirror the CLI flags converted to kebab-case (cli (opens in new window)):

{
  "$schema": "https://www.chromatic.com/config-file.schema.json",
  "onlyChanged": true,
  "exitZeroOnChanges": false,
  "autoAcceptChanges": "main",
  "externals": ["public/**", "tokens/**"]
}

externals lists glob patterns of non-bundled files that should still trigger a TurboSnap rebuild when changed (e.g. design tokens, static assets) (turbosnap (opens in new window)).

Reading exit codes

Per the Chromatic CLI docs (opens in new window), exit codes carry semantic meaning - the gate logic should treat visual changes (1) differently from system errors (3, 21 - 23, 101 - 105, 201 - 220):

Use --exit-zero-on-changes only when changes are reviewed in the Chromatic UI (not in CI) and you want CI to remain green pending review.

TurboSnap

TurboSnap analyzes git history and the bundler dependency graph to identify stories affected by a PR's changes; only those stories are snapshotted, and the rest copy their baseline forward (turbosnap (opens in new window)).

Enable via --only-changed (CLI) or onlyChanged: true (chromatic.config.json).

Bundler requirements

• Webpack: Chromatic reads the stats file emitted by Webpack.
• Vite: Vite also supplies a compatible dependency graph.

(Per turbosnap (opens in new window).)

Full-rebuild triggers

TurboSnap conservatively snapshots everything when any of these change (turbosnap (opens in new window)):

• package.json changes without a valid lockfile.
• Storybook config (main.js, manager.js).
• preview.js imports.
• Static folders.
• Infrastructure upgrades (Storybook major version, etc.).

Merge commits also trigger conservative re-testing because TurboSnap cannot know ahead of time which baseline side to compare against (turbosnap (opens in new window)).

CI integration

The minimal pattern is: install chromatic, expose CHROMATIC_PROJECT_TOKEN as a CI secret, run the CLI, fail the job on exit != 0 (or != 0,1 if review happens in the Chromatic UI).

# .github/workflows/chromatic.yml
name: chromatic

on:
  pull_request:
  push:
    branches: [main]

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0   # required by TurboSnap

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm ci

      - name: Build Storybook + run Chromatic
        env:
          CHROMATIC_PROJECT_TOKEN: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
        run: npx chromatic --only-changed

fetch-depth: 0 is required so TurboSnap can resolve the PR-vs-baseline commit ancestry (turbosnap (opens in new window)).

References

• chromatic-overview (opens in new window) - product overview, framework support.
• chromatic-quickstart (opens in new window) - install + first-run baseline.
• chromatic-cli (opens in new window) - full CLI flag set + exit codes + config schema.
• chromatic-turbosnap (opens in new window) - TurboSnap mechanism, full-rebuild triggers, bundler requirements.