Back to Details

integration-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Run this repo's integration tests against a Veris dependency sandbox.
The sandbox is a set of stateful, contract-accurate twins of the services this code depends on. The code under test is never modified and never told: it keeps its production hostnames, credentials, and client stack, and 
veris-proxy
reroutes its outbound HTTP(S) into the sandbox from outside the process. Your job is to stand that pipeline up, prove it actually intercepted, and only then trust any test result.
针对Veris依赖沙箱运行本仓库的集成测试。
该沙箱是一组与代码依赖服务状态一致、契约精准的孪生服务。被测代码不会被修改，也不会被告知任何信息：它保留生产环境的主机名、凭证和客户端栈，
veris-proxy
会从进程外部将其出站HTTP(S)请求重定向到沙箱中。你的任务是搭建这条流水线，证明请求确实被拦截，只有这样才能信任测试结果。

Core framing: green means nothing without proof of interception

核心框架：若无拦截验证，测试通过毫无意义

Everything in this skill exists to make one sentence true: a passing test proves the integration works against the sandbox. Two rules follow.
  • Never modify the code under test to point it at Veris. No base-URL overrides, no injected config, no test doubles. If the code path you test is not the code path that ships, the green is fiction. The proxy is the whole mechanism.
  • Never report tests as passing without evidence the sandbox received the traffic. A suite that quietly stopped calling its dependency, a runtime that ignored the interception, and a working run all print the same test output. The proxy prints a receipt — what the sandbox actually received, per service — after every run, and an 
    --environment
    run whose receipt is empty exits 3 on its own: the environment already names the services, so "the suite reached the sandbox at all" is asserted for you. When the tests must touch a specific service, sharpen with 
    --require-service <name>[:count]
    . Either way, read the receipt before drawing any conclusion.
Do not declare the task done until the tests are green and the receipt shows the sandbox received the traffic the tests were supposed to send.
本技能中的所有内容都是为了确保一句话成立：通过的测试证明集成功能在沙箱环境下有效。由此衍生出两条规则：
  • 绝不要修改被测代码使其指向Veris。不要覆盖基础URL，不要注入配置，不要使用测试替身。如果测试的代码路径与上线的代码路径不一致，那么测试通过的结果就是虚假的。代理是实现这一机制的核心。
  • 若无沙箱接收请求的证据，绝不要报告测试通过。测试套件停止调用依赖服务、运行时忽略拦截、测试正常运行这三种情况的测试输出看起来完全一样。代理会在每次运行后打印一份请求接收凭证——即沙箱实际接收的各服务请求详情；如果使用
    --environment
    参数运行且凭证为空，程序会自动以退出码3终止：因为环境已经指定了服务，所以“测试套件至少连接到了沙箱”这一点会被自动验证。当测试必须访问特定服务时，可以使用
    --require-service <name>[:count]
    参数来强化验证。无论哪种情况，在得出结论前都要先查看请求接收凭证。
只有当测试通过且请求接收凭证显示沙箱收到了测试应发送的请求时，才能宣告任务完成。

The mode: container, always

运行模式：始终使用容器

Everything runs through 
veris-proxy run --image ...
. The proxy runs in its own container and your image runs in a second one sharing its network namespace; an 
iptables
redirect moves the traffic in the kernel, below every library. Nothing in the process under test has to cooperate, so the routing covers every runtime: Java, static Go binaries, Apache HttpClient, aiohttp. (Trust is still decided in-process, and an SDK that ships its own CA bundle decides it alone — see phases/troubleshooting.md.) Your image needs no capability, no iptables, no entrypoint change, and no particular base — distroless and scratch work. All requirements sit on the proxy's own container.
(The binary also has a host tier — 
run
without 
--image
, environment variables only. Do not use it in this skill: it covers only libraries that honour proxy variables, and its gaps are silent. If the work truly cannot run in a container, stop and tell the user rather than falling back.)
There is no committed proxy config to maintain. The run names an 
--environment
and the whole routing — which production hostnames map to which sandbox services — is derived from the control plane plus a routing table measured against the real vendors and embedded in the binary. Never write hosts files by hand.
所有操作都通过**
veris-proxy run --image ...
完成。代理在独立容器中运行，你的镜像在第二个容器中运行并共享代理的网络命名空间；
iptables
重定向会在内核层处理流量，不受任何库的影响。被测进程无需做任何配合，因此该路由方式支持所有**运行时：Java、静态Go二进制文件、Apache HttpClient、aiohttp。（信任关系仍由进程内部决定，如果SDK自带CA证书包，则由SDK单独决定——详见phases/troubleshooting.md。）你的镜像不需要任何特殊权限、iptables配置、入口点修改，也不需要特定的基础镜像——distroless和scratch镜像都可以正常工作。所有依赖都由代理容器承担。
（该二进制文件也支持主机层模式——不带
--image
参数的
run
命令，仅使用环境变量。本技能中请勿使用该模式：它仅支持遵守代理变量的库，且存在隐性漏洞。如果工作确实无法在容器中运行，请告知用户，不要退而求其次使用该模式。）
无需维护已提交的代理配置。运行时指定
--environment
参数后，整个路由规则（即哪些生产主机名映射到哪些沙箱服务）会由控制平面加上一个与真实供应商对比后生成的路由表推导得出，并嵌入到二进制文件中。永远不要手动编写hosts文件。

The phases

实施阶段

Work the skill as two phases plus a failure manual, each in its own file. Read the file fully at the point named — the details there are load-bearing, not optional:
  • phases/preflight.md — Phase 0, once per environment: seven check-first gates (API key, MCP server, testing guide, proxy binary, docker, a runnable test image, service manuals + the default world). Run through it before the first run against any environment, and whenever a prerequisite might have changed.
  • phases/running.md — Phase 1, every run: the one run command and its flags, receipts and 
    --require-*
    assertions, exec sessions for iterative work, webhooks via 
    --expose
    , seeding and fault injection, teardown. Autonomous once preflight holds.
  • phases/troubleshooting.md — the moment anything fails or confuses: the evidence-first diagnosis order (receipt, then 
    /veris/requests
    , then theories), empty-receipt causes, exit codes, and TLS trust failures from SDKs that bundle their own CA. Read it before forming a theory, not after one collapses.
本技能分为两个阶段加一份故障排查手册，每个部分都有独立文件。请在对应阶段完整阅读文件——其中的细节至关重要，不可省略：
  • phases/preflight.md —— 阶段0，每个环境执行一次：七项前置检查（API密钥、MCP服务器、测试指南、代理二进制文件、Docker、可运行的测试镜像、服务手册+默认配置）。在针对任何环境首次运行前，以及任何前置条件可能发生变化时，都需要执行该检查。
  • phases/running.md —— 阶段1，每次运行执行：单条运行命令及其参数、请求接收凭证与
    --require-*
    断言、迭代开发的执行会话、通过
    --expose
    实现的Webhook、数据初始化与故障注入、环境清理。完成前置检查后即可自主执行。
  • phases/troubleshooting.md —— 出现任何故障或疑问时使用：基于证据的诊断顺序（先看凭证，再看
    /veris/requests
    ，最后提出假设）、空凭证的原因、退出码说明、以及SDK自带CA证书包导致的TLS信任故障。请在提出假设前阅读该手册，不要等到假设不成立时才看。

Reporting back

反馈要求

Keep a running record of anything about the sandbox that confused or blocked you: gaps in its documentation, behavior that contradicted the docs, responses that differ from the real vendor, failures you could not attribute. Include request/response evidence. Give that list to the user verbatim at the end — it goes back to Veris, and it is how the twins improve.
请持续记录任何关于沙箱的疑问或障碍：文档缺失、与文档不符的行为、与真实供应商不同的响应、无法归因的故障。请附上请求/响应证据。任务结束时将该列表原封不动提交给用户——这些信息会反馈给Veris团队，用于优化孪生服务。

Ask before

操作前需询问

  • installing veris-proxy
  • registering the MCP server (the user runs this — it needs a restart)
  • anything that sends repo code or data to a new external destination
Sandbox lifecycle operations (
create_sandbox
, 
reset_sandbox
, 
delete_sandbox
, 
promote_sandbox
) are routine and yours to perform freely.
  • 安装veris-proxy
  • 注册MCP服务器（由用户执行——需要重启）
  • 任何将仓库代码或数据发送到新外部目标的操作
沙箱生命周期操作（
create_sandbox
、
reset_sandbox
、
delete_sandbox
、
promote_sandbox
）属于常规操作，你可以自由执行。