API 自动化测试框架

项目简介

一套完整的API自动化测试框架，支持多环境执行（test/uat/prod）、Excel驱动测试、灵活的用例筛选和详细的测试报告生成。

核心特性：

• 多环境支持：一套代码运行在test/uat/prod三个环境
• Excel驱动：用例配置在Excel中，易于维护
• 灵活筛选：通过env_scope字段控制各环境的执行用例
• 丰富的验证：支持多种关系运算符（$gt、$contains、$regex等）
• 详细报告：HTML和Excel双格式测试报告
• Jenkins集成：参数化执行，支持定时任务
• Docker支持：容器化部署

---

快速开始

需求

• Python 3.8+
• pip 和 venv
• 依赖库（详见requirements.txt）

安装依赖

# 创建虚拟环境
python3 -m venv venv

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

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

准备测试用例

编辑 api_cases.xlsx，在表格中添加新列 env_scope，标记每个用例的执行范围：

env_scope 值说明：
- all 或留空    → 所有环境执行
- test          → 仅测试环境执行
- uat           → 仅UAT环境执行
- prod          → 仅生产环境执行
- test,uat      → 测试和UAT执行，生产跳过

运行测试

# 测试环境
export DEPLOY_ENV=test
python3 api_test.py

# UAT环境
export DEPLOY_ENV=uat
python3 api_test.py

# 生产环境
export DEPLOY_ENV=prod
python3 api_test.py

查看报告

执行完成后，生成的报告文件：

• api_test_report_*_test_*.html - 测试环境HTML报告
• api_test_report_*_uat_*.html - UAT环境HTML报告
• api_test_report_*_prod_*.html - 生产环境HTML报告
• api_test_report_*.xlsx - Excel格式报告

---

Docker 快速开始

前提条件

• Docker 已安装
• docker-compose 已安装

运行命令

测试环境：

docker-compose run --rm -e DEPLOY_ENV=test api-test-runner

UAT环境：

docker-compose run --rm -e DEPLOY_ENV=uat api-test-runner

生产环境：

docker-compose run --rm -e DEPLOY_ENV=prod api-test-runner

报告文件保存在 ./reports 目录

详细说明见 DOCKER_GUIDE.md

---

文档导航

文档	说明	适用场景
USER_GUIDE.md	详细使用指南	如何使用框架、多环境配置、常见问题
DEPLOYMENT_GUIDE.md	部署安装指南	Linux服务器部署、Jenkins配置
DOCKER_GUIDE.md	Docker部署指南	Docker容器化、docker-compose、Jenkins集成
OPERATOR_GUIDE.md	运维指南	关系运算符使用
OPTIMIZATION_REQUIREMENTS.md	优化需求	性能优化、增强建议

---

️ 项目结构

interface_test/
├── 📄 README.md                    # 项目介绍（本文件）
├── 📖 USER_GUIDE.md               # 使用指南
├── 🚀 DEPLOYMENT_GUIDE.md         # Linux部署指南
├── 🐳 DOCKER_GUIDE.md             # Docker部署指南
├── 🔧 OPERATOR_GUIDE.md           # 运维指南
├── 📈 OPTIMIZATION_REQUIREMENTS.md # 优化需求
│
├── 💻 api_test.py          # 主测试脚本
├── ⚙️  env_config.py       # 环境配置（多环境IP）
├── 📊 api_cases.xlsx       # 测试用例（Excel）
├── requirements.txt        # Python依赖
│
├── 🐳 Dockerfile           # Docker镜像配置
├── 📦 docker-compose.yml   # Docker容器编排
├── .dockerignore          # Docker忽略文件
│
├── Jenkinsfile             # Jenkins标准配置（直接执行）
├── Jenkinsfile.docker     # Jenkins Docker配置（容器中执行）
│
└── .venv/                 # Python虚拟环境

---

核心功能

多环境执行

支持三个环境：

环境	IP_HOST	用途
test	ai-test.hikoon.com	测试环境
uat	ai-uat.hikoon.com	UAT验收环境
prod	api.hikoon.com	生产环境

环境选择：

export DEPLOY_ENV=test   # 或 uat / prod
python3 api_test.py

用例筛选

通过 env_scope 列灵活控制用例执行范围：

env_scope = 'all'        → 三环境都执行
env_scope = 'test,uat'   → 生产环境跳过（避免危险操作）
env_scope = 'prod'       → 仅生产环境执行

关系运算符

expected_response 支持多种验证方式：

{
  "code": {"$ne": 500},              // 不等于
  "count": {"$gt": 0},               // 大于
  "status": {"$in": ["ok", "done"]}, // 在列表中
  "msg": {"$contains": "success"},   // 字符串包含
  "email": {"$regex": "^.*@.*$"}     // 正则匹配
}

详见 OPERATOR_GUIDE.md

详细报告

• 统计信息：总数、成功数、失败数、耗时
• 筛选功能：按失败、响应时间筛选
• 详细结果：请求参数、期望值、实际值、错误信息
• 性能分析：响应时间分布
• 环境标识：报告文件名包含运行环境

---

环境配置

env_config.py

定义多个环境的IP和其他变量：

import os

# 多环境IP配置
DEPLOY_ENV = os.getenv('DEPLOY_ENV', 'test')
IP_HOST_MAP = {
    'test': 'ai-test.hikoon.com',
    'uat': 'ai-uat.hikoon.com',
    'prod': 'api.hikoon.com'
}
IP_HOST = os.getenv('IP_HOST', IP_HOST_MAP.get(DEPLOY_ENV, 'ai-test.hikoon.com'))

# 当前日期（格式：YY-MM-DD）
CURRENT_DATE = datetime.now().strftime('%y-%m-%d')

# 其他环境变量
RANDOM_EMAIL = gen_email()  # 自动生成随机邮箱

自定义环境变量

# env_config.py 中添加
API_TOKEN = "your-token-here"
TIMEOUT = 60
DEBUG = True

然后在Excel用例中使用：

URL: {IP_HOST}/api/users
Headers: {"Authorization": "Bearer {API_TOKEN}"}
Params: {"timestamp": "{CURRENT_DATE}"}

---

Excel测试用例格式

字段	说明	示例
case_id	用例ID	1
api_name	接口名称	用户注册
is_run	是否执行（1=跳过）	0
env_scope	执行环围（新增）	all
method	请求方法	POST
ip_host / url	基础URL	ai-test.hikoon.com
path	路径	/api/users/register
params	请求参数（JSON）	{"email":"test@qq.com"}
headers	请求头（JSON）	{"Content-Type":"application/json"}
expected_code	期望状态码	200
expected_response	期望响应	{"code":0}
extract_vars	提取变量	user_id=data.user_id

---

Jenkins集成

Build with Parameters

在Jenkins中参数化执行，选择环境：

1. 点击 Build with Parameters
2. 选择 DEPLOY_ENV: test / uat / prod
3. 点击 Build

自动环境映射

environment {
    DEPLOY_ENV = "${params.DEPLOY_ENV ?: 'test'}"
    IP_HOST_TEST = 'ai-test.hikoon.com'
    IP_HOST_UAT = 'ai-uat.hikoon.com'
    IP_HOST_PROD = 'api.hikoon.com'
}

执行流程

Jenkins参数选择 → DEPLOY_ENV环境变量 → IP_HOST自动映射 → 用例执行 → 报告生成

详见 DEPLOYMENT_GUIDE.md

---

常见用例场景

场景1：通用接口测试（所有环境）

env_scope = 'all'
用例：登录、查询用户信息、获取列表等
结果：test✅ / uat✅ / prod✅

场景2：跳过生产的危险操作

env_scope = 'test,uat'
用例：删除数据、清理数据库、重置密码等
结果：test✅ / uat✅ / prod⏭️（跳过）

场景3：仅生产执行

env_scope = 'prod'
用例：导出报表、数据备份等（基于真实数据）
结果：test⏭️ / uat⏭️ / prod✅

---

常见问题

Q: 如何新增环境？

编辑 env_config.py 和 Jenkinsfile 的IP配置。详见 USER_GUIDE.md 的Q&A部分

Q: env_scope 支持哪些值？

支持：all / test / uat / prod 及其组合（用逗号分隔）。详见 USER_GUIDE.md

Q: 如何禁用某个用例？

设置 is_run = 1 或 env_scope 不包含当前环境。详见 USER_GUIDE.md

Q: 生产环境执行失败怎么办？

检查 env_scope 是否正确、IP_HOST是否可访问。详见 DEPLOYMENT_GUIDE.md

---

获取帮助

• 使用问题 → USER_GUIDE.md
• 部署问题 → DEPLOYMENT_GUIDE.md
• Docker问题 → DOCKER_GUIDE.md
• 验证方式 → OPERATOR_GUIDE.md
• 优化建议 → OPTIMIZATION_REQUIREMENTS.md

---

最近更新

v1.0.0 (2026-01-21)

完整框架实现

• 多环境执行支持（test/uat/prod）
• env_scope字段用于用例筛选
• 关系运算符验证（$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains, $regex, $range等）
• 报告文件名包含环境标识
• Docker容器化支持
• 参数化Jenkins配置
• 完整文档整合

---

许可证

项目所有者：百音引擎项目

---

祝你使用愉快！如有问题，请查看对应的文档或联系项目维护者。