TBC/specs/API-TEST-SPEC.md
d-robotics 633a797226 AutoFlow v2.0: 合并 Test (Robogo) + data-loop-automation (D-Cloud) 为统一平台
- 16 个业务模块,856 个测试用例,40 个 E2E 测试
- 单一 React 19 前端 + PlatformSwitcher 二合一切换
- Flask 后端支持 scenario/dcloud_module/dcloud_e2e/dcloud_all 四种任务类型
- E2E 测试面板:API 全链路(8条) + UI 点击(3条) + 分步测试(3个)
- SSE 实时日志流 + 飞书告警 + 定时调度
- 完整还原原 ToB 平台 TestPanel E2E 模块
2026-06-23 11:48:29 +08:00

108 lines
2.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# API 自动化测试规范
## 文档联动关系
本文档规定 API 自动化测试怎么写,不定义具体业务接口行为。具体接口资料来自 `swagger/`、实际请求日志、业务需求和模块测试代码。
| 文档或目录 | 关系 | 使用场景 |
| --- | --- | --- |
| `../README.md` | 主索引 | 判断是否需要读取本文档 |
| `AUTOMATION-SPEC.md` | 工程总规范 | 了解运行、日志、清理 |
| `TEST-WRITING-SPEC.md` | 测试代码规范 | 编写 pytest 测试 |
| `TEST-CASES-SPEC.md` | 用例文档规范 | 同步 API 测试用例 |
| `../swagger/` | 接口原始资料 | 查询接口路径、参数和响应 |
| `../api_docs/` | API 对接文档 | 沉淀接口说明和调用约定 |
| `../tests/utils/api_client.py` | API 客户端 | 复用请求封装 |
## 1. 适用范围
本文档适用于:
- API 连通性测试。
- 业务状态码和关键字段验证。
- 参数边界和异常响应验证。
- 多接口业务流程编排。
- UI 测试前置数据创建和清理。
## 2. 最低断言
API 测试默认至少包含三层验证:
1. HTTP 状态码。
2. 业务状态码,例如 `status == 0`。
3. `data` 中关键字段或响应结构。
示例:
```python
response = api_client.post("/api/example/list", json={"page": 1, "pageSize": 20})
assert response.status_code == 200
result = response.json()
assert result["status"] == 0
assert "data" in result
```
仅检查 HTTP 状态码的场景,应在测试说明中写明原因。
## 3. 响应结构
常见成功响应:
```json
{
"status": 0,
"message": "success",
"data": {}
}
```
常见失败响应:
```json
{
"status": 50000,
"message": "invalid params",
"data": null
}
```
不同业务接口如果返回 `code`、`pageInfo`、`currentPage`、`pageSize` 等字段,应在测试或 `api_docs/` 中记录清楚。
## 4. 边界测试
边界测试至少考虑:
- 空参数。
- 缺失必填字段。
- 非法 ID。
- 超大页码和页大小。
- 负数、零值、空字符串。
- 特殊字符。
- 重复创建或重复提交。
- 资源不存在。
- 无权限或认证失效。
边界测试可以允许业务失败,但仍应验证失败结构可解释、不会导致服务异常。
## 5. 日志要求
API 测试应通过项目 API 客户端或 logger 记录:
- 当前测试用例名称。
- 方法和路径。
- 关键请求体或查询参数。
- HTTP 状态码。
- 关键响应字段。
日志不得记录真实密码、token、cookie 或敏感业务数据。
## 6. 文档回写
出现以下情况时,应更新 `api_docs/`、`test_cases/` 或 `history.md`:
- 新增接口测试。
- 接口路径、Header、参数或响应结构变化。
- 业务状态码或错误码规则变化。
- API 仅能做连通性验证且原因需要长期保留。
- Swagger 与实际响应不一致。