Chromaticとは？Storybook連携のビジュアルテスト自動化と料金・TurboSnapを解説

Chromaticは、Storybookに書いたストーリーをクラウド上のブラウザで撮影し、前回の承認済み画像との差分を検出するビジュアルテストのSaaSです。運営元は公式サイトのフッターに「© Chroma Software Inc. Made by the maintainers of Storybook.」と明記されているとおり、Storybookそのものを保守しているチームです。一方で「chromatic」という語は音楽用語や画像処理プラグインの名前としても流通しており、検索結果には別分野の対象が混ざります。ここでは開発ツールとしてのChromaticに絞り、導入手順・Modes API・料金の数え方・見送るべき条件までを公式ドキュメントの記述に沿って整理します。

まとめ：Chromaticの要点

先に結論を挙げます。ChromaticはStorybook開発元が提供するビジュアルテストSaaSで、npx chromatic --project-token の1コマンドから始められます。ストーリーごとの撮影結果を承認・却下していく運用が中核で、承認済みの画像がベースラインになります。

Storybook側の書き方そのものはStorybookの使い方とNext.js連携の手順にまとめてあります。以降はChromatic固有の設定と、課金スナップショットをどう見積もるかを掘り下げます。

Chromaticの正体と、同名の別対象との見分け方

「chromatic」で検索すると、開発ツール以外の同名製品や音楽用語も同じページに並びます。何が混ざるのかを先に押さえておくと、社内で情報を共有するときの混乱を避けられます。

Storybookの開発元が運営するビジュアルテストSaaS

公式のクイックスタートは「Chromatic, created by the team behind Storybook」と書き出しています。つまりStorybookのアドオンを第三者が作ったものではなく、Storybook本体を保守している法人の商用サービスです。ストーリーをテストケースとして扱い、ビジュアルテスト・インタラクションテスト・アクセシビリティテストをCIで実行し、承認フローをPull Requestのチェックに紐づけます。npmパッケージ chromatic の最新版は18.7.2（2026年8月31日公開）、Storybook用アドオン @chromatic-com/storybook は5.3.1（2026年9月2日公開）です。

検索結果に混ざる別分野の「chromatic」

日本語の検索結果でこの語を引くと、開発ツール以外の対象が同じ1ページ目に並びます。導入検討の資料を集めるときは、次の対象を除外して読むと早く済みます。

色収差を意味する chromatic aberration が語源を共有しているため、画像・映像分野の製品名に採用されやすいという事情があります。社内の検索や課題管理で「Chromatic」とだけ書くと取り違えが起きるので、ツール名は「Chromatic（Storybook）」と併記しておくのが安全です。

Storybook連携で自動化される検証の中身

ビジュアルテストとベースライン承認の流れ

初回ビルドで各ストーリーを撮影し、それがベースラインになります。次のビルドからは新しいスナップショットがベースラインと比較され、差分が出たテストが「Tests」テーブルに並びます。ここで承認すればベースラインが更新され、ブランチをまたいでも再承認は不要です。却下するとビルドは失敗し、そのストーリーは次回ビルドで必ず再撮影されます（TurboSnapのスキップ対象であっても再撮影されるという例外が公式ドキュメントに明記されています）。この「差分を人が承認する」点が、期待値ファイルをリポジトリに置くJestやVitestのスナップショットテストとの最大の運用差です。

インタラクションテストとアクセシビリティテスト

ストーリーのplay関数を使ったインタラクションテストと、axeベースのアクセシビリティテストを同じビルドで実行できます。アクセシビリティ側は、ページ単位ではなくコンポーネント単位で検査してWCAG違反の発生源を特定しやすくする設計です。ページ単位の検査では違反が数千件並んだうえで原因コンポーネントを探す作業が発生する、という問題意識が公式ドキュメントに説明されています。

ローカルで回すVisual Tests addon

npx storybook@latest add @chromatic-com/storybook でアドオンを入れると、Storybookのサイドバーの再生ボタンからその場でビジュアルテストを実行できます。Storybook 7.6以上が要件です。CIに上げる前に差分を潰せるので、レビュー待ちの往復が減ります。Storybook本体を開発サーバーの脆弱性CVE-2026-114125の修正版へ上げるときに、このアドオンに求められるバージョンはStorybookの脆弱性CVE-2026-114125とはで整理しています。

導入手順：CLIのインストールからCI連携まで

パッケージ導入と初回ビルド

Chromaticにサインインしてプロジェクトを作るとプロジェクトトークンが発行されます。あとはCLIを入れて実行するだけで、Storybookのビルドとアップロードまで自動で進みます。要件はStorybook 6.5以上です。

npm install --save-dev chromatic
npx chromatic --project-token <your-project-token>

CLIは既定で package.json の build-storybook スクリプトを使います。storybook スクリプト側に静的ディレクトリ指定などのカスタマイズを入れている場合は、build-storybook にも同じ指定を反映しておかないとビルド結果がずれます。

設定ファイルと環境変数

プロジェクトルートの chromatic.config.json に設定を置くのが公式の推奨です。CLIフラグはケバブケース、設定ファイルのキーはキャメルケースで、両方に同じ項目があるときはフラグが優先されます。トークンは CHROMATIC_PROJECT_TOKEN 環境変数から読ませ、CI側のシークレットに置くとリポジトリに残りません。

{
  "$schema": "https://www.chromatic.com/config-file.schema.json",
  "projectId": "Project:...",
  "onlyChanged": true
}

実行時のログや診断ファイルはリポジトリに入れる必要がないため、build-storybook.log、chromatic.log、chromatic-build-*.xml、chromatic-diagnostics.json を .gitignore に加えておきます。

GitHub Actionsでの実行

steps:
  - name: Run Chromatic
    uses: chromaui/action@latest
    with:
      projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}
      onlyChanged: true

GitやCIのプロバイダがChromaticの連携対象外の場合は「unlinked project」として作成できますが、Pull Requestへのステータス表示が自動では付かず、ユーザー招待によるアクセス制御も手動になります。GitHub・GitLab・Bitbucketを使っているなら連携プロジェクトを選んだほうが運用は軽くなります。

Storybookを使わない構成での連携

Vitest・Playwright・Cypressのテスト実行中にDOM・スタイル・アセットのアーカイブを取得し、それをクラウドで描画してビジュアルテストにかける経路も用意されています。CLIに対応フラグを渡すだけです。

npx chromatic --project-token <token> --vitest
npx chromatic --project-token <token> --playwright
npx chromatic --project-token <token> --cypress

この経路では chromatic パッケージを開発依存として入れることが推奨されています。@chromatic-com/vitest などの各パッケージとCLIのバージョンを揃える必要があるためで、npxで都度最新版を落とす運用だと組み合わせがずれます。E2E側の書き方はVRT（Visual Regression Testing）の主要ツールとPlaywright実装で扱っています。

Modes APIによるビューポート・テーマ・ロケール検証

chromatic.viewportsがlegacy扱いになった

幅ごとの撮影に使われてきた chromatic.viewports は、公式ドキュメント上で「The chromatic.viewports feature is now replaced by the new Modes API.」と警告付きで案内される旧APIになりました。数年前の日本語記事はほぼこの旧APIで書かれているため、そのまま写すと現行の推奨から外れます。旧APIには高さを指定できないという制約もあり、幅は200から2560ピクセルの整数、1スナップショットあたりの上限は25,000,000ピクセルという条件で動きます。

modes.tsに定義してchromatic.modesで適用する

現行のModes APIは、ビューポート・テーマ・ロケールといったStorybookのグローバル設定の組み合わせに名前を付けて、ストーリーに適用する仕組みです。.storybook/modes.ts に定義をまとめ、ストーリーファイルから参照します。

// .storybook/modes.ts
export const allModes = {
  mobile: { viewport: 'small' },
  desktop: { viewport: 'large' },
  'dark desktop': { backgrounds: { value: '#1E293B' }, theme: 'dark', viewport: 'large' },
} as const;

// ArticleCard.stories.ts
import { allModes } from '../.storybook/modes';

const meta = {
  component: ArticleCard,
  parameters: {
    chromatic: {
      modes: {
        mobile: allModes.mobile,
        'dark desktop': allModes['dark desktop'],
      },
    },
  },
} satisfies Meta<typeof ArticleCard>;

モードごとに独立したベースラインと承認が発生します。Storybook 6.0以上が要件で、モードの実体はStorybookのglobalsとデコレータなので、テーマ切り替えなら @storybook/addon-themes のようなアドオンを preview 側に設定しておく必要があります。

モードは上書きされず積み上がる

ここは請求額に直結するので注意が要ります。モードはプロジェクト（preview）・コンポーネント・ストーリーの3階層で指定できますが、下位の指定が上位を上書きするのではなく、すべてが1つのスタックに合成されます。プロジェクト全体にlightとdarkを設定したうえでコンポーネントにmobileを足すと、そのコンポーネントは3モード分テストされます。ストーリー2本にモード2種類なら4テスト、という数え方です。デザインシステムの構成要素を全コンポーネントで多モード検証する構成は、この掛け算がそのままスナップショット数になります。

料金プランと課金スナップショットの数え方

以下は2026年9月8日時点のChromatic公式の料金ページの記載です。金額と枠は改定されるため、契約前に最新の条件を確認してください。

4プランの内訳

すべてのプランでプロジェクト数・ユーザー数・共同編集者数・並列テスト実行数が無制限で、課金対象はスナップショットの枚数だけです。無料プランがChromeのみである点は見落としやすく、SafariやFirefoxでの表示崩れを検知したい場合はStarter以上が要件になります。

TurboSnapで課金スナップショットを減らす条件

TurboSnapはGit差分とバンドラの依存グラフを突き合わせ、変更の影響を受けるストーリーだけを撮影し直します。影響のないストーリーはベースラインからコピーされ、これがturbosnapとして課金上は軽く扱われます。公式の料金表では5,000課金スナップショットが25,000turbosnap相当、35,000が175,000相当と併記されており、turbosnap 5枚が課金スナップショット1枚に相当する換算です。

有効化はCLIに --only-changed を渡すか、設定ファイルの onlyChanged を true にします。ただし最初から使えるわけではなく、公式は「TurboSnap is unlocked after ten successful builds on CI.」として、CI上で10回ビルドが成功するまで解放しないと明言しています。ほかの前提はCLI 10.0以上、Storybook 6.5以上またはVitest 4以上、Git 2.28.0以上、WebpackかVite製のプロジェクトです。

依存グラフ上の変更が皆無で、祖先ビルドが1つだけといった条件をすべて満たすビルドは「bypassed」となり、課金スナップショットがゼロになります（CLI 17.7.0以降）。逆に、判定材料は依存グラフだけなので、ストーリーが読み込むCSSファイルにコメントを1行足しただけでも撮影は走ります。マージコミットは祖先ビルドが2つあるため対象外です。

導入を見送るべき場面と、費用が跳ねる失敗パターン

導入をおすすめできない条件がはっきりしているツールなので、そこを先に確認してください。

まず、Storybook経由で使う場合、ストーリーが十分に整備されていない段階では効果が出ません。この経路で撮影されるのはストーリーとして切り出された状態だけなので、ストーリーが薄ければ差分も出ません。この段階では、先に主要な状態をストーリーとして定義するか、前章の --vitest・--playwright・--cypress 連携で既存のテストから始めるほうが現実的です。

次に、コンポーネント単位ではなく画面単位の崩れだけを検知したい場合、Chromaticは過剰です。Playwrightのスクリーンショットアサーションなどでリポジトリ内で完結するリグレッションテストを組むほうが費用も運用も軽く済みます。

費用面の失敗パターンは掛け算の見落としです。課金スナップショットはストーリー数×モード数×ブラウザ数で増えます。200ストーリーに対してモードを2つ、ブラウザを2つ設定すると1ビルドで800枚となり、1日3ビルド・月20営業日ならおよそ48,000枚に達してStarterの35,000枚を超えます。モードをプロジェクト階層に置くと全コンポーネントに乗る点も合わせて、階層ごとの指定を先に設計してください。

もう1つ多いのが、フルリビルドを毎回誘発する構成です。preview.js がバレルファイル経由で多数のモジュールを読み込んでいると、無関係なファイルの変更でも全ストーリーが依存扱いになり、TurboSnapが効きません。有効なロックファイルが無い状態で package.json の依存バージョンが変わった場合も、同様に全撮影になります。Storybookの設定変更、静的ディレクトリの変更、新しいブラウザでのテスト追加も、仕様上フルリビルドの対象です。

よくある質問

Chromaticの無料プランでどこまで使えますか？

月5,000枚の課金スナップショットまで、テスト対象ブラウザはChromeのみという条件で使えます。クレジットカード登録は不要で、プロジェクト数・ユーザー数・共同編集者数・並列テスト実行数に制限はありません。SafariやFirefox、Edgeでのテストは$179のStarter以上が必要です。

chromatic.viewportsは今も使えますか？

動作はしますが、公式ドキュメントでlegacy扱いになりModes APIへの移行が案内されています。高さを指定できないなどの制約は解消されないため、新規に設定するならModes API、既存の設定は移行ガイドに沿って書き換えるのが妥当です。

Storybookを使っていなくても導入できますか？

できます。CLIに --vitest、--playwright、--cypress のいずれかを渡すと、それぞれのテスト実行中に取得したUIのアーカイブをクラウドで描画してビジュアルテストにかけます。この場合はCLIと対応パッケージのバージョンを揃えるため、chromatic を開発依存としてインストールしてください。

TurboSnapは最初のビルドから有効にできますか？

できません。設定が複雑で切り分けが難しくなることを理由に、CI上で10回ビルドが成功するまで解放されない仕様です。まずは既定の挙動で運用を安定させ、そのあとで --only-changed を足す順序になります。

検索すると音楽用語や画像処理の製品が出てくるのはなぜですか？

chromaticが「色彩の」「半音階の」を意味する英単語で、色収差（chromatic aberration）を含む語としても使われるためです。日本語の検索結果には英和辞書、LANDR Chromaticのような音楽制作プラグイン、色収差を再現する映像用プラグインが同居します。開発ツールを指すときは「Chromatic（Storybook）」と併記すると誤解を避けられます。

関連記事

• Storybookとは？使い方・Next.js連携・テスト・費用まで実装手順で解説
• VRT（Visual Regression Testing）とは？必要性・メリットと主要ツール・Playwright実装をわかりやすく解説
• スナップショットテストとは？JestとVitestの実装と更新運用を実装者向けに解説
• リグレッションテスト（回帰テスト）とは？目的・範囲選定・自動化と実施判断を解説
• デザインシステムとは？構成要素・作り方とデザインガイドラインとの違いを解説