testing-best-practices

テストのベストプラクティス

製品の動作、要件、コードパスを有用なチェックに変えるための、実践的な QA ガイダンスです。手動テストケース、テスト計画、カバレッジレビュー、自動化シナリオ、ユニットテスト、Playwright のブラウザテストやコンポーネント統合テスト、ロケーター、/unit-test-grill、/integration-test-grill、/testcase-grill にご活用ください。

中心となる考え方は、特定のフレームワークではありません。テストの規律です。

• ユーザーに見える、または公開されている契約から始めます。何が正常に動作する必要があるのか、何が失敗する可能性があるのか、何が決して起きてはならないのかを確認します。
• リスクに合ったテスト形式を選びます。探索的テストの記録、手動テストケース、回帰テストチェックリスト、ユニットテストのカバレッジ、統合シナリオ、自動化タスクなどです。
• 各チェックで、意味のある動作、要件、分岐、状態遷移、エラーパス、またはクリーンアップの保証を検証します。
• カバレッジの対象を絞ります。互いに独立した要素は個別にテストし、ノイズの多い直積を避け、プラットフォームの再テストにしかならない恣意的な境界値は省略します。
• 新しい構成を追加する前に、周辺のテスト、既存の QA 成果物、製品のフロー、スキーマ、自動化の規約を確認し、プロジェクトの実情を反映します。
• 統合テストのロケーターとテストデータは、保守が必要なテスト API として扱います。スキーマや実装を変更する場合は、影響を受けるチェックも併せて変更します。

テスト対象を選んだ後、該当する個別のルールファイルを参照してください。現在、詳細なルールが用意されているのは、自動化されたユニットテスト、セマンティックな統合テストロケーター、リポジトリに保存された製品テストケースです。それ以外の QA 形式では、このファイルの基本方針に従い、テスターや自動化エンジニアが実行できるほど具体的な成果物にしてください。

適用する場面

次の場面では、このガイドラインを参照してください。

• 手動テストケース、スモークテスト、回帰テストスイート、受け入れシナリオ、探索的テストのチャーターを作成するとき。
• リポジトリのテストケースカタログに保存された構造化テストケースを生成、修正、レビュー、または再編成するとき。
• アプリケーションの動作に対する自動化カバレッジを計画またはレビューするとき。
• コードの自動テストを追加またはレビューするとき。
• 動作のカバレッジ、分岐カバレッジ、状態遷移、クリーンアップチェック、エラーパスの不足を探すとき。
• テストファイルや QA チェックリスト内のチェックの命名、順序、範囲を決めるとき。
• 統合テスト用のロケーターを作成またはレビューするとき。セマンティックな名前、スキーマパス、JSX 属性、影響を受けるチェックも対象です。
• /unit-test-grill を呼び出して、テストコードを書かずにコードの動作をチェックリストに変換するとき。
• /integration-test-grill を呼び出して、テストコードを書かずに、確認済みの製品ケースをブラウザまたはコンポーネントの自動テストに対応付けるとき。
• /testcase-grill を呼び出して、ページやブロックの担当テストケースを一覧化し、カタログには書き込まずに整理するとき。

QA の基本方針

• 各チェックは1つの動作または要件を対象にします。その形式で必要な場合は、前提条件、操作、期待結果を明確にします。
• 実行の優先度が異なる場合は、スモークテスト、クリティカルパス、回帰テスト、ネガティブテスト、境界値テスト、権限テスト、データ状態テスト、復旧テストを分けます。
• 実装の詳細ではなく、保証する動作を説明するシナリオ名を優先します。
• 再現性に影響する場合に限り、セットアップデータ、環境の前提条件、クリーンアップを記載します。
• 自動化の候補は、安定性と価値に基づいて選びます。繰り返し実行するクリティカルパス、リスクの高い回帰、決定論的な状態、信頼性の高いアサーションを優先します。
• 期待結果、データ要件、ロケーター戦略が保守可能なほど安定するまで、シナリオを自動化しないでください。
• レビューでは、不足している具体的なチェックや不安定な前提条件を報告します。カバレッジ率や技術名を主な指摘事項にしないでください。

ルール一覧

各テーマ固有のユニットテストルールを読む前に、unit-test-conventionsを読んでください。

• unit-test-function - 公開入力、所有する変換処理、分岐、エラー、非同期コラボレーターとの境界。
• unit-test-react-hook - 公開フックの契約、変化する引数、非同期処理、クリーンアップ、ブラウザーやリスナーの動作。
• unit-test-react-component-standalone - 独立したコンポーネントの DOM、props、state、インタラクション、アクセシビリティ。
• unit-test-react-component-compound - 公開パーツと、それらの間にある state、context、動作、アクセシビリティの関係。
• unit-test-grill - /unit-test-grill用のシナリオ計画モード。改善する既存テストと、新たに作成するテストに分けます。

各アプリケーション統合テストルールを読む前に、integration-test-conventionsを読んでください。

• integration-test-browser - ナビゲーション、ブラウザーが管理する状態、アプリケーションのブートストラップ、またはその他のフルブラウザー境界が必要なケース向けです。
• integration-test-component - 現実的にマウントされた機能境界、ラッパー、プロバイダー、観察可能なコンポーネント統合の動作。
• integration-test-server — 公開サーバーのエントリーポイントとサービスのオーケストレーション。
• integration-test-mocks - シナリオごとに管理するモック状態、ケース ID、ハンドラー、同じ場所に配置するファイル構造。
• integration-test-locator-testids - 意味に基づくテスト ID のスキーマ、再利用、生成される定数、条件付きの@siberiacancode/testidsの使用。
• integration-test-setup — テストケースの前提条件、コンポーネントラッパー、ルーターとクエリの状態、マウント、準備完了の確認。
• integration-test-grill - テストケース主導の自動化計画。改善する既存の自動テストと、新たに作成するブラウザーテストまたはコンポーネントテストに分けます。

各テーマ固有のテストケースルールを読む前に、testcase-conventionsを読んでください。

• testcase-file-structure - フォルダーとファイルの管理範囲、カバレッジの重複、子画面と再利用可能なブロックの配置場所。
• testcase-naming - ドット区切りの階層、インターフェースラベルの厳密な表記、読み込み、空のリスト、データのケースにおける固定形式。
• testcase-content - アトミックなケース、ユーザー視点の操作、具体的な期待結果、デザイン、機能、データの各チェックの分け方。
• testcase-preconditions - ケースファイル、フォルダー、グローバルの各前提条件の適用範囲。
• testcase-grill - /testcase-grill用のケース計画モード。改善する既存ケースと、新たに作成するケースに分けます。

使用方法

1. テストの目的を特定します。手動 QA、テストケースの設計、カバレッジのレビュー、自動化の計画、自動テストの実装、または統合テストの設計です。
2. テスト対象を特定します。製品のフロー、要件、API、データ状態、関数、UI の動作、フック、コンポーネント、またはコンポーネント間の統合です。
3. 依頼に合った出力形式を選びます。手動 QA の場合は、実行可能なテストケースまたは優先順位付きのチェックリストを作成します。自動化の場合は、安定したシナリオまたはコードレベルのテストを作成します。
4. 単体テストでは、共通の規約を読んでから、テスト対象のコードに合致するルールだけを読みます。
5. ブラウザー API またはリスナーのフックについては、その動作が該当する場合に限り、フックのルールからリンクされているリファレンスを読みます。
6. 統合テストでは、共通の規約を読んでから、選択したブラウザーまたはコンポーネントの境界、モック、ロケーター、グリルモードに必要なルールだけを読みます。
7. リポジトリに保存するテストケースでは、テストケースの規約を読んでから、タスクに合致するルールだけを読みます。ファイルを選択または再編成する場合は構成、name を記述する場合は命名、ステップと期待結果を記述する場合は内容、セットアップを追加または移動する場合は前提条件、テストケースを記述する前に一覧表示する場合はグリルのルールを確認します。

自動テストのデフォルト

• 既存のリポジトリ規約は、一般的なテストの推奨事項より優先されます。
• まず同じモジュールのテストを確認し、次に最も近い比較対象のテスト、隣接レイヤーのテスト、既存のヘルパーを確認してから、実装を確認します。
• 最も近い正常に動作するパターンを模倣し、必要最小限の構造変更にとどめます。比較対象のテストですでに使われている場合、または正確性のために必要な場合を除き、テストスイートを再設計したり、新しい抽象化を追加したりしないでください。
• シナリオは、明示された動作、プロジェクトで通常カバーする実装分岐、類似テスト、ユーザー要件、回帰、または確立されたカバレッジパターンに基づいてのみ追加します。
• 関連するプロジェクト規約がない場合は、Should <observable behavior>、同じ場所に配置するテスト、直接的なセットアップを使用します。forEach は本当に繰り返しになるケースにのみ使用し、複合ケースは複数の軸が相互作用する場合にのみ作成します。

コンパイル済みドキュメント全体

概要をまとめたドキュメントは、AGENTS.md を参照してください。