integration-contract-testing

インテグレーション契約テスト

アダプターの境界が、アプリケーションが依存する契約に準拠していることを確認するには、このスキルを使用します。

基本ルール

• ベンダーの実装ではなく、境界の契約をテストします。
• 成功時と失敗時の両方のレスポンス形式を検証します。
• フィクスチャは現実的かつ最小限にし、サニタイズします。
• 境界でのスキーマ検証を優先し、無効なベンダーデータが拒否されることをアサートします。
• アプリケーションのテストにはフェイクを使用し、アダプターの動作には対象を絞ったインテグレーションテストを実施します。
• CI の決定性を確保します。ネットワーク接続が必要なテストには、明示的なオプトイン、安定した認証情報、明確なスキップ動作が必要です。

契約テストのレイヤー

1. マッピングテスト：外部フィクスチャから内部型への変換。
2. エラー正規化テスト：ベンダーの失敗からアプリケーションエラーへの変換。
3. アダプター境界テスト：アダプターが期待されるコマンド／リクエストを送信し、レスポンスを処理することを確認します。
4. 任意のライブスモークテスト：管理された環境で、認証情報、エンドポイント、安全な操作を 1 つ確認します。

フィクスチャのルール

• サニタイズ済みのフィクスチャは、アダプターのテストの近くに保存します。
• 動作が分かる名前を付けます：customer-success.json、customer-missing-required-field.json。
• 不正な形式または不完全なレスポンスのフィクスチャを少なくとも 1 つ含めます。
• 完全な形状が契約である場合を除き、大きなゴールデンファイルは避けます。
• トークン、認証情報、個人データ、独自のペイロードの詳細を削除します。

テストチェックリスト

• 成功レスポンスが内部契約にマッピングされる。
• 必須フィールドが欠落している場合、明確なエラーになる。
• 想定外の列挙値／ステータスが適切に処理される。
• タイムアウトまたはネットワーク障害が、再試行可能／利用不可のエラーにマッピングされる。
• 認証／認可の失敗が、一時的なエラーとして再試行されない。
• ページネーションが正しく停止し、カーソル／チェックポイントが維持される。
• リクエスト ID などの可観測性フィールドが、利用可能な場合に保持される。

フェイクとモック

ユースケースをテストするときは、動作フェイクを使用します：

class FakeCustomerGateway implements CustomerGateway {
  customers = new Map<string, Customer>();

  async getCustomer(id: string) {
    return this.customers.get(id);
  }
}

アダプター自体をテストする場合に限り、SDK／HTTP の境界で絞り込んだモックを使用します。

よくある間違い

• モックが呼び出されたことだけをテストし、その結果の動作をテストしない。
• 成功ケースのフィクスチャしかテストしない。
• 生のベンダーフィールドがドメインのアサーションに漏れるのを許す。
• すべてのテストを外部サービスの稼働に依存させる。
• フィクスチャデータをサニタイズせずに残す。