# api_test

**Repository Path**: vsvzyy/api_test

## Basic Information

- **Project Name**: api_test
- **Description**: 基于 pytest 的分层 API 自动化测试框架。按服务拆分 Client 封装接口，通过 JSON 数据驱动用例，fixture 自动管理认证和环境切换，单接口覆盖正常/未授权/参数异常/边界四种场景，Allure 生成测试报告
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 接口自动化测试框架

pytest + requests + JSON 数据驱动。Client 封装业务接口，auth 由调用方通过 headers 控制。

---

## 目录结构

```
config/                JSON 环境配置（test.json / prod.json / dev.json）
clients/               接口封装层（每个服务一个 Client 类）
utils/
  base_client.py       HTTP 封装（URL 拼接、超时、日志、Allure 附件）
  read_data.py         数据文件读取（.json / .json5，递归扫描 data/ 目录）
  allure_util.py       Allure 附件工具
  logger.py            日志初始化
data/                  JSON 测试数据文件（按业务模块拆分）
test_cases/
  single/              单接口测试
  e2e/                 场景化测试
local_debug_run.py     本地 Mock Server + 调试启动脚本
conftest.py            全局 fixture（config / base_url / auth_token / auth_header / client 实例）
pytest.ini             pytest 配置
run.py                 一键运行脚本
```

## 分层架构

| 层 | 文件 | 职责 |
|---|---|---|
| 用例层 | `test_cases/single/` | 单接口参数化测试，数据从 data/ 读取 |
| | `test_cases/e2e/` | 场景化流程测试 |
| Fixture 层 | `conftest.py` | 注入 base_url、auth_token、auth_header、client 实例 |
| 接口封装层 | `clients/` | 每个服务一个 Client 类，继承 BaseClient，方法用 `**kwargs` 透传 |
| 工具层 | `utils/base_client.py` | HTTP 请求封装，自动记录请求/响应日志到 Allure |
| | `utils/read_data.py` | 递归扫描 data/ 目录，按文件名读取 JSON 数据 |
| 数据层 | `data/` | JSON 测试数据文件，按模块拆分 |
| 配置层 | `config/` | 按环境拆分的 JSON 配置文件 |
| Mock 层 | `local_debug_run.py` | Flask Mock Server，仅本地调试用 |

## 快速开始

```bash
# 安装 Allure（macOS）
brew install allure

# 搭建虚拟环境
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 运行测试
python3 local_debug_run.py &   # 后台启动 Mock Server
pytest -v                        # 跑测试
kill %1                          # 停止 Mock Server

# 或用一键脚本
python3 run.py

# 查看报告
open reports/allure-report/index.html
```

## 核心设计

| 场景 | 写法 |
|---|---|
| 已登录 | `client.get_profile(headers=auth_header)` |
| 未登录 | `client.get_profile()` |
| 请求体 | `client.create_item(json={"name": "xx", "price": 99})` |
| 切换环境 | `export TEST_ENV=prod && pytest` |

`auth_header` 返回 `{"Authorization": "Bearer {token}"}`，session 级缓存，自动从 config 中的测试账号登录获取。

## 数据驱动

测试数据放在 `data/` 目录下的 JSON 文件中，按 `normal` / `abnormal` 分组：

```json
{
    "normal": [
        {"username": "testuser", "password": "pass123", "expected_code": 0, "expected_message": "登录成功"}
    ],
    "abnormal": [
        {"username": "testuser", "password": "wrongpwd", "expected_code": 1001, "expected_message": "用户名或密码错误"}
    ]
}
```

用例中通过 `read_test_data` 读取：

```python
from utils.read_data import read_test_data

USER = read_test_data("user_data")

class TestLogin:
    @pytest.mark.parametrize("case", USER["normal"])
    def test_normal(self, user_client, case):
        ...

    @pytest.mark.parametrize("case", USER["abnormal"])
    def test_abnormal(self, user_client, case):
        ...
```

## 添加新接口

### 1. 创建 Client

```python
# clients/xxx_client.py
from utils.base_client import BaseClient

class XxxClient(BaseClient):
    def create_xxx(self, **kwargs):
        return self._request("POST", "/api/xxx", **kwargs)

    def get_xxx(self, obj_id, **kwargs):
        return self._request("GET", f"/api/xxx/{obj_id}", **kwargs)
```

### 2. 注册 fixture

```python
# conftest.py
from clients.xxx_client import XxxClient

@pytest.fixture
def xxx_client(base_url):
    return XxxClient(base_url)
```

### 3. 添加测试数据

```json
// data/xxx_data.json
{
    "normal": [
        {"name": "test", "expected_code": 0}
    ],
    "abnormal": [
        {"name": "", "expected_code": 1002}
    ]
}
```

### 4. 编写测试

```python
# test_cases/single/test_xxx.py
from utils.read_data import read_test_data

DATA = read_test_data("xxx_data")

class TestXxx:
    @pytest.mark.parametrize("case", DATA["normal"])
    def test_normal(self, xxx_client, auth_header, case):
        resp = xxx_client.create_xxx(json=case, headers=auth_header)
        assert resp.json()["code"] == case["expected_code"]

    def test_without_auth(self, xxx_client):
        assert xxx_client.create_xxx(json={"name": "test"}).status_code == 401
```

### 5. （可选）Mock 接口

在 `local_debug_run.py` 的 Flask app 中加路由。

## 配置切换

```bash
export TEST_ENV=prod     # 切换到生产环境
pytest                    # 自动读取 config/prod.json
```

## 技术栈

pytest · requests · Flask（Mock Server）· Allure（报告）