testing-best-practices

テストレイヤリングポリシー

ユニットテスト

目的：個々の関数と不変条件を分離して検証します。

• データ駆動：正常系、境界値、エラー、エッジケースを網羅するパラメーター化テーブルを使用します。
• プロパティベース：すべての入力で成り立つ不変条件をファズテストします（例：冪等性、ソートの安定性、シリアライズの往復）。
• モジュールの公開 API の範囲からテストケースを導きます。入力の型と制約、出力の形式、エラーの種類、不変条件を確認します。

統合テスト／コントラクトテスト

目的：コンポーネント間および外部サービスとの連携を検証します。

• API エンベロープ：リクエスト／レスポンスの形式、ステータスコード、コンテンツタイプ、ページネーション。
• エラーコントラクト：エラーコード、エラーの形式、レート制限、再試行。
• 認証とスコープ：トークンの検証、ロールベースのアクセス制御、テナントの分離。
• 結果整合性：制限時間内に収束することを検証します。固定時間待機ではなく、ポーリングを使用します。
• 可能な場合はテスト間で認証状態を再利用し、重複したログインフローを避けます。

E2E テスト

目的：フルスタックを通じて、実際のユーザーワークフローを検証します。

• モックは使用せず、実際のサービス、データベース、API を実行します。
• 正常系のワークフローのみを対象とし、エッジケースは下位レイヤーで扱います。
• 状態許容型：初期状態がクリーンであると決めつけず、既存の状態を許容して利用します。
• 冪等性：実行間のクリーンアップなしで、繰り返し安全に実行できるようにします。
• フロー指向：個別のアサーションではなく、実際のデータ経路をエンドツーエンドで検証します。

厳守事項

• シグネチャ、ソースの場所、行番号を決して捏造しないでください。 コードベースから実際に読み取った内容のみを参照してください。
• フィクスチャを捏造しないでください。 テストデータは、リポジトリ内の実際のスキーマ、型、またはシードデータから導きます。
• プロダクトコードにテスト専用のハックを加えないでください。 if (process.env.TEST) 分岐、テスト専用のエクスポート、テスト用のバックドアは禁止です。
• E2E テストで初期状態がクリーンであることに依存してはいけません。 テストは、既存データ、過去のテスト実行、共有環境を許容する必要があります。

実行ガイダンス

事前チェック（E2E の前）

1. 対象環境に接続できることを確認します（ヘルスエンドポイント、ping）。
2. 必要なサービス（データベース、API、認証プロバイダー）が稼働していることを確認します。
3. テストユーザー／認証情報が存在し、機能することを確認します。
4. 偽の失敗を引き起こす可能性のある残存状態を確認します。記録はしますが、それを理由に失敗させないでください。

決定論的なフィクスチャ

• 生成データにはシード付きの乱数を使用します（シード付き faker、決定論的 UUID）。
• フィクスチャは自己完結させ、テスト間でフィクスチャに依存しないようにします。
• 共有の可変フィクスチャオブジェクトより、ファクトリー関数を優先します。

非同期処理

• 上限時間とバックオフを設けてポーリングします。固定の sleep／waitForTimeout は決して使用しないでください。
• 操作ごとに明示的なタイムアウトを設定し、タイムアウト時には説明的なメッセージを出して速やかに失敗させます。
• 再試行回数に上限を設けます（例：指数バックオフで最大 3 回）。
• 手動ループより、フレームワーク標準の待機機能（Playwright の expect、非同期アサーション）を使用します。

フレークへの対処

• テスト実行ごとに許可されるインフラ起因の再試行は 1 回です。2 回失敗した場合、それはフレークではありません。
• 再試行に失敗した場合は、診断情報（スクリーンショット、ネットワークログ、サービスのヘルス状態、タイムスタンプ）を収集します。
• 修正に着手する前に、失敗を（フレーク／古いテスト／バグ）に分類します。
• フレークの「修正」として、根拠のない遅延や再試行ループを決して追加しないでください。

API サーフェスの調査

テストケースを生成する前に、以下を実施します。

• モジュールのソースを読み、エクスポート／公開関数を列挙します。
• ユーザーの依頼と調査したコードのコンテキストから対象範囲を確認します。曖昧な場合は前提を明記し、慎重に進めます。
• 関数ごとに、入力の型と制約、出力の形式、エラーの種類、不変条件を確認します。
• 状態への依存関係と、関数間の順序制約を調べます。

出力形式

Markdown を使用します。以下の 3 つのセクションを作成します。

テスト戦略 -- 各レイヤー（単体／統合／E2E）につき 1 つの箇条書きで、対象の関数／フローとカバレッジの種類を示します。

テストマトリックス -- 関数ごとに表を作成します。列は ID | Category | Name | Input | Expected とします。ケース ID の形式は {CATEGORY}-{NN}（HP、BV、ERR、EDGE）です。追記のみとし、番号を振り直してはいけません。

実装計画 -- フィクスチャ、単体テスト、統合テスト、E2E フロー、実行コマンドの順に手順を示します。

CI ガイダンス

高速 PR スモークレーン

• すべての PR で単体テスト、リント、型チェックを実行します。
• 重要な契約を対象とする統合テストの一部を実行します。
• 目標：5 分未満。

夜間フルレーン

反復回数を増やしたプロパティベーステストを含む、単体・統合・E2E テスト一式を実行します。再試行後は成功したものの、初回に失敗したテストにはフラグを付けます。

ワークフロー

1. 仕様またはコードでモジュールの動作（型、制約、API サーフェス）を定義します。
2. エージェント（このスキルを使用）がテスト戦略、マトリックス、実装計画を作成します。
3. test-writer エージェントが、計画を対象言語の慣用的な形式で実行可能なコードに変換します。
4. 開発者がテストに合格するよう実装します。
5. 実装によって不足しているケースが明らかになった場合は、まず追加を提案します。明示的に依頼された場合に限り、仕様に追記します。