chromatic

Automate visual testing across browsers. Gather UI feedback. Versioned documentation.

weekly downloads5.0M

versionv15.1.1

licenseMIT

categorytesting

storybook-addonstorybookaddontestpopular

Overview

Chromatic is a command-line tool designed for automating visual regression testing of Storybook components. With over 5 million weekly downloads, it's become the de facto solution for teams building component libraries who need to catch unintended UI changes before they reach production. The package builds your Storybook, uploads it to Chromatic's cloud infrastructure, captures pixel-perfect screenshots across browsers, and compares them against baseline snapshots to detect visual regressions.

The tool integrates natively with Storybook's story format, treating each story as an individual test case. This means you don't write separate test files—your existing component documentation becomes your test suite. Chromatic handles the complexity of cross-browser rendering, parallel test execution, and baseline management automatically. It maintains per-branch baselines to avoid false positives when multiple teams work on different features simultaneously.

Chromatic excels in CI/CD environments with optimization flags like --only-changed (tests only modified components based on git diff) and --exit-zero-on-changes (prevents blocking builds on visual changes). The tool supports interaction testing via Playwright or Testing Library, capturing UI states mid-interaction. Configuration can be managed through chromatic.config.json or CLI flags, with support for ignoring files via --untraced to avoid wasting snapshot quotas on dependency updates.

Teams using React, Vue, Angular, or any framework supported by Storybook benefit from Chromatic's component-level tracking and review workflows. The tool generates shareable URLs for each build, enabling designers and QA engineers to review visual changes directly in pull requests without needing local development environments.

Quick Start

typescript

// Install: npm install --save-dev chromatic
// Add script to package.json and run with: npm run chromatic

// package.json
{
  "scripts": {
    "chromatic": "chromatic --exit-zero-on-changes"
  }
}

// chromatic.config.json (project root)
{
  "projectToken": "chpt_your_token_here",
  "buildScriptName": "build-storybook",
  "onlyChanged": true,
  "untraced": ["package-lock.json", "yarn.lock"],
  "autoAcceptChanges": "main",
  "externals": ["public/**"]
}

// CI workflow example (.github/workflows/chromatic.yml)
name: Visual Tests
on: [push, pull_request]
jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true
          exitZeroOnChanges: true

// Button.stories.jsx with interaction test
import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    chromatic: {
      modes: {
        light: { theme: 'light' },
        dark: { theme: 'dark' }
      },
      delay: 300
    }
  }
};

export const InteractiveHover = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');
    await userEvent.hover(button);
    await expect(button).toHaveClass('button--hover');
  }
};

Use Cases

Component library maintenance: Track visual changes across a design system with hundreds of components. When refactoring Button variants or updating global CSS variables, Chromatic detects unintended ripple effects across all story permutations, catching issues like color contrast problems or layout shifts in specific states.

Pull request review automation: Block merges until visual changes are explicitly approved. Integrate with GitHub Actions using chromaui/action@latest to add status checks that fail when unapproved UI changes are detected, forcing explicit acknowledgment of visual differences before code reaches main branches.

Cross-browser compatibility testing: Verify components render consistently in Chrome, Firefox, Safari, and Edge without maintaining local Selenium grids. Useful for catching browser-specific bugs like flexbox rendering differences or CSS property support gaps that only appear in specific browsers.

Theme and responsive design validation: Test component variations across light/dark themes and viewport sizes using parameters.chromatic.modes. Automatically capture screenshots for each theme permutation, ensuring buttons, cards, and navigation elements adapt correctly without manual testing.

Documentation versioning: Generate versioned Storybook documentation that teams can browse historically. When debugging production issues, developers can reference the exact component states from specific releases by accessing Chromatic's archived builds linked to git commits.

Pros & Cons

Pros

+Zero-config Storybook integration—existing stories become test cases without writing additional test files or selectors
+Intelligent diffing with per-branch baselines eliminates false positives from parallel feature development
+CI optimization flags like --only-changed and --untraced significantly reduce test time and snapshot quota consumption
+Cloud-based parallel execution across browsers without maintaining infrastructure or Selenium grids
+Comprehensive interaction testing support captures UI states mid-click, mid-hover, or after complex user flows

Cons

−Requires paid plan beyond free tier quotas (5,000 snapshots/month for open source projects, less for commercial use)
−Tightly coupled to Storybook—not suitable for non-Storybook applications or full-page E2E testing
−Cloud dependency means tests fail if Chromatic's infrastructure is down; no fully offline mode for local-only workflows
−Snapshot quotas can be consumed quickly in large monorepos unless carefully configured with --untraced and --only-changed
−Learning curve for advanced config like externals, ignoreLastBuildOnBranch, and interaction test debugging

Comparisons

storybook vs chromatic

testing

Install

bash

npm install chromatic

bash

pnpm add chromatic

bash

bun add chromatic

Overview

Quick Start

typescript

// Install: npm install --save-dev chromatic
// Add script to package.json and run with: npm run chromatic

// package.json
{
  "scripts": {
    "chromatic": "chromatic --exit-zero-on-changes"
  }
}

// chromatic.config.json (project root)
{
  "projectToken": "chpt_your_token_here",
  "buildScriptName": "build-storybook",
  "onlyChanged": true,
  "untraced": ["package-lock.json", "yarn.lock"],
  "autoAcceptChanges": "main",
  "externals": ["public/**"]
}

// CI workflow example (.github/workflows/chromatic.yml)
name: Visual Tests
on: [push, pull_request]
jobs:
  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm ci
      - uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true
          exitZeroOnChanges: true

// Button.stories.jsx with interaction test
import { within, userEvent } from '@storybook/testing-library';
import { expect } from '@storybook/jest';

export default {
  title: 'Components/Button',
  component: Button,
  parameters: {
    chromatic: {
      modes: {
        light: { theme: 'light' },
        dark: { theme: 'dark' }
      },
      delay: 300
    }
  }
};

export const InteractiveHover = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    const button = canvas.getByRole('button');
    await userEvent.hover(button);
    await expect(button).toHaveClass('button--hover');
  }
};

Use Cases

Pros & Cons

Pros

+Zero-config Storybook integration—existing stories become test cases without writing additional test files or selectors
+Intelligent diffing with per-branch baselines eliminates false positives from parallel feature development
+CI optimization flags like --only-changed and --untraced significantly reduce test time and snapshot quota consumption
+Cloud-based parallel execution across browsers without maintaining infrastructure or Selenium grids
+Comprehensive interaction testing support captures UI states mid-click, mid-hover, or after complex user flows

Cons

−Requires paid plan beyond free tier quotas (5,000 snapshots/month for open source projects, less for commercial use)
−Tightly coupled to Storybook—not suitable for non-Storybook applications or full-page E2E testing
−Cloud dependency means tests fail if Chromatic's infrastructure is down; no fully offline mode for local-only workflows
−Snapshot quotas can be consumed quickly in large monorepos unless carefully configured with --untraced and --only-changed
−Learning curve for advanced config like externals, ignoreLastBuildOnBranch, and interaction test debugging