第4章 零基础接口自动化到 Jenkins 持续集成【写第一个 YAML 接口测试用例】

第4章 写第一个 YAML 接口测试用例

本章目标

在不修改框架代码的前提下，新增一个可执行用例。

1. 命名规则

• 文件必须以 _test.yaml 结尾
• 登录用例建议 01_login_test.yaml（便于优先执行）

2. 最小模板

在 data/ 下新增 demo_test.yaml：

- project: "演示项目"
  module: "基础模块"
  api_name: "健康检查"
  title: "健康检查返回200" 
  base_url_key: "admin_url"
  request:
    method: "GET"
    url: "/ping"
    params:
      t: 1
  validate:
    - eq: ["status_code", 200]

3. 常用字段含义

• project/module/api_name/title：报告分组和标题
• base_url_key：在 config/config.yaml 中找域名（如 admin_url、sale_admin_url）
• request：请求参数
• validate：断言规则

4. 按接口请求方式写用例（GET / POST / 文件上传）

4.1 GET 请求（一般用 params）

- project: "演示项目"
  module: "用户模块"
  api_name: "用户详情"
  title: "GET-查询用户详情"
  base_url_key: "admin_url"
  request:
    method: "GET"
    url: "/api/user/detail"
    params:
      userId: 10001
  validate:
    - eq: ["status_code", 200]
    - eq: ["json.code", 0]

4.2 POST 请求（JSON 请求体，用 json）

- project: "演示项目"
  module: "订单模块"
  api_name: "创建订单"
  title: "POST-JSON创建订单成功"
  base_url_key: "sale_admin_url"
  request:
    method: "POST"
    url: "/api/order/create"
    headers:
      Content-Type: "application/json"
    json:
      productId: 1001
      count: 1
  validate:
    - eq: ["status_code", 200]
    - eq: ["json.code", 0]

4.3 POST 请求（Form 请求体，用 data）

- project: "演示项目"
  module: "登录模块"
  api_name: "账号登录"
  title: "POST-Form登录成功"
  base_url_key: "admin_url"
  request:
    method: "POST"
    url: "/api/admin/v2/account/login"
    headers:
      Content-Type: "application/x-www-form-urlencoded"
    data:
      username: "test"
      password: "123456"
  validate:
    - eq: ["status_code", 200]
    - eq: ["json.code", 0]

4.4 文件上传（files + 可选 data）

- project: "演示项目"
  module: "文件模块"
  api_name: "上传头像"
  title: "POST-文件上传成功"
  base_url_key: "admin_url"
  request:
    method: "POST"
    url: "/api/file/upload"
    files:
      file: "mock-binary-content"
    data:
      bizType: "avatar"
  validate:
    - eq: ["status_code", 200]
    - eq: ["json.code", 0]

说明：

• 当前框架会把 files 原样透传给 requests，不同接口网关对上传格式要求不同。
• 如果你的接口要求"真实文件流"，建议先和后端确认入参格式；必要时可在框架里补一层"本地路径转文件对象"的封装再统一使用。

5. 按返回值格式写断言（json 与业务 data 字段）

框架断言支持：

• status_code：HTTP 状态码
• json.xxx：响应 JSON 字段路径（例如 json.code、json.data.id）

常见写法：

validate:
  - eq: ["status_code", 200]
  - eq: ["json.code", 0]
  - contains: ["json.msg", "success"]
  - contains: ["json.data", "list"]

说明：这里的 json.data 指"响应 JSON 里的 data 字段"，不是请求体里的 data 参数。

6. 接口鉴权取值与复用（最常用模板）

6.1 登录接口提取 token

- project: "演示项目"
  module: "登录模块"
  api_name: "登录接口"
  title: "登录成功提取token"
  base_url_key: "admin_url"
  request:
    method: "POST"
    url: "/api/login"
    json:
      username: "test"
      password: "123456"
  extract:
    auth_token: "data.token"
  validate:
    - eq: ["status_code", 200]
    - eq: ["json.code", 0]

6.2 后续接口使用 token

方式一（推荐）：自动注入鉴权头

request:
  method: "POST"
  url: "/api/order/list"
  need_auth: true

方式二：手动引用变量

request:
  method: "GET"
  url: "/api/user/info"
  headers:
    Authorization: "Bearer ${auth_token}"

7. 执行测试

python3 run.py

8. 查看结果

• 报告里出现你的 title
• 失败时查看 logs/ 中请求和响应内容

本章验收标准

• 能分别写出 GET、POST(JSON)、POST(Form)、文件上传 4 类用例
• 能根据返回结构写 json.code、json.data.xxx 断言
• 能完成"登录提取 token -> 后续接口复用"链路