AI開発で外部APIを使わずテストする。記録データと応答の設計

外部APIを使わないテストで過去に取得したJSONだけを保存すると、検証対象が成功時へ偏ります。返事がない、同じ要求が再送される、契約と違う形が届く、といった分岐は確かめられません。AIがもっともらしいモックを補っても、それがチームの合格基準と一致するとは限りません。人が境界と結果を決め、承認した範囲の実装やケース追加をAIへ任せます。

2026年9月21日時点の[WireMock公式文書](https://wiremock.org/docs/simulating-faults/)は、実サービスでは要求どおりに起こしにくい異常動作をテスト用のweb service fakeで注入でき、任意のHTTPエラー応答も構成できると説明しています。固定遅延、空応答、不正な応答チャンク、ランダムデータ送信後の切断、接続リセットも扱えます。保存対象にはbodyの写しとともに、遅延や通信障害を再現する設定が入ります。

ツールの機能一覧だけでは合格基準は決まりません。処理を続ける、再試行する、入力を拒む、エラーとして通知する、のどれが正しいかを先に定め、その分岐を起こす最小の記録を用意します。試験範囲は、自社コードが外部APIとの境界で定めた動作をすることです。先方サービスの可用性は証明できないと明記すれば、合否に責任を持つ範囲がぶれません。

4分類は、固定的な異常注入、状態遷移、応答コードとデータ型という出典の一般原則を基にした実務上の提案です。WireMockやOpenAPIが定めた分類や義務ではありません。異なる原因と期待判定を一つの「異常系」に押し込まないことが、分類の役割です。

正常fixtureは、契約どおりの要求に成功status、header、bodyを返します。必要な値を受理して後続処理へ渡せれば合格です。この基準データは、形式変更との差分を読む起点にもなります。

時間切れfixtureは、クライアントが定めた期限を超えるまで返答しません。HTTPエラーは返事を受け取った結果なので、即時にエラーstatusを返すケースとは分けます。期限到達時に中断するのか、社内方針に従って再試行するのかまで定めて、ようやく成否を判定できます。

重複fixtureは、同一要求の初回と再送後を異なる局面として表します。入力が同じでも、処理前か処理済みかによって返却内容と実行後の記録を切り替えます。二回とも同じbodyを返すだけでは二重処理を観察できないため、遷移そのものを検査対象に含めます。

形式変更fixtureは、契約どおりの旧形式と、欠落フィールド、型変更、未知フィールドを別ケースにします。それぞれを受理するか拒否するかも明記します。4分類を揃える目的はファイル数を増やすことではなく、自社プログラムの別々の分岐を再現可能にすることです。

各fixtureには「要求の照合条件」「返すstatus・header・bodyまたは障害」「事前状態」「実行後状態」「利用コードに期待する結果」を持たせます。この台帳は出典の一般原則を基にした実務上の提案であり、原典所定の分類や義務ではありません。ファイル名だけに意図を背負わせず、入力、返却、前後関係、合格基準を一続きで読めるようにします。

正常の一行には、対象操作と必須の要求項目、仕様に沿う成功応答、前後で変わる情報の有無、受理という結果を記します。時間切れの返却欄には、同じ照合条件に対する「クライアントの期限を超える遅延」を置きます。期限後に成功扱いせず、定めた中断または再試行へ進めば合格です。固定遅延を設定できることは2026年9月21日時点の公式仕様で確認できますが、待ち時間の値と再試行方針は各社が決める事項です。

重複は返却内容と遷移を一組で管理します。同じ入力でも、未処理なら初回用の内容を返して処理済みへ進め、すでに処理済みなら再送用の内容へ切り替えます。2026年9月21日時点の[WireMockの状態遷移に関する公式文書](https://wiremock.org/docs/stateful-behaviour/)では、scenarioが状態機械として動き、現在のscenario stateに応じて異なるstubを返す構成が示されています。これは再送前後を表現する技術的な根拠であり、何をもって「同じ要求」とするか、二度目をどう扱うかは業務側で定義します。

レビューで見るのは、結果を外から観察できるかです。「適切に処理する」では合否が決まりません。受理する、拒否する、成功と見なさない、後続へ渡さない、のように実行結果へ置き換えます。AIにも台帳の一行単位で作業を渡せば、生成されたテストを人が承認した基準へ対応付けられます。開発全体のマージ条件はAI駆動開発の開発フロー｜レビュー・テスト・CIで人の判断を残すと合わせて整理できます。

形式変更fixtureでは契約にある応答コードと出力型を基準にし、欠落フィールド、型の変更、未知フィールドを個別のケースにします。破損した通信応答は通信障害として分離します。これはOpenAPIとWireMockの一般原則を基にした実務上の提案で、両原典が求める分類や義務ではありません。データ形状の変更と、bodyを最後まで読めない障害では、呼出側が観察できる事象が異なります。

2026年9月21日時点の[OpenAPI Specification 3.1.1](https://spec.openapis.org/oas/v3.1.1.html)では、Responses ObjectがHTTP応答コードをResponse Objectへ対応付け、成功応答と既知のエラーを記述する想定になっています。Schema Objectはobjectに加えてprimitiveやarrayも含む入出力型を表現できます。形式変更は、契約上の応答コードと型を比較基準にします。取得した一件のJSONは、その契約を満たす例として扱います。

欠落と型変更については、どの差分を拒むべきかを個別に決めます。未知フィールドなら、追加を許容する設計か、契約外として弾く設計かを書き分けます。一方、空応答、不正な応答チャンク、途中切断、接続リセットは通信破損のfixtureへ移します。WireMockでこれらを構成できることは確認できますが、必須とする障害は利用中のクライアントとエラー処理に照らして選びます。

AIに形式変更テストを追加させる前に、契約のどの部分を基準にしたか、変更ごとの受理・拒否、エラー時に後続処理を止めるかを人が承認します。開発支援AIの権限条件は、Claude Codeのセキュリティ｜法人導入前に決める権限とデータ管理を参照し、外部APIのテスト条件とは別の台帳で管理できます。これにより、何をテストする判断と、AIに何を許す判断の責任者が明確になります。

導入可否は、4種類を用意したかだけでなく、各ケースの根拠を説明して承認できるかで判断します。対象操作について、仕様を基に正常と形式変更を説明できる、利用コードの期限を基に時間切れを起こせる、重複を状態遷移として再現できる、各結果を担当者が承認できる、という四点が実行条件です。実サービスへ接続しないため、先方環境の正常性は証明範囲に入りません。この限界もテスト名とレビュー記録へ残します。

更新のきっかけも先に決めます。API契約、タイムアウト、再送時の扱い、許容するデータ形状のいずれかを変えるなら、該当する台帳行とテストを同じレビューへ載せます。確認欄には、成功応答・既知のエラー・出力型の参照先、期限超過の観察方法、初回と再送後の局面、判定の承認者を置きます。取得済みの内容を上書きすると変更前の基準が消えます。旧形式と変更形式を別々に残せば、更新前後の受理範囲を比較できます。

実行へ進めるのは、正常を仕様どおりの受理、時間切れを期限超過、重複を初回と再送後の遷移、形式変更を出力型との差分として説明でき、台帳に記した結果を人が承認したときです。一つでも欠ければ、AIにテストを量産させる前に境界を決め直します。揃った後は、外部APIへ接続せず、開発環境とCIで同じ前提を繰り返し検証できます。fixtureの設計や承認フローを社内だけで決めにくい場合は、AI駆動開発の研修・導入支援・技術顧問に関する初回60分の無料相談で対象範囲を整理できます。