skill-template/tests/samples

samples（业务测试样例，默认不执行）

本目录存放可复制到根目录的业务测试范式，面向「企业数字员工技能」中 ERP、TMS、WMS、船司、报关、邮件、LLM、RPA 等外联场景下的 service / golden 测法说明。

---

作用

• 这里的文件是 .py.sample：python tests/run_tests.py 不会收集本目录（run_tests.py 只发现 tests/ 根目录下的 test_*.py）。
• 人类或 AI 需要启用范式时：复制到 tests/test_<名称>.py（去掉 .sample），再按业务改 import、断言与 fixture 路径。
• 禁止把真实联调、真实网络、真实 RPA 写进复制后的默认用例；此类内容应放在 tests/integration/*.sample 并配合环境变量开关。

---

样例文件

1. test_service_contract.py.sample

适合：

• 技能有清晰的 service 层入口，例如 run(...)、handle(...)、execute(...)。
• 需要验证：成功路径、参数/校验错误、adapter 异常被转换为业务可读错误。
• 需要用 FakeAdapter（见 tests/adapter_test_utils.py）或自建 stub 替代 ERP、TMS、WMS、船司、报关、LLM、RPA 等，不发真实 HTTP、不开真实浏览器。

2. test_sync_contract.py.sample

适合： 外源 → 本地库的同步 / refresh / collect 能力。

至少应覆盖：首次插入、第二次幂等、更新、失效数据处理、不可信空结果保护 vs 完整空快照失效、遗漏 snapshot_complete 立即失败、部分写入后故障注入与回滚（fail_after_writes）、统计字段 inserted/updated/unchanged/removed、同步路径不调用 CSV/Excel 导出器。snapshot_complete 为调用方必须显式传入的 keyword-only 参数（无默认值），禁止默认把结果当成完整快照，也禁止靠条数猜测完整性。使用通用表名（如 business_key），不要写具体平台业务名。

3. test_action_core_contract.py.sample

适合： 校验「单业务内核、多入口」——task/CLI/兼容命令调用同一 domain service；不按 toolbar/cron/agent 来源改变业务结果。

4. test_golden_cases.py.sample

适合：

• 解析类：邮件/单证/PDF/Excel 等结构化输出。
• 计算类：费用、税费、分摊、账单字段。
• 校验类：合规、字段一致性、状态机规则。

推荐配合根目录下的 tests/fixtures/sample_request.json 与 tests/fixtures/expected_response.json（复制技能后按域替换字段，保持脱敏）。

---

如何启用 service contract 样例

1. 复制文件
   tests/samples/test_service_contract.py.sample
   → tests/test_service_contract.py（或 tests/test_<domain>_service_contract.py，须符合根目录 test_*.py 命名以便 run_tests.py 收集）。

2. 替换示例 import
   把注释中的示意：
   # from service.your_service import run
   改为真实模块，例如：
   from service.quote_service import run_quote
   （具体路径以技能代码为准。）

3. 注入假外部依赖

   • 不要在默认用例里直接 requests 访问 ERP/TMS/WMS 等。
   • 不要打开真实网页或驱动真实 RPA。
   • 不要调用真实 LLM；可 stub 返回固定 JSON。
   • 对 timeout / unauthorized / invalid_response 等分支，用 FakeAdapter 或自建 fake 模拟（与 adapter_test_utils 思路一致）。

4. 至少保留三类断言习惯

   • 成功路径：返回 success: true 或与技能约定的成功结构。
   • 参数错误：缺必填字段时返回结构化 error（字段/码），而非未捕获裸异常。
   • 外部异常：adapter 超时、鉴权失败、脏响应等被转换为可读、可重试标识明确的错误形态（按产品约定）。

5. 给 AI 的提示
   复制后全文搜索 your_service、TODO、伪代码 等占位符并替换；不要留下指向真实客户的示例数据。

---

如何启用 golden case 样例

1. 复制文件
   tests/samples/test_golden_cases.py.sample
   → tests/test_golden_cases.py（或 tests/test_<domain>_golden.py）。

2. 按业务修改 fixtures（仍须脱敏）

   • tests/fixtures/sample_request.json：请求或输入快照。
   • tests/fixtures/expected_response.json：期望摘要或关键字段。
     可新增多组文件，如 case_valid_001.json，并在测试中显式读取路径。

3. 断言建议（避免脆弱用例）

   • 比较关键字段，避免对整段 JSON 做机械全文 diff。
   • 忽略时间戳、随机 id、trace_id 等非确定字段。
   • 对列表：断言长度、关键元素、排序规则（若业务保证顺序）。
   • 对金额/数量：断言 Decimal 字符串、或允许文档约定的小范围误差。

4. 与 service 的关系
   golden 用例仍应通过 service 层（或纯函数）得到输出，再与 fixture 对比，而不是从 CLI 字符串 scrape。

---

不应该写在 samples 复制件里的内容

以下若出现，应移到 tests/integration/*.sample 或 tests/desktop/*.sample，并加环境变量授权说明：

• 访问真实 API 或内网服务。
• 打开真实 RPA 页面或生产门户。
• 读取真实客户文件、生产数据库。
• 在测试中写入真实数据根或共享盘。
• 任何真实 token / cookie / 密码 字面量。
• 耗时极长、强依赖宿主 UI 抖动、无法在 CI 稳定复现的用例（不要塞进默认 tests/test_*.py）。

---

推荐命名（复制到根目录后）

用途	示例文件名
Service 契约	tests/test_service_contract.py
同步契约	tests/test_sync_contract.py
单内核多入口	tests/test_action_core_contract.py
Golden / fixture 回归	tests/test_golden_cases.py
领域规则	tests/test_<domain>_rules.py
校验逻辑	tests/test_<domain>_validation.py

命名需满足：tests/ 根目录下 test_*.py，以便 python tests/run_tests.py 默认发现。

更多分层说明见 tests/README.md（「我该把测试写在哪里？」与「新技能最小测试清单」）。