解決できる課題 事業紹介トップ 経営データ分析基盤 AI導入・業務改善 AI 業務アプリ 基幹システムのWeb化・段階移行 複雑な SaaS を専用 UI に Shopify Plus 移行・拡張 生成AI 活用(Multi AI) SEO / AIO / 広告運用 顧問・アドバイザリ インフラ構築 PHP脆弱性対策・更新 WordPressからEmDashへの移行 自社メディア投資・開発
AI導入 AI導入・業務改善 ChatGPTの社内導入 OpenAI Codex導入 AI運用・定着 Claude / MCP 総合 Claude Cowork Claude Code 導入支援 Claude Code 使いこなし支援 Claude Design MCP 開発・サーバー構築
EC構築・移行 Shopify Plus トップ EC-CUBEからShopifyへの移行 大手カートからの移行 Shopify 通常プラン EC サイト構築
実績
業界ニュース 業界ニュース トップ AI ニュース └ Claude └ ChatGPT・Codex └ Gemini └ その他 Shopify ニュース SaaS ニュース お知らせ(自社発信)
会社情報 相談する
2026.10.31

ChromaticのコストをTurboSnapで削減する——全件撮影が起きる原因と対策

記事のサマリー(TL;DR)

  • SmartHRの給与計算機能チームは、Chromaticを使ったVRT(Visual Regression Testing)で、約720個あるストーリーをストーリーの変更と無関係にすべて撮影し直すビルドが半分近くあることに気づきました。原因はテストの範囲の広さではなく、TurboSnapが効かず全件撮影(Bail)になることと、実行の重複でした。
  • 給与計算機能では、全件撮影になるビルドの割合が、8月期(7月11日〜8月10日)の43.1%から、2つの対策(previewの依存削減、feature flagの対応)を入れたあとの9月29日〜10月10日には8.5%まで下がりました。あるビルドでは撮影枚数が720枚から20枚になりました。
  • 記事では、Chromaticの課金の仕組み、TurboSnapがBailする主な理由(changedStorybookFiles、changedPackageFiles)、不要な全件撮影を減らす対策、撮影対象の判定を正しくする対策、重複した実行を減らす対策、撮影の粒度の設計について、給与計算機能および社内の他チームの事例とあわせて紹介しています。

詳細

VRTとChromatic、TurboSnapの仕組み

VRTは、UIのスクリーンショットを前回のものと比較し、見た目の意図しない変化を見つけるテストです。CSSの修正やライブラリのアップデートによる画面崩れを、手作業の確認に頼らずに検知できます。

Chromaticは、Storybookのストーリーを撮影し、前回との差分をレビューできるサービスで、Storybookのメンテナーが開発しています。Pull Requestごとに撮影を実行し、差分があれば画面上で確認・承認する流れでVRTを運用できます。SmartHRでのVRT導入については、過去の記事でも紹介されています。

Chromaticは、ビルドのたびにストーリーを撮影し、祖先にあたるビルドのスナップショットと比較して差分を検出します。何もしなければ、ビルドのたびに全ストーリーを撮影することになります。

TurboSnapは、この撮影を必要なストーリーだけに絞るChromaticの機能です。変更されたファイルからimportの依存をたどり、影響を受けるストーリーだけを撮影します。影響を受けないストーリーは、前のビルドのスナップショットをコピーして使います。

ただし、TurboSnapは条件によっては依存をたどるのをあきらめて全ストーリーを撮影します。これを「Bail」と呼びます。Bailの理由はいくつかあり、記事で主に扱うのは次の2つです。

  • changedStorybookFiles:.storybook/配下のファイル(preview.tsxなど)か、その依存に含まれるファイルが変更された場合
  • changedPackageFiles:package.jsonやlockfileが変更され、依存しているパッケージが変わった可能性がある場合

このほか、比較の基準になる祖先のビルドが見つからない場合などにもBailします。記事で紹介する対策の多くは、Bailにつながる経路を減らすためのものです。

Chromaticのコストの課題

Chromaticの課金は、スナップショットの枚数で決まります。実際に撮影したスナップショットは1枚として数え、TurboSnapで前のビルドからコピーしたスナップショットは0.2枚として数えます。TurboSnapが効いていれば、同じストーリー数でもコストを大きく抑えられますが、Bailが多ければ毎回ほぼ全件を撮影することになります。

給与計算機能では、8月期(7月11日〜8月10日)の555件のビルドのうち239件(43.1%)がchangedStorybookFilesでBailしていました。9月期(8月11日〜9月10日)は600件のうち316件(52.7%)です。このあと紹介する対策を入れた10月期(9月11日〜10月10日)には、この割合は29.9%まで下がりました。9月11日にpreviewの依存を減らす対応を、9月28日にfeature flagの対応を入れています。

previewの依存を小さく、変わりにくくする

給与計算機能で最も多かったのは、changedStorybookFilesによるBailでした。TurboSnapは、変更されたファイルからimportの関係をさかのぼり、.storybook/配下のファイルにたどり着いた時点でBailします。つまり、preview.tsxが直接または間接的にimportしているファイルは、どれを変更しても全件撮影の原因になります。

preview.tsxは、すべてのストーリーに共通する設定を書くStorybookの設定ファイルです。ここでよく使われるのがdecoratorで、Providerやレイアウトなどストーリーの描画に必要なものを足すために使われます。preview.tsxで指定したdecoratorは全ストーリーに適用され、ストーリーのファイルで指定したdecoratorはそのストーリーにだけ適用されます。

給与計算機能のpreview.tsxは、Headerコンポーネントや、SmartHR UIを再exportしているプロダクト内のbarrelをimportしていました。その先をたどると、認証の処理やOpenAPIから生成したAPIクライアントまで、preview.tsxの依存に含まれていました。依存は558ファイルあり、そのうち504ファイルが生成したコードでした。APIのスキーマを変更してコードを生成し直すたびに、全件撮影になっていたことになります(依存のファイル数は、Storybookをビルドするときにwebpackのstatsを出力し、preview.tsxからたどれるモジュールを数えて調べたものです)。

そこで、preview.tsxからアプリケーション本体のコードへの依存を必要最小限まで減らしました。依存を広げていたのは、preview.tsxのdecoratorで使っていた3つのコンポーネント、多言語化用のIntlProvider、バリデーションライブラリZodの設定を行うZodCustomizer、画面上部のHeaderで、それぞれ次のように修正しました。

  • IntlProviderは、プロダクト内のbarrelではなく、smarthr-uiパッケージから直接importする
  • ZodCustomizerは、RootLayoutのbarrel経由ではなく、実体のファイルから直接importする
  • Headerはグローバルなdecoratorから外し、ページ全体を撮影するストーリーにだけ適用する

注意点として、preview.tsxのimport文だけを直しても不十分なケースがありました。Headerのコンポーネント自身がbarrelをimportしていたため、preview.tsx→Header→barrelという経路で依存が残ってしまいます。Headerをpreview.tsxから外すことと、セットで対応する必要がありました。また、Headerを適用するdecoratorは.storybook/ではなくsrc/配下に置きました。.storybook/配下のファイルは変更するだけでBailの原因になるため、共有するコードをそこに置くと同じ問題が再発するからです。

この対応で、preview.tsxの依存は558ファイルから14ファイルに減りました。撮影するストーリーは1つも減らしていません。あるビルドでは、それまで全件撮影になっていた変更で、撮影枚数が720枚から20枚になりました。

社内の他チームでも同様の対策が行われており、preview.tsxでグローバルに登録していたMSW(Mock Service Worker)のハンドラーを外し、必要なストーリーにだけ個別に登録するようにしたチームもあります。

feature flagの一覧をpreviewに持ち込まない

preview.tsxの依存を減らしたあとも、給与計算機能にはBailの原因が残っていました。5月期から8月期にマージされたPull Requestで試算すると、この対応のあとでもBailするものが38件あり、そのうち32件がfeature flagの追加や削除によるものでした。

feature flagは、機能の公開をコードのデプロイと切り離し、フラグの値で出し分ける仕組みです。開発途中の機能をフラグでオフにしたままマージしておき、準備ができたらオンにして公開します。そのため開発が進むたびに、フラグは増えたり消えたりします。

コンポーネントはフラグの値を見て表示を変えるため、Storybookのストーリーにもフラグの値が必要です。給与計算機能では、すべてのフラグの既定値を並べた一覧をモック用のファイルに用意し、preview.tsxでそれを読み込んで全ストーリーに渡していました。この一覧のファイルはpreview.tsxの依存に含まれるため、フラグを1つ追加するたびに全件撮影になっていました。

そこで、preview.tsxでは一覧を持たず、ストーリーが指定しなかったフラグをfalseとして扱うようにしました。Proxyを使い、存在しないキーにアクセスされたらfalseを返す実装です。給与計算機能では、もともとすべてのフラグの既定値がfalseだったため、この変更で描画は変わりません。

なお、一覧をpreview.tsxの中にコピーして持つ方法も考えられますが、それではフラグを増やすたびに.storybook/配下のファイルを編集することになり、結局Bailしてしまいます。一覧そのものを持たない形にして、初めて「フラグを増やしても全件撮影にならない」状態になります。

この対応で、preview.tsxの依存は14ファイルから9ファイルに減りました。対応を入れる前の9月18日〜27日は、35件のビルドのうち12件(34.3%)がBailしていました。対応を入れた翌日からの9月29日〜10月10日は、129件のうち11件(8.5%)です。対応前の期間はビルド数が少ないため、目安として示されています。前述のグラフの10月期の29.9%より低いのは、10月期にはfeature flagの対応を入れる前のビルドも含まれているためです。

依存更新による全件撮影の原因を調べる(社内他チームの事例)

preview.tsxの依存を減らしてchangedStorybookFilesのBailがほぼなくなった一方で、changedPackageFilesによるBailが増えていた事例があります。

このリポジトリは、1つのリポジトリに複数のpackage.jsonがあるmonorepo構成で、Storybookも複数のディレクトリにあり、Chromaticのワークフローもそれぞれ分かれています。問題になったのはclient/のStorybookを撮影するワークフローで、一方lockfileのpnpm-lock.yamlはリポジトリ全体で1つです。

TurboSnapは、package.jsonが変更されると、本来はlockfileを解析して依存しているパッケージが実際に変わったかを判定しますが、lockfileを解析できないとpackage.jsonが変更されただけでBailします。このリポジトリではlockfileを解析できず、package.jsonの変更で判定する動きになっていました。そのため、client/と関係ないディレクトリのpackage.jsonを変更しただけでも、client/のStorybookが全件撮影になっていました。ある3日間のstagingブランチの実行を調べると、150回のうち62回が依存の更新による全件撮影で、そのうち25回はclient/と関係ないpackage.jsonの変更によるものでした。

対策として、client/の外にあるpackage.jsonだけを、TurboSnapが変更を無視するuntracedに指定しました。client/package.jsonとpnpm-lock.yamlはあえて残しています。これらまで無視すると、SmartHR UIのようなライブラリをアップデートしたときの見た目の変化を見逃してしまうためです。

ここから分かるのは、一度Bailを減らしても、それで終わりではないということです。ある原因を潰すと別の原因が目立つようになるため、Bailの理由ごとに件数を見続ける必要があります。

撮影する変更と範囲を正しく判定する

TurboSnapで必要なストーリーだけを撮影するには、比較するコミットや、変更の影響を判定する設定も重要です。判定が適切でないと、不要な撮影が増えたり、必要な撮影が漏れたりします。

撮影するコミットを正しくする

Pull Requestのビルドで、本来の変更よりも広い範囲が撮影されていたリポジトリもありました。原因は2つで、1つはGitHub Actionsでcheckoutするrefを指定しておらず、Pull Requestの一時的なmergeコミットを撮影していたこと、もう1つはCIの中でgit mergeをしていて変更されたファイルの集合が広がっていたことです。

対策として、checkoutでPull Requestのheadのコミットを明示し、変更の判定にはgit mergeではなくgit diff origin/<base>...HEADを使うようにしました。撮影するコードのコミットと、Chromaticに伝えるコミットの情報がそろっているかは、確認しておくとよいとされています。

untracedとexternalsの設定が効いているかを確かめる

TurboSnapの判定は、untracedとexternalsという2つの設定で調整できます。untracedは変更されても無視するファイルの指定、externalsはimportの依存をたどれないものの変更されたら全件撮影すべきファイルの指定です。どちらも、記述しただけでなく実際に効いているかを確かめる必要があります。

Pull Requestの一時的なmergeコミットを撮影していたリポジトリでは、untracedを記述していたのに効いていませんでした。原因は次の2つです。

  • untracedのパスは、working directoryではなくリポジトリのルートを基準にして書く必要があるのに、frontend/が抜けていた
  • ChromaticのGitHub Actionの入力は改行区切りなのに、複数のパスをスペース区切りで書いていた。そのため、スペースを含む1つのglobとして解釈されていた

一方、別のリポジトリでは、撮影されるべき変更が撮影されていなかったこともありました。グローバルなCSSを変更したのに、影響するストーリーが0件と判定され、1,042枚すべてが撮影されなかったケースです。このリポジトリでは、グローバルなCSSやTailwind CSSの設定が、ストーリーからたどれるimportの依存に入っていなかったため、それらのファイルをexternalsに指定し、変更されたら全件撮影するようにしていました。

どちらの問題も、設定ファイルを読んだだけでは気づきにくいものです。ChromaticのCLIのログには、どのファイルの変更でBailしたかが出力されるため、ログを見て判定が意図どおりかを確かめることが推奨されています。

重複した実行を減らす

全件撮影でなくても、同じ内容を何度も撮影していればコストは増えます。

同じコミットを2回撮影しない

同じコミットを2回撮影していたリポジトリもありました。そこでは、stagingからmainへのリリース用のPull Requestが常に開いており、stagingブランチにマージすると、stagingへのpushと、リリース用のPull Requestの更新の両方でChromaticが走っていました。対策として、リリース用のPull Requestでの実行をスキップするようにしています。CIのトリガーが増えてくると役割が重なっている実行に気づきにくくなるため、どのイベントでChromaticが走っているかを見直すことが有効とされています。

必要なときだけ実行する

Chromaticを走らせる必要がない変更であれば、そもそも実行しないのが一番です。たとえば、フロントエンドのテストファイルだけを変更したときはVRTを実行しないようにしているチームがありました。ただし、Storybookが読み込むfixtureやモック、play functionまでテスト扱いで外してしまうと、見た目の変化を見逃すことになるため、外すのは描画に影響しないファイルだけにしています。

給与計算機能では、DraftのPull Requestでは、run-chromaticというラベルを付けたときだけChromaticを実行する運用にしています。開発の途中でコミットを積むたびに撮影していると、それだけでコストがかかるためです。ただし、実行をopt-inにすると、Chromaticを走らせないままマージしてしまうおそれがあるため、これを防ぐためにラベルを付けたときにもワークフローが起動するようにし、レビューの前に必ずVRTが走っていることを確かめるようにしたチームもあります。実行を減らすならば、必要なVRTが走らないままマージされない仕組みもセットで用意しておく必要があるとされています。

撮影の粒度を設計する

撮影の粒度は撮影枚数に直接影響します。ストーリーの数や画面幅などのバリエーションを増やすほど、撮影枚数も増えるためです。

撮影の粒度を見直した例として、ほかのテストで見た目を確認できているストーリーを整理したチームがあります。たとえば、ローカルで動かしている別のVRTですでに比較している状態のストーリーには、disableSnapshot: trueを付けてChromaticでは撮影しないようにしています。一方で、そのストーリー自体はローカルのVRTが参照しているため、削除はしていません。ここでは、「どのテストを消すか」ではなく「どの見た目を、どのテストで守るか」から検討されています。

まとめ

Chromaticのコストを下げる際にまず減らすべきなのは、テストの範囲ではなく不要な全件撮影と重複した実行です。ただし、減らしすぎると撮影されるべき変更まで見逃してしまうため、撮影が減ったときはそれが正しいのかもあわせて確認する必要があります。

効果を測る際は、月ごとの総量だけでなく、Bailの理由ごとの件数や、1ビルドあたりの課金対象枚数も見ることが推奨されています。給与計算機能では、10月期の課金対象の枚数が8月期より37.2%減りました。ただし、同じ期間にビルド数も555件から328件に減っており、1ビルドあたりの枚数で見ると343.8枚から365.1枚とむしろ増えています。この期間にはストーリー数も増えており、1ビルドあたりの課金対象枚数を押し上げた要因の1つと考えられています。総量の減少がすべて対策の効果とはいえないため、Bailの割合のような対策と結びつきやすい数字や、撮影対象の規模の変化もあわせて確認されています。

TurboSnapについては、Chromaticの公式ドキュメントにもベストプラクティスがまとめられており、記事で紹介された対策と重なる部分も多いとされています。

ただし、こうした対策を続けても、コストの問題が根本から解決するわけではないとされています。給与計算機能のチームを含め、社内の各所でChromaticのコストを下げる取り組みが進んでいる一方、SmartHRではプロダクトが増え続けており、それぞれのプロダクトでも開発が進むたびにストーリーが増えていきます。撮影枚数で課金される以上、無駄な撮影を減らしてもストーリーが増えるぶんコストは増えていくため、現在はUIのリグレッションを防ぎつつ、ストーリーが増えてもコストが増えにくい方法が模索されています。例として、全ストーリーを撮影する前提からVRTの対象や粒度を見直すことや、OSSを使った自前のVRTの仕組みに移ることも選択肢の1つとして挙げられています。