integration-testing

针对 Veris 依赖沙箱运行此仓库的集成测试。

沙箱是一组有状态且符合契约的服务双胞胎，模拟此代码所依赖的服务。被测代码绝不会被修改，也不会被告知：它保留生产环境中的主机名、凭据和客户端技术栈，veris-proxy 则从进程外将其出站 HTTP(S) 流量重定向到沙箱。你的任务是让任务描述的问题实际发生，修改代码，观察问题不再发生，并能证明这三点。

当前情况

• 没有 .veris/run.sh，或者 setting-up-veris 的 scripts/preflight.sh 失败 → 先处理该技能。这里绝不临时拼凑传输方式。
• 设计仍未确定，或者任务依赖于你尚未见过供应商声称的说法——“API 不支持 X”“它总是返回 Y” → 先处理 discovering-vendor-behavior。带着已定型的设计前来，会让沙箱只剩一个问题：你的代码是否有效。它会正确回答这个问题，但底层假设仍未经过验证。
• 否则：运行。

运行

只需一条命令——代理容器、工作负载容器、环境、信任、回执和清理都由它负责。.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 会悄然拒绝代理的证书。参考资料。
• --keep-proxy 会保留代理容器以供检查。

循环

这个双生体是模拟器，而不是模拟对象：它可以让供应商进入任务描述的状态，并在之后展示它记录的内容。每次运行都是这个循环的一轮，而一个类似 bug 的任务会从一轮红色运行开始：

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. 切换 — 同一轮运行，改动前为红色，改动后为绿色。

复现结果为红色时，就用它。在报告描述的确切条件下探查依赖项的行为——对重放请求的响应、失败回调留下的状态、重复项上的代码。修复所依赖的分支，往往只有实时依赖项才能揭示；根据静态阅读设计的修复，恰恰会在这个分支上显得合理却不正确；而作者从未察觉，因为他们编写的测试编码了与修复相同的猜测。

在一个会话中迭代。 将测试套件接入容器很少能一次成功，而且每次重新启动都会重新部署沙箱。使用 .veris/run.sh -- sleep infinity & 启动运行，然后根据需要多次执行 docker exec "$(docker ps -q -f name=veris-workload-)" bash -lc '<one pass>'；执行 kill %1 会结束运行并打印整个会话的回执。在一次拦截中执行多个步骤时，也可以通过镜像的 shell 串联起来：.veris/run.sh -- bash -lc 'python seed.py && pytest tests/integration -x'。

完成标准

• 回执中列出的服务，正是测试本应访问的服务；
• 回执和绿色结果来自同一次运行——通过 stub 获得的绿色结果与通过探测获得的回执，放在一起不能证明任何事情；
• 这次运行在到达供应商的过程中执行了改动后的代码——例如，仅由新代码写入状态的断言、仅由新分支输出的日志行，或从红到绿的切换本身；
• 仓库及其环境中没有任何内容指向沙箱。

请根据 reference/evidence.md 编写变更描述中的验证部分。测量过的内容归入已验证；未测量的内容归入假设而非验证。如果有 .veris/MEASUREMENTS.md 记录文件，应在撰写该部分前对照设计检查。

案例需要时参考

• reference/troubleshooting.md — 回执，然后是 /veris/requests，再然后是推测；空回执；退出代码。
• reference/trust.md — 自带 CA 的 SDK、未获得交接的 sidecar、两次重试的循环。
• reference/worlds.md — 重置、晋升、快照；保留会话构建的 world。
• reference/webhooks.md — --expose、--require-callback。
• reference/evidence.md — 变更描述模板。

反馈

持续记录任何让你对 沙盒 感到困惑或受阻的情况：文档中的缺失之处、与文档描述相矛盾的行为、与真实供应商不一致的响应，以及无法确定原因的故障。附上请求和响应证据。在最后将这份记录原样交给用户——它会反馈给 Veris，也是孪生体改进的方式。

操作前先询问

安装 veris-proxy、注册 MCP 服务，或将仓库代码发送到新的外部目的地之前，请先询问。沙盒生命周期操作（create_sandbox、reset_sandbox、delete_sandbox、promote_sandbox）属于常规操作，可自行执行。