125 lines
6.2 KiB
Markdown
125 lines
6.2 KiB
Markdown
# 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`**（「我该把测试写在哪里？」与「新技能最小测试清单」）。
|