# no-code-auto-api-test

**Repository Path**: blackhades/no-code-auto-api-test

## Basic Information

- **Project Name**: no-code-auto-api-test
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-06-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pytest 接口自动化测试框架

基于 **Python + pytest + YAML + requests + allure/pytest-html** 的接口自动化测试框架，测试人员只需维护 YAML 用例文件，零代码即可完成接口测试。

测试靶场：https://dummyjson.com/

## 技术栈

| 组件 | 用途 |
|------|------|
| Python 3.8+ | 开发语言 |
| pytest | 测试框架 |
| PyYAML | 用例数据管理 |
| requests | HTTP 请求 |
| jsonpath-ng | 响应数据提取 |
| loguru | 日志记录 |
| allure-pytest | Allure 报告数据生成 |
| pytest-html | HTML 报告生成 |
| pytest-xdist | 多进程并行执行 |
| Jenkins | CI/CD 集成 |

## 目录结构

```
api-test/
├── config/                  # 全局配置
│   ├── conf.yaml            # 多环境配置（host、数据库、账号等）
│   └── setting.py           # 配置加载，暴露为全局变量
├── data/                    # 测试用例（YAML）
│   ├── login.yml
│   ├── products.yml
│   └── user.yml
├── testcases/               # 自动生成的 pytest 测试代码（勿手动修改）
├── utils/                   # 工具层
│   ├── assertion/           # 断言引擎（jsonpath + 多操作符）
│   ├── cache_process/       # 缓存管理器（接口间依赖数据传递）
│   ├── logUtils/            # 日志配置
│   ├── readFilesUtils/      # YAML 解析 + 用例代码生成器
│   └── requestsUtils/       # HTTP 请求封装
├── report/                  # 测试报告输出（gitignore）
├── logs/                    # 日志输出（gitignore）
├── conftest.py              # pytest 全局 fixture（环境切换、缓存）
├── pytest.ini               # pytest 配置
├── run.py                   # 一键运行入口
├── Jenkinsfile              # Jenkins CI 配置
└── requirements.txt         # Python 依赖
```

## 快速开始

### 1. 环境准备

```bash
# 克隆项目
git clone <your-repo-url>
cd api-test

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境（Windows）
.venv\Scripts\activate
# 激活虚拟环境（Mac/Linux）
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置环境

编辑 `config/conf.yaml`，将 `active` 设置为当前要用的环境：

```yaml
active: dev    # 可选 dev / test / staging
```

### 3. 编写用例

在 `data/` 目录下创建 `.yml` 文件，写用例（详见下方 [YAML 用例编写指南](#yaml-用例编写指南)）。

### 4. 运行测试

```bash
# 一键：生成用例 + 执行测试 + 出报告
python run.py

# 或手动分步
python run.py          # 生成测试代码
pytest testcases/ -v   # 执行测试
```

### 5. 查看报告

```bash
# 浏览器打开 HTML 报告
start report/report.html
```

## YAML 用例编写指南

### 基础用例（无依赖）

```yaml
# data/products.yml
get_all_products_01:
  name: 获取所有产品列表-默认分页
  url: /products
  method: GET
  requestType: params          # URL 参数（params：URL参数，json：JSON请求体，data：表单，file：文件上传）
  data:
    limit: 10
    skip: 0
  assert:
    - jsonpath: $.products
      type: "!="
      value: null
    - jsonpath: $.limit
      type: "=="
      value: 10
    - jsonpath: $.total
      type: ">"
      value: 0
```

### 用例字段说明

| 字段 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | 否 | 用例名 | 用例描述，显示在报告中 |
| `url` | 是 | - | 请求路径（相对路径自动拼接配置中的 host） |
| `method` | 否 | GET | GET / POST / PUT / DELETE / PATCH |
| `requestType` | 否 | json（GET 自动推断为 params） | 参数类型：`params` / `json` / `data` / `file` |
| `headers` | 否 | {} | 用例级请求头（会与全局头合并） |
| `data` | 否 | {} | 请求参数 |
| `dependence_case` | 否 | false | 是否需要读取缓存数据 |
| `setup` | 否 | [] | 提取响应数据写入缓存（见依赖用例） |
| `assert` | 否 | [] | 断言配置列表 |

### 断言操作符

| 操作符 | 说明 | 示例 |
|--------|------|------|
| `==` | 等于 | `"type": "==", "value": 0` |
| `!=` | 不等于 | `"type": "!=", "value": null` |
| `>` | 大于 | `"type": ">", "value": 0` |
| `<` | 小于 | `"type": "<", "value": 10` |
| `>=` | 大于等于 | `"type": ">=", "value": 5` |
| `<=` | 小于等于 | `"type": "<=", "value": 100` |
| `contains` | 包含子串 | `"type": "contains", "value": "@"` |
| `in` | 在列表中 | `"type": "in", "value": ["a","b"]` |

### 依赖用例（接口 B 使用接口 A 返回的数据）

**第一步**：前置接口提取数据写入缓存

```yaml
# data/login.yml
login_success_01:
  name: 登录成功-正常账号
  url: /auth/login
  method: POST
  requestType: json
  data:
    username: emilys
    password: emilyspass
  setup:                            # 将响应中的字段写入缓存
    - jsonpath: $.accessToken
      cache_key: login_token        # 缓存 key
    - jsonpath: $.id
      cache_key: user_id
  assert:
    - jsonpath: $.accessToken
      type: "!="
      value: null
```

**第二步**：后续接口通过 `$cache{key}` 读取缓存

```yaml
# data/user.yml
get_current_user_01:
  name: 获取当前用户信息-依赖登录token
  url: /auth/me
  method: GET
  headers:
    Authorization: "Bearer $cache{login_token}"    # 从缓存读取 token
  dependence_case: true                             # 标记为依赖用例
  assert:
    - jsonpath: $.username
      type: "=="
      value: emilys
```

> **注意**：依赖用例的执行顺序依赖文件名排序（字母序）。确保前置用例所在的 YAML 文件名排在后续用例之前（如 `login.yml` < `user.yml`）。

### POST 请求示例

```yaml
create_something:
  name: 创建资源
  url: /api/v1/resource
  method: POST
  requestType: json
  data:
    name: test_item
    type: demo
  assert:
    - jsonpath: $.id
      type: "!="
      value: null
```

## 多环境切换

### 方式一：修改 conf.yaml

```yaml
active: test    # 改为目标环境名
```

### 方式二：命令行参数

```bash
python run.py --env=test
pytest testcases/ --env=staging
```

### 环境配置结构

```yaml
dev:
  host: https://dummyjson.com       # 接口域名
  mysql: {...}                       # 数据库配置（按需）
  redis: {...}                       # Redis 配置（按需）
  account:                           # 测试账号
    username: emilys
    password: emilyspass
  headers:                           # 全局请求头
    Content-Type: application/json
    Accept: application/json

test:
  host: https://dummyjson.com
  # ... 同上结构
```

## 日志

日志文件按天切割，存放于 `logs/` 目录，保留 30 天。

- **控制台输出**：INFO 级别
- **文件输出**：DEBUG 级别（更详细），文件名格式 `YYYY-MM-DD.log`

出问题时优先查看日志文件，每个请求的完整 URL、Header、Body、响应都会记录。

## 报告

### pytest-html 报告（默认）

运行 `python run.py` 后自动生成 `report/report.html`，直接浏览器打开即可。

### Allure 报告（可选，需安装 allure CLI）

```bash
# 生成 Allure 原始数据
pytest --alluredir=report/allure_results --clean-alluredir

# 生成 HTML 报告
allure generate report/allure_results -o report/allure_html --clean

# 打开报告
allure open report/allure_html
```

Allure CLI 安装：https://github.com/allure-framework/allure2/releases

## Jenkins CI 集成

### Jenkins 侧配置

1. 安装插件：HTML Publisher、Pipeline、Git
2. 新建 Pipeline 项目 → 指向仓库 → Script Path: `Jenkinsfile`
3. 定时触发已配置为工作日早上 8 点

### 手动构建时选择环境

Jenkins → Build with Parameters → 下拉选择 dev/test/staging

### 查看历史报告

Build 页面 → "API Test Report" 链接

## 常见问题

**Q: 新增一个 YAML 文件后需要手动做什么？**

A: 不需要，运行 `python run.py` 会自动扫描 `data/` 目录下的所有 `.yml`/`.yaml` 文件并生成对应测试代码。

**Q: 为什么依赖用例单独跑时会失败？**

A: 依赖数据存储在 pytest session 级别的缓存中，单独跑一个文件时前置接口没执行，缓存为空。跑全量用例即可。

**Q: 生成的 testcases/ 目录下的文件需要提交到 git 吗？**

A: 建议不提交，每次 `run.py` 自动生成。`.gitignore` 中可加上 `testcases/`。

**Q: 如何接入公司内部 API？**

A: 修改 `config/conf.yaml` 中对应环境的 `host` 为内部 API 地址即可，其他代码不需改动。如需签名认证，在 `utils/requestsUtils/request_handler.py` 的 `send_request` 方法中加入签名逻辑。