testing-principles

言語に依存しないテストの原則

ここでのテストは受け入れ済みの振る舞いを保証し、次のエージェントは既存のテストをすべて維持すべき要件として読み取ります。そのため、脆弱なテスト、重複したテスト、実装の形に引きずられたテストは誤った要件になります。そのようなテストは回避策を生み、その回避策は実装に負債を残します。維持コストに見合う証明を行うテストだけを残してください。

テストの選定

• 特に理由がなければ、ユーザーや呼び出し元が観察する境界での統合テストと E2E テストを通じて、受け入れ済みの振る舞いを証明してください。計算、解析、分岐ルールなど、代表的な境界テストでは各ケースを証明できないロジックには、ユニットテストを追加してください。
• 振る舞いに関する各主張は、1つのテストが担います。ロジックに関する主張はそのユニットテストが担い、その他の振る舞いに関する主張は、観察可能な最も狭い統合または E2E の境界におけるテストが担います。より広い境界や別のバリエーション（ビューポート、デバイス、ロール）でのテストは、配線、マッピング、永続化、レンダリング、ナビゲーションなど、その境界やバリエーションによって加わる要素を証明し、別のテストが担うルールについては代表的なケースを最大1つだけ残してください。
• テストを最小限にする前に、受け入れられる結果に基づいて必要な証明境界を判断してください。アプリケーションやサービスのエントリーポイントを通じて提供される結果には、ルーティング、プロバイダー、状態の所有者、アダプターなど、関連する本番構成が含まれます。コンポーネントを分離したテストや、テスト用に構築した代替構成では、その配線を証明できません。その構成を通過する証明を再利用するか、通過するテストを選んでください。ハーネスは、コンポーネントの数やテストレーンの割り当てではなく、何を観察する必要があるかに基づいて選んでください。その境界より下のテストでは、切断されたアクション、失われた状態更新、壊れた遷移が見えないことがあります。明示的にコンポーネントに限定された結果には、コンポーネントの境界を維持してください。
• カバレッジは、未テスト領域を見つけるための診断指標として扱い、目標にはしないでください。CI のしきい値がある場合はプロジェクトの設定であり、それ自体が品質目標ではありません。
• プロジェクトで速度の予算が設定されている場合は、それに従ってください。設定されていない場合、現在の成果にとってフィードバックの遅さや CI コストが無視できないときに限り、テスト速度を調査してください。必要な証明境界を満たすために遅くなるテストは残してください。

テスト設計のルール

• 各テストは、Arrange、1つの Act、Assert の順に構成してください。複数のアサーションで1つの振る舞いを証明してもかまいません。
• リポジトリのテスト命名規則に従い、条件と観察可能な結果を名前に含めてください。
• 公開境界または統合境界を通じて振る舞いをテストしてください。アサーションでは、非公開の実装ではなく、戻り値、出力、エラー、状態変化を検証してください。
• 独立して導き出したリテラル、プロパティ、承認済みスナップショット、またはフィクスチャを期待値として使用してください。実装から導いたオラクルでは、同じ実装上の欠陥を検出できません。
• 各テストの期待結果は無条件にしてください。テーブル駆動テストやプロパティベーステストも使用できますが、各ケースが個別に報告され、独立したオラクルを使う必要があります。
• 受け入れ済みの境界動作とエラー動作をテストしてください。一般的なエッジケースの組み合わせを追加するのではなく、契約からテストケースを導き出してください。
• 各テストは独自の状態を作成して後片付けし、単独でも任意の順序でも成功し、結果に影響する時間や乱数を制御してください。
• テストは実行可能な状態に保ってください。受け入れ済みの振る舞いを記述しなくなったテストは修正するか削除し、失敗を回避するためだけに無効化されたテストは復元してください。

モックと境界のルール

• 外部との直接的な I/O 境界をモックし、内部のビジネスロジックとテスト対象の境界は実際のものを使用してください。
• 既存のアプリケーション所有のアダプターをモック境界として使用してください。現在の設計では外部 I/O、不安定な契約、または必要な置き換えを制御できない場合に限り、アダプターを導入してください。
• モックの振る舞いは、テストに必要な契約の範囲に限定してください。

データレイヤーのテスト

データアクセスがテスト対象の振る舞いの依存先にすぎない場合は、モックベースのテストで十分です。テスト対象がクエリ、リポジトリの実装、スキーマ制約、またはマイグレーションとの互換性である場合は、プロジェクトで実際に使用しているデータベースエンジン、または承認済みの同等環境で検証してください。リポジトリの設定からテスト環境を特定してください。代表的な環境が存在せず、その追加が承認済みの作業範囲外である場合は、検証方法が未決定であることを報告してください。

Design Doc またはリポジトリの設定で指定されたスキーマソースと、データアクセスコードを照合してください。テーブル、カラム、型、制約、または方言との互換性を証明するには、スキーマソースの検証が必要です。モックの成功によって証明できるのは、モック化された境界での振る舞いのみです。

検証要件

ケイパビリティプローブの事後条件

ケイパビリティプローブは、利用側の境界を使用し、利用側が必要とする正確なプロパティをアサートした場合に合格となります。コマンドの成功、インポートの成功、またはオブジェクトの存在は、セットアップの証拠です。

テストの構成

リポジトリで確立されているテストパス、ランナーのルーティング、命名規則に従ってください。承認済みの新しい規約を定める場合は、セットアップ、ランナー、または環境が異なる場合に限り、テストの種類を分けてください。

回帰テスト

• 再現可能な振る舞いのバグを修正するたびに、回帰テストを追加してください。実行可能な形で再現できない場合は、その理由と、再発を防ぐための代替となる静的、契約、または環境面の証拠を記録してください。
• 特性が明らかになっていないレガシーコードに対して、振る舞いを維持する変更を加える前に、特性を確認する証拠を取得し、変更後に再実行してください。

参考資料

• references/frontend.md：コンポーネント、フック、または UI 統合テストを作成、変更、レビューする際に参照してください
• references/e2e.md：ブラウザー E2E テストを作成、変更、レビューする際に参照してください