auto-api-test 0.1.0

YAML DSL API testing framework based on pytest and requests

auto-api-test

基于 pytest + requests 的 YAML DSL 接口测试框架。

安装

pip install auto-api-test

快速开始

1. 创建测试用例

config:
  base_url: "https://api.example.com"
  timeout: 30
  headers:
    Authorization: "Bearer ${API_TOKEN}"

tests:
  - name: "获取用户列表"
    request:
      method: GET
      url: /users
      params:
        page: 1
    expect:
      status_code: 200
      json:
        code: 0
        data.len: ">0"
    extract:
      first_user_id: "data.0.id"

  - name: "获取用户详情"
    request:
      method: GET
      url: "/users/${first_user_id}"
    expect:
      status_code: 200
      json:
        name: "not_null"

2. 运行测试

# 使用 atr 命令
atr run tests/

# 或直接使用 pytest
pytest tests/

3. 查看报告

测试完成后会在 YAML 文件所在目录生成 report.md。可通过 -o 指定其他路径。

CLI 命令

# 运行测试
atr run <yaml_path_or_dir>
  -o, --report PATH    报告输出路径（默认 YAML 同目录/report.md）
  -v, --verbose        详细输出
  --env-file PATH      环境变量文件（.env 格式）
  --base-url URL       覆盖 config.base_url

# 创建示例文件
atr init [filename]

YAML DSL 语法

config 配置

config:
  base_url: "https://api.example.com"  # 基础 URL
  timeout: 30                           # 请求超时（秒）
  headers:                              # 默认请求头
    Authorization: "Bearer ${TOKEN}"

test 用例

tests:
  - name: "用例名称"
    request:
      method: GET                     # HTTP 方法
      url: /api/path                  # 请求路径
      headers:                        # 请求头（覆盖 config）
        X-Custom: value
      params:                         # URL 参数
        key: value
      json:                           # JSON 请求体
        field: value
      body: "raw body"                # 原始请求体
    expect:
      status_code: 200                # 期望状态码
      json:                           # 期望 JSON 字段
        field: value
      headers:                        # 期望响应头
        Content-Type: "application/json"
    extract:                          # 提取变量供后续用例使用
      var_name: "json.field.path"

断言表达式

字段值以运算符前缀开头时视为表达式：

表达式	含义	示例
>0	大于	data.len: ">0"
<100	小于	count: "<100"
>=1	大于等于	total: ">=1"
<=999	小于等于	id: "<=999"
~=pattern	正则匹配	email: "~=.*@.*\\.com"
contains:sub	包含字符串	message: "contains:success"
not_null	非空	id: "not_null"
is_null	为空	deleted_at: "is_null"
is_true	为真	active: "is_true"
is_false	为假	banned: "is_false"
(其他)	精确匹配	status: "active"

嵌套字段访问

使用点号分隔访问嵌套字段：

json:
  data.user.name: "test"      # data -> user -> name
  data.items.0.id: "not_null" # data -> items -> 第0个 -> id
  data.items.len: ">0"        # data -> items 的长度

变量提取与引用

tests:
  - name: "创建资源"
    request:
      method: POST
      url: /resources
      json:
        name: "test"
    expect:
      status_code: 201
    extract:
      resource_id: "data.id"

  - name: "获取资源"
    request:
      method: GET
      url: "/resources/${resource_id}"
    expect:
      status_code: 200

环境变量

使用 ${VAR_NAME} 引用环境变量：

config:
  headers:
    Authorization: "Bearer ${API_TOKEN}"

可通过 --env-file 加载 .env 文件：

atr run tests/ --env-file .env

Issue 自动创建

测试失败时可自动向 Git 平台提交工单。支持 GitHub、GitLab、Gitea、Gitee。

配置

config:
  base_url: "https://api.example.com"
  issue:
    enabled: true
    platform: github          # github | gitlab | gitea | gitee
    repo: "owner/repo"        # 仓库路径
    base_url: ""              # 自托管平台 API 地址（可选，默认使用平台官方地址）
    labels:                   # issue 标签（可选）
      - bug
      - auto-test

Token

通过环境变量 git_token 提供认证 token：

export git_token="ghp_xxxx"
atr run tests/

或通过 .env 文件：

# .env
git_token=ghp_xxxx

atr run tests/ --env-file .env

平台说明

平台	默认 API 地址	Token 类型
GitHub	https://api.github.com	Personal Access Token
GitLab	https://gitlab.com	Private Token
Gitea	需配置 base_url	API Token
Gitee	https://gitee.com	Personal Access Token

每个失败的测试用例会自动创建一个 issue，包含用例名称、请求信息、断言失败详情和响应体。

使用方式

方式一：atr CLI（推荐）

atr run tests/
atr run tests/api.yaml -o report.md -v
atr run tests/ --env-file .env --base-url https://staging.api.com

方式二：pytest

pytest tests/
pytest tests/ --report report.md -v

License

Apache License 2.0