Skip to main content

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

Metadata

Release files for auto-api-test 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for auto-api-test 0.1.0
File Size Uploaded Provenance Actions
auto_api_test-0.1.0.tar.gz 23.3 kB Without provenance Details for auto_api_test-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for auto-api-test 0.1.0
File Interpreter ABI Platform Actions
auto_api_test-0.1.0-py3-none-any.whl Python 3 none any Details for auto_api_test-0.1.0-py3-none-any.whl

Total release size: 42.7 kB

Release files / auto_api_test-0.1.0.tar.gz

Download URL auto_api_test-0.1.0.tar.gz
Size 23.3 kB
Tags Source
SHA-256 checksum
How to use checksums
63c158fcb8c13e3fe0c5a9d1afdebc75568b52655549011a4f5b592229fbd773
BLAKE2b-256 checksum
How to use checksums
5bd10acd9b3f7440909e87b31b9dd017c13faa1e3d135dcccf72c59fe75bb99d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Release files / auto_api_test-0.1.0-py3-none-any.whl

Download URL auto_api_test-0.1.0-py3-none-any.whl
Size 19.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cdf16f8b51569943d9fb86012c3961ad8a1675e7b394b00936c3515708ce3422
BLAKE2b-256 checksum
How to use checksums
0ae767a115c5216757dd2d73a179d210e0ed3a53bf6bfdc9d582603ed6a75ed4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.3

Security for auto-api-test 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page