integration-testing

このリポジトリの統合テストを Veris 依存関係サンドボックスに対して実行します。

サンドボックスは、このコードが依存するサービスの、状態を保持し、契約に忠実なツインの集合です。テスト対象のコードは決して変更されず、サンドボックスの存在も知らされません。本番環境のホスト名、認証情報、クライアントスタックをそのまま使い、veris-proxy がプロセスの外部から送信 HTTP(S) をサンドボックスへ振り向けます。あなたの仕事は、タスクで説明されている障害を発生させ、コードを変更し、障害が起きなくなるのを確認し、その3点すべてを証明できるようにすることです。

現在の状況

• .veris/run.sh がない、または setting-up-veris の scripts/preflight.sh が失敗する場合 → まずそのスキルを使います。ここでトランスポートをその場しのぎで用意することはありません。
• 設計がまだ固まっていない場合、またはタスクがベンダーの主張について、実際に確認していない内容に基づいている場合――「API には X がない」「常に Y を返す」など―― → まず discovering-vendor-behavior を使います。設計を固めた状態で取りかかると、サンドボックスに残る問いはコードが動くかどうかだけになります。サンドボックスは正しく答えますが、その前提は検証されないままです。
• それ以外の場合：実行します。

実行

コマンドは1つです。プロキシコンテナ、ワークロードコンテナ、環境、信頼設定、実行結果の記録、後片付けはすべてこのコマンドが担当します。.veris/run.sh がその役目を担います。-- より前のフラグは引き継がれ、-- の後のコマンドはデフォルトのコマンドに置き換わります。run.sh がない場合の形式は次のとおりです。

veris-proxy run --environment "$VERIS_ENVIRONMENT_ID" --image <test-image> \
  -v "$PWD:/work" -w /work -- <test command>

プロキシは環境の新しいサンドボックスをデプロイして、そのサンドボックスに対して実行し、サービスごとにサンドボックスが受信した内容を示す実行結果の記録を出力してから、サンドボックスを削除します。sandbox ready sandbox_id=<id> とログに出力されます。その ID を使って get_sandbox を呼び出すと、実行中に各サービスのシード投入と読み戻しに使用できる control_url が取得できます。実行のために独自のサンドボックスを管理しないでください。

• --environment を指定した実行で、実行結果の記録にサービスへの通信がないことが示された場合は、単独で終了コード 3 になります（コントロールプレーンの読み取りは別扱いであり、代わりにはなりません）。マッピングされたホストへの TLS ハンドシェイクがすべて拒否された場合も、次のアクションを示す診断とともに終了コード 3 になります。4 は判定不能を意味し、失敗であって、合格ではありません。
• --require-service <name>[:count] は省略可能で、必要になることはまれです。特定のサービスまたは呼び出し回数自体がアサーションとなる場合に限って使います。--require-* を指定すると、判定はその指定に委ねられます。
• --strict を指定すると、マッピングされていないホストがある場合、そのホスト名を示す 502 エラーで実行が失敗します。「コードがサンドボックス以外には到達しなかった」という主張を検証するときに使います。
• 依存関係に stripe（Python または Ruby）、古い botocore、または httplib2 が含まれる場合は、必ず最初から --patch-bundled-cas を指定します。これらの SDK はプロキシの証明書を通知なく拒否します。reference/trust.md。
• --keep-proxy を指定すると、プロキシコンテナを起動したままにして検査できます。

ループ

このツインはモックではなくシミュレーターです。タスクに記された状態をベンダーに作り出し、その後、記録された内容を確認できます。実行のたびにこのループを1回回します。バグを扱うタスクでは、最初の実行は失敗します。

1. 準備 — POST {control_url}/veris/data を使い、ケースで必要な行だけを指定してシードします。データの形は /veris/schema とマニュアルの名前に従います。ID はサンドボックスの状態から確認し、決して推測しないでください。
2. 設定 — このケースで発生させる障害を設定します。応答の消失（"phase":"after"）、スロットリング（429、Retry-After、"remaining":2）、レコードの消失、レイテンシなどです。強制できるコードはマニュアルに、行の形式はテストガイドの§4に、一覧は discovering-vendor-behavior に記載されています。
3. 実行 — タスクで指定された境界、つまりアプリケーションのエンドポイント、ワーカー、ジョブ、またはツールハンドラーからフローを実行します。その内部の SDK 呼び出しからではありません。報告に記載された呼び出しを変更せずに実行してください。呼び出し元が新しい値を渡すようになったことでしか成功しない再試行は、呼び出し元を変更しただけで、コードを修正したことにはなりません。変更した境界を通り、依存先を呼び出す最小限のテストを使ってください。
4. 読み戻し — レシート、クライアントが実際に送信した内容を確認する GET {control_url}/veris/requests、ベンダーが保存した内容を確認する GET {control_url}/veris/data?entity_type= を確認します。失敗した場合は、仮説を立てる前にこれらを読み戻してください（reference/troubleshooting.md）。
5. 切り替え — 変更前は失敗し、変更後は成功する、同じ実行を行います。

再現が失敗している間に、それを使ってください。報告に記載された正確な条件で依存先がどう動作するかを調べます。再送されたリクエストへの応答、失敗したコールバックが残した状態、重複時のコードなどです。修正の成否を左右する分岐は、実際の依存先でしか明らかにならないことがよくあります。その分岐について静的な読み取りだけで設計した修正は、もっともらしく見えても、まさにその箇所で誤ったものになります。しかも、修正の作者はそれに気付きません。書いたテストにも修正と同じ推測が組み込まれているためです。

1つのセッション内で繰り返してください。 テストスイートをコンテナに組み込んでも、初回でうまく動くことはほとんどありません。また、再起動のたびにサンドボックスが再デプロイされます。.veris/run.sh -- sleep infinity & で実行を開始し、必要に応じて docker exec "$(docker ps -q -f name=veris-workload-)" bash -lc '<one pass>' を何度でも実行します。kill %1 で終了すると、セッション全体のレシートが出力されます。1回のインターセプトで複数のステップを実行する場合も、イメージのシェルを経由して連結できます。例：.veris/run.sh -- bash -lc 'python seed.py && pytest tests/integration -x'。

完了の条件

• レシートに、テストが到達するはずだったサービスが記載されていること。
• レシートと成功が同じ実行から得られていること。スタブで得た成功とプローブで得たレシートを組み合わせても、何の証明にもなりません。
• その実行中に、変更したコードがベンダーに到達するまで実行されたこと。新しいコードだけが書き込む状態へのアサーション、新しい分岐だけが出力するログ行、または失敗から成功への切り替えそのものが証拠になります。
• リポジトリ内にもその実行環境にも、サンドボックスを参照する設定がないこと。

変更説明の検証セクションは、reference/evidence.md に従って作成してください。測定した内容は検証済みに、測定していない内容は検証ではなく仮定に記載します。.veris/MEASUREMENTS.md の記録がある場合は、そのセクションを書く前に設計と照らし合わせて確認してください。

ケースに応じて参照

• reference/troubleshooting.md — レシート、次に /veris/requests、その後に仮説を確認します。空のレシート、終了コードについても説明します。
• reference/trust.md — 独自の CA をバンドルする SDK、引き継ぎが行われなかったサイドカー、2回の再試行ループについて説明します。
• reference/worlds.md — リセット、昇格、スナップショット、セッションで構築したワールドの維持について説明します。
• reference/webhooks.md — --expose、--require-callback について説明します。
• reference/evidence.md — 変更説明のテンプレートです。

報告

サンドボックスについて戸惑ったことや作業を妨げられたことは、すべて継続して記録してください。ドキュメントの不足、ドキュメントと矛盾する動作、本物のベンダーとは異なる応答、原因を特定できなかった障害などが該当します。リクエストとレスポンスの証拠も含めてください。最後にそのリストをそのままユーザーに渡してください。Veris に送られ、ツインの改善に役立ちます。

事前に確認すること

veris-proxy のインストール、MCP サーバーの登録、リポジトリのコードの新しい外部送信先への送信を行う前に、確認してください。サンドボックスのライフサイクル操作（create_sandbox、reset_sandbox、delete_sandbox、promote_sandbox）は通常の操作であり、実行して問題ありません。