skill-template/tests/integration/README.md

integration（可选集成 / 真实外联）

本目录默认不执行：

• python tests/run_tests.py 只收集 tests/ 根目录下 test_*.py，不会进入本目录。
• 本目录下文件一律为 *.py.sample，pytest / unittest 默认也不会按普通 test_*.py 收集。

与 samples 的区别

维度	tests/samples/	tests/integration/
目的	默认可升级为根目录 test_*.py 的 业务单元 / service 契约 / golden 范式	外联联调范式：网络、浏览器、仿真或真实系统
默认执行	.sample 不执行；复制到根目录并改名后才进入默认套件	永远不作为默认 unittest 的一部分；复制后仍需显式环境变量与手动/CI 任务触发
典型内容	FakeAdapter、fixture、隔离 DB	localhost 仿真、真实 API、真实 RPA（最高风险）

原则：只要会访问网络、浏览器、真实或仿真外部系统，应优先放在 integration（并保持 .sample 直至团队同意启用），而不是写进默认 tests/test_*.py。

何时使用

场景	建议 OPENCLAW_TEST_TARGET	其它条件
本地 / CI 对接仿真 HTTP	simulator_api	仿真服务如 http://localhost:5180
仿真页面 / 录播 RPA	simulator_rpa	本地页面或沙箱浏览器 profile
真实 API	real_api	仅手动触发
真实 RPA（最高风险）	real_rpa	仅手动触发

环境变量（与 adapter_test_utils 一致）

• 目标档位：OPENCLAW_TEST_TARGET
  取值：unit | mock | simulator_api | simulator_rpa | real_api | real_rpa
  默认未设置等价于 unit。

安全约束

• 禁止在样例或复制后的测试代码中硬编码真实账号、密码、token、cookie、生产 URL。
• 凭证应来自平台密钥库、受控环境变量或本机安全配置（.env 已列入 tests/.gitignore，勿提交）。
• 真实 RPA 可能对 ERP/TMS/WMS 等产生真实操作；务必沙箱账号、只读权限，并由人工触发 CI job。

如何运行某个样例

1. 将目标 *.sample 复制为 test_*.py（去掉 .sample）。
2. 按技能修改其中的占位 URL / 路由 / 断言。
3. 使用 pytest 指向该文件（或整目录），并导出上表所需环境变量。

$env:OPENCLAW_TEST_TARGET = "simulator_api"
pytest tests/integration/test_simulator_api_contract.py -v