mcpField
U
update-storybook-snapshots

update-storybook-snapshots

github.com/cartridge-ggテスト・品質8036 回インストール7 週間前に更新
リポジトリ

update-storybook-snapshots について

update-storybook-snapshotsは、Storybookのビジュアル回帰テスト用ベースラインを管理するスキルです。UIコンポーネントの開発者向けに、差分確認、スナップショット更新、結果検証、一般的な問題への対処を説明します。

主な機能

  1. 01Storybookスナップショットテストの実行
  2. 02期待画像と実際の画像差分の確認
  3. 03スナップショットベースラインの再生成
  4. 04変更内容の確認とスナップショットのコミット
  5. 05タイムアウトや環境差のトラブル対応

活用シーン

  1. 01意図的なスタイル変更後のベースライン更新
  2. 02新しいコンポーネントのスナップショット作成
  3. 03デザインシステム更新後の視覚変化の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/cartridge-gg/controller --skill update-storybook-snapshots

インストール後、Claude Code で/update-storybook-snapshotsを入力して読み込まれたか確認します。

詳細

Storybook スナップショットを更新する

概要

Storybook スナップショットは、ビジュアルリグレッションテストで使用するベースライン画像です。UI コンポーネントを意図的に変更した場合、新しい想定表示を反映するためにスナップショットを更新する必要があります。

スナップショットを更新するタイミング

次の場合にスナップショットを更新してください：

  • コンポーネントのスタイルを意図的に変更した
  • ストーリーを持つ新しい UI コンポーネントを追加した
  • コンポーネントのレイアウトや構造を変更した
  • デザインシステムの更新がコンポーネントの表示に影響した

次の場合はスナップショットを更新しないでください：

  • UI を意図的に変更していない
  • ビジュアル差分にバグやリグレッションが示されている
  • 表示が変わった理由が分からない

更新手順

ステップ 1：テストを実行して失敗を確認する
pnpm test:storybook

失敗したスナップショットを確認してください。失敗すると差分画像が生成されます。

ステップ 2：差分画像を確認する

差分画像は次の場所に保存されます：

packages/keychain/__image_snapshots__/__diff_output__/

各差分画像には次の内容が表示されます：

  • 左：期待される表示（ベースライン）
  • 中央：強調表示された差分
  • 右：実際の表示（現在）

続行する前に、変更が意図したものであることを確認してください。

ステップ 3：スナップショットを更新する
pnpm test:storybook:update

これにより、現在のコンポーネントのレンダリング結果に基づいて、すべてのスナップショット画像が再生成されます。

ステップ 4：更新後のスナップショットを確認する

更新された画像に問題がないことを確認してください：

# List changed snapshot files
git status packages/*/__image_snapshots__/

# View specific changes (if you have an image viewer)
ls packages/keychain/__image_snapshots__/*.png
ステップ 5：更新内容をコミットする
git add packages/*/__image_snapshots__/
git commit -m "chore: update storybook snapshots"

スナップショットの保存場所

packages/keychain/__image_snapshots__/
├── components-*.png           # Component snapshots
├── __diff_output__/           # Diff images (not committed)
│   └── *-diff.png

よくあるケース

新しいコンポーネントを追加した場合
  1. コンポーネントを作成する
  2. packages/keychain/src/components/ に Storybook ストーリーを追加する
  3. pnpm test:storybook:update を実行して初期スナップショットを生成する
  4. コンポーネントとスナップショットの両方をコミットする
テーマ／デザインシステムを更新した場合

デザイントークンやテーマの変更が複数のコンポーネントに影響する場合：

# Update all snapshots at once
pnpm test:storybook:update

# Review all changes
git diff --stat packages/*/__image_snapshots__/

# Commit with descriptive message
git add packages/*/__image_snapshots__/
git commit -m "chore: update snapshots for design system changes"
CI による自動更新

CI ワークフロー（test.yml）では、スナップショットを自動更新してプッシュできます：

  • PR ブランチで実行されている場合
  • 失敗がビジュアル差分のみの場合
  • "chore: update storybook snapshots" というコミットを作成します

つまり、ビジュアルに影響する変更をプッシュすると、CI が PR に更新済みスナップショットを自動コミットする場合があります。

トラブルシューティング

テストがタイムアウトする

Storybook が起動できる必要があります：

# Kill any existing Storybook process
pkill -f storybook

# Ensure port 6006 is free
lsof -i :6006

# Try running Storybook manually first
pnpm storybook
スナップショットに一貫性がない

ローカルと CI でスナップショットが異なる場合：

  • 同じ Node バージョン（20.x）を使用していることを確認してください
  • フォントのレンダリングはプラットフォームによって異なる場合があります
  • 一貫性を保つため、CI では特定の Docker イメージを使用します
依存関係が不足している
pnpm clean && pnpm i && pnpm build:deps

スクリプトヘルパー

ヘルパースクリプトも利用できます：

./scripts/update-storybook-snapshot.sh

ベストプラクティス

  1. すべての差分を確認する - スナップショットをむやみに更新しないでください
  2. 小さなコミットにする - スナップショットは個別のコミットで更新してください
  3. 内容が分かるメッセージにする - 大きな変更の場合は、何を変更したかを記載してください
  4. クリーンなベースラインを保つ - 差分画像はコミットしないでください（gitignore 対象です）
  5. CI との一貫性を保つ - ローカルでは成功して CI で失敗する場合は、差異を調査してください

コメント

Markdown 対応