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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.