chromatic-visual-regression-testing

Overview

Chromatic is a visual testing platform built by the team behind Storybook (chromatic-overview). 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).
• 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.)

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):

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); 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):

export CHROMATIC_PROJECT_TOKEN=<token>
npx chromatic

Useful flags (cli):

Configuration file

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

{
  "$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).

Reading exit codes

Per the Chromatic CLI docs, 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).

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.)

Full-rebuild triggers

TurboSnap conservatively snapshots everything when any of these change (turbosnap):

• 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).

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).

References

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