# fgeinterface

**Repository Path**: yaoqis/fgeinterface

## Basic Information

- **Project Name**: fgeinterface
- **Description**: fgeinterface
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-10
- **Last Updated**: 2026-09-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 接口自动化框架使用说明

## 1. 框架简介

本项目是基于 `Python + pytest + Allure + YAML` 的接口自动化测试框架，适用于企业级接口自动化测试。

框架特点：

- 使用 YAML 文件维护接口测试数据
- 使用 pytest 管理和执行测试用例
- 支持 Allure 测试报告
- 支持接口返回值断言
- 支持接口数据提取和变量复用
- 支持 token 自动获取和替换
- 支持数据库断言
- 适合快速迁移到其他接口项目中使用

## 2. 环境准备

### 2.1 安装 Python

建议使用 `Python 3.8+`。

检查 Python 是否安装成功：

```bash
python --version
```

### 2.2 安装依赖

在项目根目录执行：

```bash
pip install pytest allure-pytest pyyaml requests jsonpath pymysql colorlog
```

如果项目后续提供了 `requirements.txt`，可以直接执行：

```bash
pip install -r requirements.txt
```

### 2.3 安装 Allure

如果需要查看 Allure 报告，需要本地安装 Allure。

安装完成后检查：

```bash
allure --version
```

## 3. 项目目录说明

```text
interfaceAuto/
├── configs/                       # 配置文件
│   ├── config.ini                 # 接口域名、数据库配置
│   └── setting.py                 # 项目路径、通知等配置
├── data/                          # YAML 测试数据
│   └── testcases/                 # 各模块测试数据
├── testcase/                      # pytest 测试用例代码
│   ├── conftest.py                # 登录 token fixture
│   ├── login/                     # 登录相关用例
│   ├── inquiry/                   # 询价模块
│   ├── purchaseOrder/             # 采购订单模块
│   └── supplyCenter/              # 供应中心模块
├── unit_tools/                    # 框架核心工具
│   ├── apiutils_single.py         # 单接口执行引擎
│   ├── apiutils_business.py       # 业务流程执行引擎
│   ├── sendrequests.py            # HTTP 请求封装
│   ├── assertion_utils.py         # 断言工具
│   ├── token_util.py              # token 替换工具
│   ├── debugtalk.py               # 动态变量函数
│   ├── handle_data/               # YAML、配置文件解析
│   ├── db_connector/              # 数据库连接
│   └── other_util/                # 通知工具
├── extract.yaml                   # 接口提取数据临时文件
├── conftest.py                    # 全局 pytest 钩子
├── pytest.ini                     # pytest 配置
└── run.py                         # 执行入口
```

## 4. 如何迁移到新项目

如果要将该框架用于其他接口自动化项目，一般只需要修改以下几部分。

### 4.1 修改接口域名

打开：

```text
configs/config.ini
```

修改接口地址：

```ini
[Host]
host = https://your-business-host.com
auth_host = https://your-auth-host.com
```

说明：

- `host`：业务接口域名
- `auth_host`：登录认证接口域名

如果新项目没有单独的认证域名，可以让两者保持一致。

### 4.2 修改数据库配置

如果项目需要数据库断言，修改：

```ini
[MySQL]
host = your-db-host
port = 3306
user = your-db-user
password = your-db-password
```

如果暂时不使用数据库断言，可以先不配置。

### 4.3 修改登录认证逻辑

当前框架默认是 CAS 三步登录：

1. `POST /uac/cas/rest/login` 获取 TGC
2. `POST /uac/cas/v1/tickets` 使用 TGC 获取 ticket
3. `GET /scm?ticket={ticket}` 使用 ticket 获取 token

相关代码在：

```text
testcase/conftest.py
```

如果新项目不是 CAS 登录，需要根据新项目的登录方式修改 `get_token` fixture。

测试用例中统一通过 `get_token` 获取 token，不建议在每个用例里单独写登录逻辑。

## 5. 如何新增一个接口测试用例

新增接口用例一般分两步：

1. 新增 YAML 测试数据
2. 新增 pytest 测试文件

### 5.1 新增 YAML 测试数据

例如新增一个订单查询接口，可以创建文件：

```text
data/testcases/order/query_order.yaml
```

示例内容：

```yaml
- baseInfo:
    api_name: 查询订单列表
    url: /order/query
    method: post
    headers:
      Content-Type: "application/json"
      Cas-Auth-Token: "${Cas-Auth-Token}"
  testCase:
    - case_name: 查询订单列表成功
      json:
        pageNum: 1
        pageSize: 20
      validation:
        - code: 200
        - eq: {'success': true}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `api_name` | 接口名称 |
| `url` | 接口路径 |
| `method` | 请求方法，例如 `get`、`post`、`put`、`delete` |
| `headers` | 请求头 |
| `json` | JSON 请求体 |
| `params` | URL 查询参数 |
| `validation` | 断言规则 |
| `extract` | 提取接口返回值，供后续接口使用 |

### 5.2 新增 pytest 测试文件

创建文件：

```text
testcase/order/test_query_order.py
```

示例代码：

```python
import pytest
import allure
from unit_tools.apiutils_single import RequestsBase
from unit_tools.handle_data.yaml_handler import read_yaml
from unit_tools.token_util import replace_token


@allure.feature('订单模块')
class TestQueryOrder:

    @allure.story('查询订单列表')
    @allure.title('{testcase[case_name]}')
    @pytest.mark.parametrize(
        'base_info,testcase',
        read_yaml('./data/testcases/order/query_order.yaml')
    )
    def test_query_order(self, base_info, testcase, get_token):
        allure.dynamic.title(testcase['case_name'])

        updated_base_info = replace_token(base_info, get_token)
        updated_testcase = replace_token(testcase, get_token)

        RequestsBase().execute_test_cases(updated_base_info, updated_testcase)
```

## 6. YAML 用例编写规范

### 6.1 POST 请求示例

```yaml
- baseInfo:
    api_name: 新增用户
    url: /user/create
    method: post
    headers:
      Content-Type: "application/json"
      Cas-Auth-Token: "${Cas-Auth-Token}"
  testCase:
    - case_name: 新增用户成功
      json:
        name: 张三
        age: 18
      validation:
        - code: 200
        - eq: {'success': true}
```

### 6.2 GET 请求示例

```yaml
- baseInfo:
    api_name: 查询用户详情
    url: /user/detail
    method: get
    headers:
      Cas-Auth-Token: "${Cas-Auth-Token}"
  testCase:
    - case_name: 查询用户详情成功
      params:
        userId: 10001
      validation:
        - code: 200
        - eq: {'success': true}
```

## 7. 支持的断言方式

| 断言类型 | 说明 | 示例 |
| --- | --- | --- |
| `code` | 校验 HTTP 状态码 | `- code: 200` |
| `eq` | 校验字段等于指定值 | `- eq: {'success': true}` |
| `ne` | 校验字段不等于指定值 | `- ne: {'msg': '失败'}` |
| `contain` | 校验字段包含指定内容 | `- contain: {'msg': '成功'}` |
| `db` | 数据库断言 | `- db: {sql: "SELECT count(*) FROM table", expected: 1}` |

示例：

```yaml
validation:
  - code: 200
  - eq: {'success': true}
  - contain: {'msg': '成功'}
```

## 8. 接口数据提取和复用

如果接口 A 返回的数据需要给接口 B 使用，可以使用 `extract`。

### 8.1 提取返回值

```yaml
extract:
  order_id: "$.data.orderId"
```

提取后，数据会保存到：

```text
extract.yaml
```

### 8.2 使用提取值

在后续 YAML 中使用：

```yaml
orderId: "${get_extract_data(order_id)}"
```

## 9. token 替换规则

YAML 中如果需要使用登录 token，请写：

```yaml
Cas-Auth-Token: "${Cas-Auth-Token}"
```

测试代码中会通过：

```python
replace_token(base_info, get_token)
replace_token(testcase, get_token)
```

自动替换成真实 token。

## 10. 动态变量使用

动态变量函数定义在：

```text
unit_tools/debugtalk.py
```

常用函数：

| 函数 | 说明 |
| --- | --- |
| `${get_extract_data(token)}` | 从 `extract.yaml` 获取已提取的数据 |
| `${get_now_time()}` | 获取当前时间戳 |

示例：

```yaml
json:
  orderNo: "AUTO_${get_now_time()}"
```

如果新项目需要随机手机号、随机名称、随机编码等，可以在 `debugtalk.py` 中新增函数。

## 11. 运行测试

### 11.1 运行全部测试

```bash
pytest
```

### 11.2 运行指定模块

```bash
pytest testcase/order/
```

### 11.3 运行指定测试文件

```bash
pytest testcase/order/test_query_order.py
```

### 11.4 运行单个测试方法

```bash
pytest testcase/order/test_query_order.py::TestQueryOrder::test_query_order -v -s
```

### 11.5 运行测试并生成 Allure 报告

```bash
python run.py
```

## 12. 新项目接入流程

推荐按照下面步骤接入新项目：

1. 复制当前框架代码
2. 修改 `configs/config.ini` 中的接口域名
3. 根据新项目登录方式修改 `testcase/conftest.py` 中的 `get_token`
4. 在 `data/testcases/` 下按业务模块创建 YAML 文件
5. 在 `testcase/` 下创建对应的 pytest 测试文件
6. 编写接口请求参数和断言
7. 执行 `pytest` 验证用例
8. 执行 `python run.py` 查看 Allure 报告

## 13. 编写用例建议

建议每个接口至少覆盖：

- 正常场景
- 必填字段为空
- 参数格式错误
- 权限异常
- 数据不存在
- 分页边界
- 重复提交
- 业务状态不允许操作

例如：

```yaml
testCase:
  - case_name: 查询订单成功
    json:
      pageNum: 1
      pageSize: 20
    validation:
      - code: 200
      - eq: {'success': true}

  - case_name: pageNum为空
    json:
      pageNum:
      pageSize: 20
    validation:
      - code: 200
      - eq: {'success': false}
```

## 14. 注意事项

1. 不要把生产环境账号、密码、数据库密码直接提交到代码仓库。
2. `extract.yaml` 是运行过程中生成和更新的数据，不建议手动维护。
3. 新增接口时，YAML 路径和 pytest 文件路径建议按业务模块保持一致。
4. 如果接口需要 token，必须在 YAML headers 中配置 `${Cas-Auth-Token}`。
5. 如果新项目认证方式不同，只需要统一修改 `get_token`，测试用例不需要改。
6. 修改公共工具类前，需要先确认是否会影响已有用例。

## 15. 常见问题

### 15.1 token 获取失败怎么办？

检查：

- `configs/config.ini` 中的 `auth_host` 是否正确
- 登录账号密码是否正确
- `testcase/conftest.py` 中的登录接口路径是否适配当前项目
- 登录接口返回结构是否发生变化

### 15.2 接口地址拼接错误怎么办？

检查 YAML 中的 `url`。

当前框架规则：

- 以 `/uac/cas` 开头的接口使用 `auth_host`
- 其他接口使用 `host`

### 15.3 YAML 读取失败怎么办？

检查：

- 缩进是否正确
- 冒号后面是否有空格
- 字符串中是否包含特殊字符
- 文件路径是否正确

### 15.4 断言失败怎么办？

可以使用：

```bash
pytest -v -s
```

查看接口请求和响应日志，然后确认：

- 接口返回结构是否变化
- 断言字段是否正确
- 测试数据是否符合当前环境数据

## 16. 一个最小完整示例

YAML 文件：

```text
data/testcases/demo/query_demo.yaml
```

```yaml
- baseInfo:
    api_name: Demo查询接口
    url: /demo/query
    method: post
    headers:
      Content-Type: "application/json"
      Cas-Auth-Token: "${Cas-Auth-Token}"
  testCase:
    - case_name: Demo查询成功
      json:
        pageNum: 1
        pageSize: 10
      validation:
        - code: 200
        - eq: {'success': true}
```

测试文件：

```text
testcase/demo/test_query_demo.py
```

```python
import pytest
import allure
from unit_tools.apiutils_single import RequestsBase
from unit_tools.handle_data.yaml_handler import read_yaml
from unit_tools.token_util import replace_token


@allure.feature('Demo模块')
class TestQueryDemo:

    @allure.story('Demo查询')
    @allure.title('{testcase[case_name]}')
    @pytest.mark.parametrize(
        'base_info,testcase',
        read_yaml('./data/testcases/demo/query_demo.yaml')
    )
    def test_query_demo(self, base_info, testcase, get_token):
        allure.dynamic.title(testcase['case_name'])

        updated_base_info = replace_token(base_info, get_token)
        updated_testcase = replace_token(testcase, get_token)

        RequestsBase().execute_test_cases(updated_base_info, updated_testcase)
```

运行：

```bash
pytest testcase/demo/test_query_demo.py -v -s
```

## 17. 建议补充

为了方便其他同事更快上手，建议后续补充：

1. `configs/config.example.ini`：放示例配置，不放真实账号密码。
2. `data/testcases/demo/` 和 `testcase/demo/`：保留一个可运行的 demo，用例比文字更容易理解。
3. `requirements.txt`：固定依赖版本，避免不同电脑安装出不一致的依赖。