test

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

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

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

必須の事前準備

frontend-designを読み、そのコンテキスト収集プロトコルに従ってください。利用可能なコンテキストを再利用し、重要な情報に不足がある場合のみ確認してください。さらに、現在本番環境に流出している最も一般的な 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 + React Testing Library、Jest + React Testing Library	ユーザーの操作を反映した Testing Library のクエリを優先します
重要なフローのエンドツーエンドテスト	Playwright、Cypress	速度とクロスブラウザーでの並列実行には Playwright、よりシンプルなセットアップには Cypress を選びます
ビジュアルリグレッション	Chromatic、Loki、Playwright screenshots、Percy	Storybook との統合には Chromatic、社内でのベースライン管理には 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 でテストする：テストスイートが遅いと、テストの実行が敬遠されます。ロジックのテストはコンポーネントテストに移します。
• あらゆるものをスナップショットにする：スナップショットテストは変更を検出しますが、その意図は説明しません。動作のテストではなく、マークアップの安定性を確認するために限定的に使用します。
• アクセシビリティテストをメインのパイプラインから分離する：スプリントごとに 1 度、手動で実行するアクセシビリティチェックでは、一貫して問題を検出できません。
• ブラウザー環境をモックする：E2E とビジュアルリグレッションには実際のブラウザーを使用します。jsdom と happy-dom はコンポーネントのロジックには適していますが、レイアウトやインタラクションの忠実性には適しません。
• サードパーティー製ウィジェットをテストする：管理していない埋め込みコンテンツ、地図、広告、チャットウィジェットをベースラインに含めたり、アサート対象にしたりしないでください。
• クロスブラウザーテストを省略する：少なくとも、実際にユーザーが使用するブラウザーで、フォーカススタイル、フォームコントロール、レイアウトを確認します。
• ベースラインを古いままにする：古いベースラインはリグレッションを見えにくくします。意図的なビジュアル変更の後は、ベースラインを更新します。

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

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

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