AI開発で外部APIをテストするなら、実サービスから切り離し、正常・時間切れ・重複・形式変更を4つの中心ケースとして固定し、通信破損は必要に応じて別の障害ケースとして追加します。AIへテストコードを任せる前に、要求の照合条件、返す応答または障害、事前と実行後の状態、自社コードに期待する結果を一組の台帳にします。これで受理・中断・再送・拒否を毎回同じ前提で検証できます。ただし、保存したJSONを4ファイルへ複製するだけでは、時間の経過や再送で結果が変わるケースを再現できません。
SECTION 01
AI開発の外部APIテストは、呼び出し側の判断を固定する
外部APIを使わないテストで過去に取得したJSONだけを保存すると、検証対象が成功時へ偏ります。返事がない、同じ要求が再送される、契約と違う形が届く、といった分岐は確かめられません。AIがもっともらしいモックを補っても、それがチームの合格基準と一致するとは限りません。人が境界と結果を決め、承認した範囲の実装やケース追加をAIへ任せます。
2026年9月29日時点のWireMock公式文書「Simulating Faults」は、実サービスでは要求どおりに起こしにくい異常動作をテスト用のWebサービスのテストダブルで注入でき、任意のHTTPエラー応答も構成できると説明しています。固定遅延、HTTPステータスやヘッダーも返さない完全な空応答、不正な応答チャンク、ランダムデータ送信後の切断を構成できます。接続リセットは主に*nixで動作し、Windowsでは接続がハングする場合があります。保存対象には本文の写しとともに、遅延や通信障害を再現する設定が入ります。
ツールの機能一覧だけでは合格基準は決まりません。処理を続ける、再試行する、入力を拒む、エラーとして通知する、のどれが正しいかを先に定め、その分岐を起こす最小の記録を用意します。試験範囲は、自社コードが外部APIとの境界で定めた動作をすることです。先方サービスの可用性は証明できないと明記すれば、合否に責任を持つ範囲がぶれません。
SECTION 02
正常・時間切れ・重複・形式変更を4つの中心ケースへ分ける
4つの中心ケースは、固定的な異常注入、状態遷移、応答コードとデータ型という出典の一般原則を基にした実務上の提案です。WireMockやOpenAPIが定めた分類や義務ではありません。異なる原因と期待判定を一つの「異常系」に押し込まず、通信破損は必要に応じて別の障害ケースとして追加します。
正常fixtureは、契約どおりの要求に成功ステータス、ヘッダー、本文を返します。必要な値を受理して後続処理へ渡せれば合格です。この基準データは、形式変更との差分を読む起点にもなります。
時間切れfixtureは、クライアントが定めた期限を超えるまで返答しません。HTTPエラーは返事を受け取った結果なので、即時にエラーステータスを返すケースとは分けます。期限到達時に中断するのか、社内方針に従って再試行するのかまで定めて、ようやく成否を判定できます。
重複fixtureは、同一要求の初回と再送後を異なる局面として表します。再送時の返却内容はAPI契約に従います。同じ本文を返す契約でも、処理件数や外部への副作用が一回に留まり、二重作成や二重送信が起きないことを検査します。必要に応じて、事前状態と実行後状態の遷移も観察します。
形式変更fixtureは、契約どおりの旧形式と、欠落フィールド、型変更、未知フィールドを別ケースにします。それぞれを受理するか拒否するかも明記します。4つの中心ケースを揃える目的はファイル数を増やすことではなく、自社プログラムの別々の分岐を再現可能にすることです。
SECTION 03
fixture台帳で条件と判定を一組にする
各fixtureには「要求の照合条件」「返すステータス・ヘッダー・本文または障害」「事前状態」「実行後状態」「呼び出し側のコードに期待する結果」を持たせます。この台帳は出典の一般原則を基にした実務上の提案であり、原典所定の分類や義務ではありません。ファイル名だけに意図を背負わせず、入力、返却、前後関係、合格基準を一続きで読めるようにします。
正常の一行には、対象操作と必須の要求項目、仕様に沿う成功応答、前後で変わる情報の有無、受理という結果を記します。時間切れの返却欄には、同じ照合条件に対する「クライアントの期限を超える遅延」を置きます。期限後に成功扱いせず、定めた中断または再試行へ進めば合格です。固定遅延を設定できることは2026年9月29日時点の公式仕様で確認できますが、待ち時間の値と再試行方針は各社が決める事項です。
重複はAPI契約に沿う返却内容と、冪等性を確認するための状態を一組で管理します。同じ本文を返す契約でも、処理件数や外部への副作用が一回に留まることを検査します。2026年9月29日時点のWireMock公式文書「Stateful Behaviour」では、scenarioが状態機械として動き、現在のscenario stateに応じて異なるstubを返す構成が示されています。これは再送前後を表現する技術的な根拠であり、何をもって「同じ要求」とするか、二度目をどう扱うかは業務側で定義します。再実行時に処理済み状態を持ち越さないよう、各テストの開始前にscenarioを開始状態へ戻すか、テストケースごとにWireMockを分離します。
レビューで見るのは、結果を外から観察できるかです。「適切に処理する」では合否が決まりません。受理する、拒否する、成功と見なさない、後続へ渡さない、のように実行結果へ置き換えます。AIにも台帳の一行単位で作業を渡せば、生成されたテストを人が承認した基準へ対応付けられます。開発全体のマージ条件はAI駆動開発の開発フロー|レビュー・テスト・CIで人の判断を残すと合わせて整理できます。
SECTION 04
形式変更と通信破損を同じfixtureにしない
形式変更fixtureでは契約にある応答コードと出力型を基準にし、欠落フィールド、型の変更、未知フィールドを個別のケースにします。破損した通信応答は、必要に応じて通信障害の追加ケースとして分離します。これはOpenAPIとWireMockの一般原則を基にした実務上の提案で、両原典が求める分類や義務ではありません。データ形状の変更と、本文を最後まで読めない障害では、呼び出し側が観察できる事象が異なります。
2026年9月29日時点のOpenAPI Specification 3.1.1では、Responses ObjectがHTTP応答コードをResponse Objectへ対応付け、成功応答と既知のエラーを記述する想定になっています。Schema Objectはobjectに加えてprimitiveやarrayも含む入出力型を表現できます。形式変更は、契約上の応答コードと型を比較基準にします。取得した一件のJSONは、契約に照らして検証し、適合する場合にだけ基準例として扱います。
欠落と型変更については、どの差分を拒むべきかを個別に決めます。未知フィールドなら、追加を許容する設計か、契約外として弾く設計かを書き分けます。一方、HTTPステータスやヘッダーも返さない完全な空応答、不正な応答チャンク、ランダムデータ送信後の切断は通信破損の障害ケースへ移します。接続リセットは主に*nixで動作し、Windowsでは接続がハングする場合があります。必須とする障害は利用中のクライアント、実行環境、エラー処理に照らして選びます。
AIに形式変更テストを追加させる前に、契約のどの部分を基準にしたか、変更ごとの受理・拒否、エラー時に後続処理を止めるかを人が承認します。開発支援AIの権限条件は、Claude Codeのセキュリティ|法人導入前に決める権限とデータ管理を参照し、外部APIのテスト条件とは別の台帳で管理できます。これにより、何をテストする判断と、AIに何を許す判断の責任者が明確になります。
SECTION 05
自社で実行する条件は、再現性と責任者で決める
導入可否は、4つの中心ケースと必要な追加障害ケースを用意したかだけでなく、各ケースの根拠を説明して承認できるかで判断します。対象操作について、仕様を基に正常と形式変更を説明できる、呼び出し側のコードの期限を基に時間切れを起こせる、重複を状態遷移として再現できる、各結果を担当者が承認できる、という四点が実行条件です。実サービスへ接続しないため、先方環境の正常性は証明範囲に入りません。この限界もテスト名とレビュー記録へ残します。
更新のきっかけも先に決めます。API契約、タイムアウト、再送時の扱い、許容するデータ形状のいずれかを変えるなら、該当する台帳行とテストを同じレビューへ載せます。確認欄には、成功応答・既知のエラー・出力型の参照先、期限超過の観察方法、初回と再送後の局面、判定の承認者を置きます。取得済みの内容を上書きすると変更前の基準が消えます。旧形式と変更形式を別々に残せば、更新前後の受理範囲を比較できます。
実行へ進めるのは、正常を仕様どおりの受理、時間切れを期限超過、重複を初回と再送後の遷移、形式変更を出力型との差分として説明でき、台帳に記した結果を人が承認したときです。一つでも欠ければ、AIにテストを量産させる前に境界を決め直します。揃った後は、外部APIへ接続せず、開発環境とCIで同じ前提を繰り返し検証できます。fixtureの設計や承認フローを社内だけで決めにくい場合は、導入研修・導入パッケージ・伴走顧問に関する初回60分の無料相談で対象範囲を整理できます。
FAQ
よくある質問
Q. 外部APIの応答JSONを保存するだけでは不十分ですか?
正常応答の再生には使えますが、時間切れ、状態を伴う重複、契約上の型変更、必要に応じて追加する通信破損を区別できません。要求の照合条件、返却または障害、事前と実行後の状態、呼び出し側のコードに期待する結果も台帳へ記録します。
Q. 時間切れはHTTPエラーのfixtureで代用できますか?
分けて扱います。HTTPエラーは応答を受け取った結果ですが、時間切れは呼び出し側の期限を超えても応答が返らない条件です。固定遅延で期限超過を作り、呼び出し側が成功扱いしないことを確認します。
Q. AIにfixtureを自動生成させてもよいですか?
生成作業には使えますが、分類、契約の基準、状態遷移、受理・拒否などの期待判定は人が先に決めて承認します。生成後も台帳との対応と、実データ由来の秘密情報が含まれないことを確認します。