Metadata-Version: 2.4
Name: auto-api-test
Version: 0.1.0
Summary: YAML DSL API testing framework based on pytest and requests
License: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest>=7.0
Requires-Dist: requests
Requires-Dist: pyyaml
Requires-Dist: python-dotenv
Dynamic: license-file

# auto-api-test

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

## 安装

```bash
pip install auto-api-test
```

## 快速开始

### 1. 创建测试用例

```yaml
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. 运行测试

```bash
# 使用 atr 命令
atr run tests/

# 或直接使用 pytest
pytest tests/
```

### 3. 查看报告

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

## CLI 命令

```bash
# 运行测试
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 配置

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

### test 用例

```yaml
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"` |

### 嵌套字段访问

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

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

### 变量提取与引用

```yaml
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}` 引用环境变量：

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

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

```bash
atr run tests/ --env-file .env
```

## Issue 自动创建

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

### 配置

```yaml
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：

```bash
export git_token="ghp_xxxx"
atr run tests/
```

或通过 `.env` 文件：

```bash
# .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（推荐）

```bash
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

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

## License

Apache License 2.0
