# 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 与实际响应不一致。