test

適切なビジュアルリグレッション、インタラクションテスト、アクセシビリティのアサーションを組み合わせ、UI の動作に対する体系的な信頼を築きます。

テストはリリース後の安全網ではなく、設計時のインプットとして扱います。目標はカバレッジの最大化ではありません。チームをメンテナンスに追われさせることなく、重要なバグを見つけることです。

テスト戦略で自動化された axe チェック、スクリーンリーダーによる検証、またはキーボード操作のテストが必要な場合は、アクセシビリティテストのリファレンスを参照してください。 カスタムコンポーネントのフォーカス管理、ARIA の正確性、キーボード操作をテストする場合は、コンポーネントのアクセシビリティのリファレンスを参照してください。 ストレス時、エラー時、またはエッジケースの条件下でワークフローを検証する場合は、インタラクションデザインのリファレンスを参照してください。 バリデーション動作、回復可能なフィールドエラー、または離脱経路をテストする場合は、エラーからの回復のリファレンスを参照してください。 ローディング状態、スケルトン、古いデータを示す表示、または知覚パフォーマンスの動作をテストする場合は、ローディングフィードバックと知覚パフォーマンスのリファレンスを参照してください。

必須の準備

ユーザーは /test を使ってこのワークフローを開始します。このスキルが有効になったら、$frontend-design を読み込んでください。ここには設計原則、アンチパターン、Context Gathering Protocol が含まれています。先に進む前に、このプロトコルに従ってください。設計コンテキストがまだ存在しない場合は、必ず先に $setup を読み込んでください。さらに、現在、本番環境に最も多く漏れている UI バグ、チームが許容できるテストメンテナンスの負担、UI のどの部分が最も頻繁に変更されるかを確認してください。

テストのニーズを評価する

何が壊れていて、何を検出すべきかを特定します。

1. バグの流出経路を整理する：

   • ビジュアルリグレッション（意図しないレイアウトのずれ、スペーシングの崩れ、アセットの欠落）
   • インタラクションの失敗（クリックしても反応しないボタン、壊れたフォーム、リンク切れ）
   • 状態の不具合（古いデータ、競合状態、不適切なローディング状態）
   • アクセシビリティの欠陥（ラベルの欠落、キーボードトラップ、コントラスト不足）
   • ブラウザー間またはデバイス間の不整合

2. 現在のカバレッジを評価する：

   • すでに何がテストされていますか？テストされていても、何のシグナルも得られないものはありますか？
   • どのテストがランダムに失敗し、無視されていますか？（不安定なテストは信頼を損ないます）
   • テストスイートの実行にどれくらい時間がかかりますか？遅いスイートは回避されます。

3. リスクと変更頻度に基づいて優先順位を付ける：

   • 利用頻度の高いユーザーパス（チェックアウト、サインアップ、主要なワークフロー）
   • 頻繁に変更される UI 領域（デザインシステムのコンポーネント）
   • 過去にバグが発生したことがある領域
   • アクセシビリティが特に重要な領域（フォーム、ナビゲーション、モーダル）

テストの観点

ビジュアルリグレッション

意図しないビジュアルの変更を、リリース前に検出します。

キャプチャ対象：

• コンポーネントの状態（デフォルト、ホバー、フォーカス、アクティブ、無効、ローディング、エラー）
• 代表的なブレークポイントでのページ全体のレイアウト
• ブラウザー間のレンダリングの違い（フォーカススタイル、フォームコントロール、フォント）

ベースラインの運用：

• ベースラインは個人のスクリーンショットではなく、チームの資産として扱います
• 意図的な変更はマージ後ではなく、プルリクエスト内でレビューします
• ノイズを防ぐため、意図的なデザイン変更の直後にベースラインを更新します

不安定さを防ぐプラクティス：

• キャプチャ前に、フォント、画像、アニメーションの読み込みが完了するまで待ちます
• 動的コンテンツ（タイムスタンプ、ランダムデータ、アニメーション）をモックするか固定します
• 決定的なテストデータと固定のビューポートサイズを使用します
• ネットワークの変動からテストを分離し、API のレスポンスをスタブします

スコープの境界：

• デザインシステムのコンポーネントを網羅的にテストします
• ページレイアウトはすべてのピクセル幅ではなく、主要なブレークポイント数か所でテストします
• 管理していないサードパーティーのウィジェット（埋め込み、広告）はテストしません

インタラクションテスト

ユーザーの操作によって正しい結果が得られることを検証します。

コンポーネントレベルのインタラクション：

• フォームの送信、バリデーション、エラーからの復旧
• モーダルの開閉、フォーカストラップ、Escapeキーの動作
• ドロップダウン、アコーディオン、タブ、開示要素の状態遷移
• ボタンの操作とその副作用

ユーザーフローの検証：

• 複数ステップのワークフロー（チェックアウト、オンボーディング、ウィザード形式のフロー）
• ナビゲーションとルーティングの動作
• ブラウザーの戻る／進む操作後の状態保持
• 同時操作（連続クリック、二重送信）

テストデータの方針：

• 現実的でありながら決定論的なデータを使用します
• エッジケース（空の入力、最大文字数、特殊文字）を網羅します
• 正常系のスタブだけでなく、エラー状態の応答も含めます

アクセシビリティのアサーション

テストパイプラインにアクセシビリティの検証を組み込みます。

自動チェック（ビルドごとに実行）：

• WCAGルール違反の検出にはaxe-coreまたは同等のツールを使用します
• 色のコントラスト比の最低基準（通常のテキストは4.5:1、大きなテキスト／UIコンポーネントは3:1）
• セマンティックHTMLの検証（見出しの順序、ランドマーク領域、ラベルの関連付け）
• フォーカス管理（視認できるフォーカスインジケーター、論理的なタブ順序）

キーボード操作のテスト：

• マウスを使わずに、フロー全体をTabキーで操作します
• すべてのインタラクティブ要素にアクセスできることを検証します
• モーダルのフォーカストラップと、そこから抜ける方法が機能することを確認します
• スキップリンクとバイパスブロックが機能することをテストします

スクリーンリーダーのスモークテスト（重要な操作フロー向け）：

• 動的なコンテンツ変更の読み上げ（ライブリージョン）
• 意味のあるアクセシブルネームと説明
• 状態の読み上げ（展開／折りたたみ、選択済み、必須）
• 支援技術に伝わるエラーメッセージ

動きとアニメーション：

• prefers-reduced-motionが尊重されることを検証します
• 発作を誘発する点滅がないことを確認します（1秒あたり3回未満）

UIのテストピラミッド

速度、信頼性、保守コストのバランスを取ります。

レイヤー	対象範囲	速度	目的
単体（コンポーネント）	単一のコンポーネント、依存関係はモック	高速（< 1s）	ロジック、レンダリング、プロパティの処理
統合（コンポーネント＋コンテキスト）	実際のプロバイダーとスタブを使ったコンポーネント	中速（< 10s）	インタラクションの動作、状態遷移
エンドツーエンド（フルブラウザー）	実際のブラウザー、実際のネットワークまたはスタブ	低速（テストあたり < 30s）	重要なユーザーフロー、ページをまたいだ動作
ビジュアルリグレッション	スクリーンショットの比較	中速（並列実行可能）	意図しない視覚的な変更

ガイダンス：

• 可能な場合は、ピラミッドの下位層にテストを配置します。ボタンの動作を検証する場合、コンポーネントテストはE2Eテストより高速で、より正確です。
• 複数のページにまたがるユーザージャーニーや、実際のブラウザー動作（ルーティング、認証、決済）が必要な場合に、E2Eテストを使用します。
• ビジュアルリグレッションテストはリリース前だけでなく、プルリクエストごとにCIで実行します。

ツールの選定

チームの技術スタックとテストレイヤーに合わせてツールを選びます。

ニーズ	有力な選択肢	検討事項
コンポーネントの単体テスト／統合テスト	Vitest + Testing Library、Jest + Testing Library	フレームワークに依存しません。ユーザーの操作を反映した Testing Library のクエリを優先します
重要なフローのエンドツーエンドテスト	Playwright、Cypress	Playwright は高速で、クロスブラウザーの並列実行に適しています。Cypress はセットアップがより簡単です
ビジュアルリグレッション	Chromatic、Loki、Playwright screenshots、Percy	Chromatic は Storybook との統合に適しています。Playwright は社内でのベースライン管理に適しています
アクセシビリティの自動チェック	axe-core、@axe-core/react、Playwright + axe	CI に統合します。ベースラインがクリーンになるまでは、ブロッカーではなく警告として扱います
インタラクション／ユーザーフロー	Playwright、Cypress、Storybook Test Runner	Storybook Test Runner は分離されたコンポーネントのインタラクションに適しています。Playwright／Cypress は一連のフローに適しています

実践的なルール：

• E2E ツールを 1 つ、コンポーネントテストツールを 1 つ選ぶことを優先します。ツールが増えすぎると、専門知識が分散します。
• プロジェクトで Storybook を使っている場合は、別のコンポーネントテストスイートを追加する前に、そこでインタラクションテストを追加します。
• アクセシビリティチェックは別のツールチェーンとしてではなく、既存のテストランナーに統合します。

アンチパターン

• 実装の詳細をテストする：内部状態や CSS クラス名ではなく、ユーザーに見えるものやユーザーの操作をアサートします。
• 不安定なテストを放置する：不安定なテストは、テストがないよりも悪いものです。すぐに修正するか削除します。
• すべてを E2E でテストする：テストスイートが遅いと、テストの実行が敬遠されます。ロジックのテストはコンポーネントテストに移します。
• すべてをスナップショットでテストする：スナップショットテストは変更を検出しますが、その意図までは説明しません。マークアップの安定性確認に限定して控えめに使い、動作のテストには使いません。
• アクセシビリティテストをメインパイプラインから分離する：スプリントごとに一度、手動で実行するだけのアクセシビリティチェックでは、継続的に問題を見つけられません。
• ブラウザー環境をモックする：E2E テストとビジュアルリグレッションには実際のブラウザーを使います。jsdom と happy-dom はコンポーネントのロジックには適していますが、レイアウトやインタラクションの再現には適していません。
• サードパーティーのウィジェットをテストする：管理していない埋め込みコンテンツ、マップ、広告、チャットウィジェットのベースラインを作成したり、アサートしたりしません。
• クロスブラウザーテストを省略する：少なくとも、ユーザーが実際に使うブラウザーで、フォーカススタイル、フォームコントロール、レイアウトを確認します。
• ベースラインを古いままにする：古いベースラインはリグレッションを見えにくくします。意図的なビジュアル変更の後は、ベースラインを更新します。

テストの信頼性を確認する

テスト戦略をリリースする前に、次の項目を確認します。

• リスクが最も高いユーザーフローが自動テストでカバーされている
• プルリクエストでビジュアルベースラインがレビューされている
• アクセシビリティチェックが CI で実行され、クリーンなベースライン、または文書化された例外を含むベースラインがある
• 不安定なテストが特定され、修正または削除されている
• テストスイート全体がチームの許容時間内に実行できる（目標：CI のフィードバックが 5 分未満）
• テスト失敗時に、不明瞭なスタックトレースではなく、対処可能なエラーメッセージが表示される
• クロスブラウザーのカバレッジが、実際のユーザーのブラウザー分布に合っている
• チームメンバーが複雑なセットアップなしでローカルにテストを実行できる
• テストデータが決定論的で、テスト実行中に外部サービスに依存しない