README.md



 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中参数化执行，选择环境：


点击 Build with Parameters

选择 DEPLOY_ENV: test / uat / prod
点击 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配置

 完整文档整合


 许可证

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


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