【Chromatic】Storybookビジュアルテストの導入ガイド

Chromaticは、Storybook社が提供するビジュアルテスト・UIレビュープラットフォームです。UIコンポーネントのスクリーンショットを自動的に撮影し、変更前後の差分をピクセル単位で検出できます。この記事では、Chromaticのセットアップ方法からGitHub Actionsとの連携まで、実践的な導入手順を解説します。

Chromatic の主な機能

前提条件

セットアップ手順

アカウント作成とプロジェクトトークン取得

パッケージインストール

お使いのパッケージマネージャーに応じてインストールします。

# npm
npm install --save-dev chromatic

# yarn
yarn add --dev chromatic

# pnpm
pnpm add -D chromatic

初回ビルド（ベースライン作成）

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

package.json にスクリプト追加

{
  "scripts": {
    "chromatic": "chromatic"
  }
}

環境変数でトークンを管理する場合は、.env やCI環境変数に設定します。

# .env または CI環境変数に設定
CHROMATIC_PROJECT_TOKEN=your-token-here

以降は以下のコマンドで実行できます。

npm run chromatic

GitHub Actions 連携

ワークフローファイルの作成

.github/workflows/chromatic.yml を作成します。

name: Chromatic

on:
  push:
    branches:
      - main
      - develop
  pull_request:
    branches:
      - main

jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      # コードをチェックアウト（履歴全体を取得）
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # TurboSnapに必要

      # Node.jsセットアップ
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      # 依存関係インストール
      - name: Install dependencies
        run: npm ci

      # Chromatic実行
      - name: Run Chromatic
        uses: chromaui/action@latest
        with:
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
          onlyChanged: true  # TurboSnap有効化

GitHub Secrets の設定

レビューワークフロー

Chromaticを導入した後の開発フローは以下のようになります。

主要な CLI オプション

# TurboSnapを有効にして実行
npx chromatic --only-changed

# mainブランチでは自動承認
npx chromatic --auto-accept-changes="main"

TurboSnap（高速化機能）

TurboSnapは、変更のあったファイルに関連するストーリーのみテストする機能です。ビルド時間とスナップショット消費を大幅に削減します。

GitHub Actions での設定

- uses: chromaui/action@latest
  with:
    projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
    onlyChanged: true
    externals: "public/**"  # 静的ファイルの変更も検知

.gitignore に追加

Chromaticのビルドログや一時ファイルをバージョン管理から除外します。

# Chromatic
build-storybook.log
chromatic.log
chromatic-build-*.xml
storybook-static/

料金プラン

セットアップチェックリスト

参考文献

• Chromatic Setup Guide
• Chromatic Quickstart
• Automate Chromatic with GitHub Actions
• Configuration Reference
• chromaui/action - GitHub

まとめ

Chromaticを導入することで、UIの意図しない変更を自動的に検出し、チーム内でのUIレビューを効率化できます。TurboSnapを活用すれば無料枠でも十分に運用可能です。GitHub Actionsとの連携により、PRごとにビジュアルテストが自動実行される仕組みを構築できます。