sisyphus-api-engine 1.0.3

Enterprise-grade API automation testing engine with YAML-based declarative syntax, supporting complex testing scenarios including HTTP/HTTPS, database operations, data-driven testing, concurrent execution, and real-time WebSocket reporting.

Sisyphus API Engine

企业级 API 自动化测试引擎

基于 YAML 的声明式测试框架，支持复杂的 API 测试场景

功能特性 • 快速开始 • 文档 • 示例

---

📖 目录

• 功能特性
• 安装指南
• 快速开始
• 核心概念
• 示例说明
• 配置参考
• 文档
• 开发指南
• 许可证

---

✨ 功能特性

🎯 核心能力

• YAML 声明式测试 - 使用简洁的 YAML 语法定义测试用例
• 多环境管理 - 支持多环境配置（dev/test/prod），一键切换
• 变量系统 - 强大的变量管理（全局变量、环境变量、动态提取）
• 模板渲染 - 基于 Jinja2 的模板引擎，支持变量引用和计算
• 🆓 变量嵌套引用（v1.0.2+） - 支持变量间的相互引用，实现配置复用
• 🆓 微秒时间戳（v1.0.2+） - 支持微秒级精度时间戳，确保测试数据唯一性

🔌 HTTP 测试

• 全方法支持 - GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS
• 请求定制 - 自定义 headers、params、body、cookies
• 响应验证 - 状态码、响应体、响应头验证
• 变量提取 - JSONPath（支持过滤表达式、通配符、数组索引等）、正则表达式、Header、Cookie 提取

🗄️ 数据库集成

• 多数据库支持 - MySQL、PostgreSQL、SQLite
• 多种操作 - 查询、执行、批量操作、脚本执行
• 参数化查询 - 防止 SQL 注入的预编译语句

🔧 高级特性

• 重试机制 - 支持固定、指数退避、线性等重试策略
• 步骤控制 - 条件执行（skip_if/only_if）、依赖管理（depends_on）
• 流程控制 - 等待（固定延迟和条件等待）、For 循环、While 循环
• 数据驱动 - 支持 CSV、JSON、数据库作为数据源
• 钩子函数 - 全局和步骤级别的 setup/teardown
• 并发测试 - 支持多线程并发执行和性能测试
• 脚本执行 - 支持 Python 脚本执行（安全沙箱）
• Mock 服务 - 内置 Mock 服务器，支持接口模拟

📊 结果输出

• 多种格式 - JSON、CSV、HTML（支持中英文）、JUnit XML、Allure 报告
• 性能指标 - DNS、TCP、TLS、服务器处理时间等详细性能数据
• 错误分类 - 智能错误分类和诊断信息
• 实时推送 - WebSocket 实时推送测试进度和结果
• 变量追踪 - 调试模式下追踪变量变化

🌟 v1.0.2+ 新功能亮点

• JSONPath 过滤表达式 - 支持 $.users[?(@.role == 'admin')] 语法
• 变量嵌套引用 - ${base_url}${api_path} 自动解析
• 微秒时间戳 - now_us() 返回 20 位唯一时间戳
• 数组通配符 - $.items[*].name 获取所有元素的字段
• Contains 验证增强 - 改进对数组和 None 值的处理

---

🚀 安装指南

环境要求

• Python 3.8 或更高版本
• pip 包管理器

安装步骤

# 克隆仓库
git clone https://github.com/koco-co/Sisyphus-api-engine.git
cd Sisyphus-api-engine

# 安装依赖
pip install -e .

# 或使用 pip 直接安装
pip install Sisyphus-api-engine

验证安装

# 查看帮助
sisyphus-api-engine --help

# 验证 YAML 文件语法
sisyphus-api-validate examples/24_最佳实践.yaml

# 验证多个文件
sisyphus-api-validate test1.yaml test2.yaml test3.yaml

# 验证目录中的所有文件
sisyphus-api-validate tests/

# 运行示例测试
sisyphus-api-engine --cases examples/24_最佳实践.yaml

---

🎬 快速开始

1. 创建第一个测试用例

创建 my_first_test.yaml：

name: "我的第一个测试"
description: "测试 HTTPBIN API"

config:
  profiles:
    prod:
      base_url: "https://httpbin.org"

steps:
  - 测试GET请求:
      type: request
      url: "${config.profiles.prod.base_url}/get"
      method: GET
      validations:
        - type: eq
          path: "$.url"
          expect: "https://httpbin.org/get"
          description: "验证URL正确"

2. 运行测试

# 基本运行（单个文件）
sisyphus-api-engine --cases my_first_test.yaml

# 详细输出
sisyphus-api-engine --cases my_first_test.yaml -v

# 运行多个测试文件
sisyphus-api-engine --cases test1.yaml test2.yaml test3.yaml

# 运行目录中的所有测试
sisyphus-api-engine --cases tests/

# 混合文件和目录
sisyphus-api-engine --cases smoke_test.yaml tests/ integration/

# 保存结果到 JSON
sisyphus-api-engine --cases my_first_test.yaml -o result.json

# 导出为 CSV
sisyphus-api-engine --cases my_first_test.yaml --format csv -o result.csv

# 导出为 HTML（中文报告）
sisyphus-api-engine --cases my_first_test.yaml --format html --report-lang zh -o report.html

# 导出为 HTML（英文报告）
sisyphus-api-engine --cases my_first_test.yaml --format html --report-lang en -o report.html

# 生成 Allure 报告
sisyphus-api-engine --cases my_first_test.yaml --allure

# 查看 Allure 报告（会自动打开浏览器）
allure serve allure-results

# 或者生成静态 HTML 报告
allure generate allure-results --clean -o allure-report
allure open allure-report

# 启用 WebSocket 实时推送
sisyphus-api-engine --cases my_first_test.yaml --ws-server

3. 查看结果

测试执行后，你将看到：

Executing: 我的第一个测试
Description: 测试 HTTPBIN API
Steps: 1

============================================================
Status: PASSED
Duration: 0.85s
Statistics:
  Total:   1
  Passed:  1 ✓
  Failed:  0 ✗
  Skipped: 0 ⊘
Pass Rate: 100.0%
============================================================

---

🎓 核心概念

测试用例结构

name: "测试用例名称"          # 必填：用例名称
description: "测试描述"       # 可选：用例描述

config:                       # 可选：全局配置
  profiles: {}               # 环境配置
  variables: {}              # 全局变量
  timeout: 30                # 超时时间

steps: []                     # 必填：测试步骤列表

步骤类型

类型	说明	适用场景
request	HTTP 请求	API 测试
database	数据库操作	数据验证
wait	等待/延迟	异步场景
loop	循环控制	批量操作
concurrent	并发执行	性能测试
script	脚本执行	自定义逻辑

变量作用域

全局变量 (config.variables)
    ↓
环境变量 (config.profiles.{profile}.variables)
    ↓
提取变量 (extractors)  ← 优先级最高

---

📚 示例说明

项目提供了从入门到精通的完整示例，位于 examples/ 目录：

⭐ 入门级 (1-7)

• 01_HTTP请求方法.yaml - 各种 HTTP 方法（GET/POST/PUT/PATCH/DELETE等）
• 02_请求参数配置.yaml - 请求参数、headers、body配置
• 03_变量基础语法.yaml - 变量定义和使用基础
• 04_内置模板函数.yaml - 内置函数（random_string/uuid/now/base64等）
• 05_基础断言验证.yaml - 常用验证断言（状态码、相等、包含等）
• 06_环境配置切换.yaml - 多环境配置（方式一：在用例内定义）
• 07_使用全局配置.yaml - 全局配置复用（方式二：!include引入）

⭐⭐ 中级 (8-14)

• 08_输出格式配置.yaml - 多种输出格式（JSON/CSV/HTML/JUnit）
• 09_变量提取器.yaml - 从响应中提取变量（JSONPath/正则/Header等）
• 10_高级断言验证.yaml - 复杂验证逻辑（逻辑运算符/嵌套验证）
• 11_JSONPath函数演示.yaml - JSONPath增强函数（length/sum/sort/unique等20+函数）
• 12_步骤控制.yaml - 条件执行、跳过、依赖关系
• 13_重试机制.yaml - 失败重试策略（固定/指数退避）
• 14_等待机制.yaml - 等待条件满足（固定延迟/条件等待）

⭐⭐⭐ 进阶级 (15-18)

• 15_循环控制.yaml - 循环执行（for/while循环）
• 16_并发执行.yaml - 并发测试（并发请求）
• 17_数据驱动测试.yaml - 数据驱动（CSV/JSON/数据库）
• 18_脚本执行.yaml - 自定义脚本（Python/JavaScript）

⭐⭐⭐⭐ 高级 (19-22)

• 19_完整流程测试.yaml - 完整业务流程测试
• 20_Mock服务器测试.yaml - Mock服务测试
• 21_WebSocket实时推送.yaml - WebSocket实时推送
• 22_性能测试.yaml - 性能测试与压测

⭐⭐⭐⭐⭐ 专家级 (23-24)

• 23_数据库操作.yaml - 数据库操作（MySQL/PostgreSQL/SQLite）
• 24_最佳实践.yaml - 综合最佳实践示例

---

🌍 环境切换与配置管理

为什么需要配置管理?

当项目有大量测试用例时,如果每个用例都单独配置环境信息,会导致:

• ❌ 配置分散,难以维护
• ❌ 修改环境需要改动多个文件
• ❌ 容易出现配置不一致的问题

解决方案:全局配置 + 环境切换

方案一:使用全局配置文件

创建 config/global_config.yaml:

# 全局配置文件
profiles:
  dev:
    base_url: "http://dev-api.example.com"
    variables:
      api_key: "dev-key-12345"
  staging:
    base_url: "http://staging-api.example.com"
    variables:
      api_key: "staging-key-67890"
  prod:
    base_url: "https://api.example.com"
    variables:
      api_key: "prod-key-abcde"

active_profile: "dev"

在测试用例中引入:

name: "我的测试"
config: !include ../config/global_config.yaml

steps:
  - 测试请求:
      type: request
      url: "${config.profiles.${active_profile}.base_url}/api/users"
      headers:
        X-API-Key: "${config.profiles.${active_profile}.variables.api_key}"

方案二:使用 !include 分层配置

创建分层配置文件:

# config/environments.yaml (仅环境配置)
profiles:
  dev: {base_url: "http://dev.example.com"}
  prod: {base_url: "https://api.example.com"}
active_profile: "dev"

# 测试用例文件
config: !include config/environments.yaml

一键切换环境:

# 开发环境
sisyphus-api-engine --cases test.yaml --profile dev

# 预发布环境
sisyphus-api-engine --cases test.yaml --profile staging

# 生产环境
sisyphus-api-engine --cases test.yaml --profile prod

优势

✅ 配置集中管理 - 所有环境配置在一个文件中 ✅ 一键切换环境 - 通过 --profile 参数,无需修改用例 ✅ 配置复用 - 多个用例共享同一配置,修改一处全部生效 ✅ 分层配置 - 支持全局配置 + 用例特定配置 ✅ 敏感信息保护 - 配合环境变量使用,避免硬编码敏感信息

示例参考

• 06_环境配置切换.yaml - 方式一：在测试用例内定义环境配置
• 07_使用全局配置.yaml - 方式二：使用 !include 引入全局配置

📁 目录结构

查看完整示例列表和运行方式

运行 YAML 测试用例

# 验证所有 YAML 示例
for file in examples/*.yaml; do
    sisyphus-api-validate "$file"
done

# 运行所有 YAML 示例
for file in examples/*.yaml; do
    sisyphus-api-engine --cases "$file"
done

学习路径

1. 从 01_HTTP请求方法.yaml 开始理解基本结构
2. 学习 02_请求参数配置.yaml 掌握请求定制
3. 通过 03_变量基础语法.yaml 学习变量系统
4. 实践 04_内置模板函数.yaml 掌握模板函数
5. 进阶 05_基础断言验证.yaml 理解验证机制
6. 掌握 06_环境配置切换.yaml 理解多环境管理
7. 精通 07_使用全局配置.yaml 掌握配置复用
8. 学习 08_输出格式配置.yaml 掌握结果导出
9. 实践 09_变量提取器.yaml 学习数据提取
10. 进阶 10_高级断言验证.yaml 掌握复杂验证
11. 学习 11_JSONPath函数演示.yaml 掌握 JSONPath 增强函数
12. 实践 12_步骤控制.yaml 理解流程控制
13. 学习 13_重试机制.yaml 掌握重试策略
14. 实践 14_等待机制.yaml 掌握异步处理
15. 学习 15_循环控制.yaml 掌握循环逻辑
16. 实践 16_并发执行.yaml 理解并发测试
17. 学习 17_数据驱动测试.yaml 掌握数据驱动
18. 实践 18_脚本执行.yaml 理解脚本扩展
19. 通过 19_完整流程测试.yaml 综合运用所学
20. 学习 20_Mock服务器测试.yaml 理解 Mock 服务
21. 实践 21_WebSocket实时推送.yaml 掌握实时推送
22. 学习 22_性能测试.yaml 理解性能测试
23. 实践 23_数据库操作.yaml 掌握数据库集成
24. 最后学习 24_最佳实践.yaml 掌握生产级实践

---

⚙️ 配置参考

环境配置

config:
  profiles:
    dev:
      base_url: "http://dev-api.example.com"
      variables:
        api_key: "dev_key"
    prod:
      base_url: "https://api.example.com"
      variables:
        api_key: "prod_key"

  active_profile: "dev"  # 当前激活环境

重试策略

steps:
  - name: "带重试的请求"
    retry_policy:
      max_attempts: 3           # 最大重试次数
      strategy: exponential      # 策略: fixed/exponential/linear
      base_delay: 1.0           # 基础延迟（秒）
      max_delay: 10.0           # 最大延迟（秒）
      backoff_multiplier: 2.0   # 退避倍数
      jitter: true              # 是否添加随机抖动

数据驱动测试

config:
  data_source:
    type: csv
    file_path: "数据驱动测试.csv"
    delimiter: ","
    has_header: true
  data_iterations: true
  variable_prefix: "user_"

验证器类型

类型	说明	示例
eq	等于	- eq: ["$.status", 200]
ne	不等于	- ne: ["$.error", null]
contains	包含	- contains: ["$.message", "success"]
regex	正则匹配	- regex: ["$.email", "^[\\w\\.]+@"]
type	类型检查	- type: ["$.count", "number"]

更多验证器请参考输入协议规范。

JSONPath 增强函数

Sisyphus API Engine 支持 20+ 种 JSONPath 增强函数，包括：

• 数组操作: length(), first(), last(), reverse(), sort(), unique(), flatten()
• 数值计算: sum(), avg(), min(), max()
• 字符串处理: upper(), lower(), trim(), split(), join()
• 检查函数: contains(), starts_with(), ends_with(), matches(), is_empty(), is_null()
• 对象操作: keys(), values()

函数链式调用示例：

validations:
  # 链式调用：去重后计数
  - type: eq
    path: "$.data.unique().length()"
    expect: 5

  # 排序后取最小值
  - type: eq
    path: "$.numbers.sort().first()"
    expect: 1

详细文档请参考：

• 输入协议规范 - JSONPath 函数
• 11_JSONPath函数演示.yaml

---

📖 文档

核心文档

• 输入协议规范 - 完整的 YAML 语法和配置说明
• 输出协议规范 - 测试结果输出格式

---

🔧 开发指南

项目结构

Sisyphus-api-engine/
├── apirun/
│   ├── core/           # 核心数据模型
│   ├── parser/         # YAML 解析器
│   ├── executor/       # 测试执行器
│   ├── validation/     # 断言验证引擎
│   ├── extractor/      # 变量提取器
│   ├── data_driven/    # 数据驱动测试
│   ├── result/         # 结果收集器
│   ├── mock/           # Mock 服务器
│   ├── websocket/      # WebSocket 实时推送
│   └── utils/          # 工具函数
├── examples/           # 示例用例
├── docs/               # 项目文档
└── tests/              # 测试文件

核心架构

输入 YAML
    ↓
V2YamlParser → TestCase
    ↓
TestCaseExecutor
    ↓
VariableManager (变量管理)
    ↓
StepExecutor (API/Database/Wait/Loop)
    ↓
ValidationEngine (验证)
    ↓
ResultCollector (结果收集)
    ↓
输出 JSON

扩展指南

添加自定义验证器

在 apirun/validation/comparators.py 中添加：

def custom_comparator(actual: Any, expected: Any) -> bool:
    """自定义比较器"""
    # 实现比较逻辑
    return actual == expected

# 注册比较器
COMPARATORS = {
    # ... 其他比较器
    "custom": custom_comparator,
}

添加新的步骤类型

1. 创建执行器类：

# apirun/executor/my_executor.py
from apirun.executor.step_executor import StepExecutor

class MyExecutor(StepExecutor):
    def _execute_step(self, rendered_step):
        # 实现执行逻辑
        pass

2. 在 TestCaseExecutor 中注册：

if step.type == "my_type":
    executor = MyExecutor(...)

---

🤝 贡献指南

欢迎贡献代码、报告问题或提出建议！

贡献流程

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 提交 Pull Request

代码规范

• 遵循 Google Python Style Guide
• 添加类型注解
• 编写单元测试
• 更新相关文档

---

❓ 常见问题

如何切换测试环境？

使用 --profile 参数：

sisyphus-api-engine --cases test.yaml --profile staging

或在 YAML 中设置：

config:
  active_profile: "staging"

如何调试失败的测试？

使用 -v 参数查看详细输出：

sisyphus-api-engine --cases test.yaml -v

这将显示每个步骤的详细信息，包括请求、响应、验证结果等。

如何处理动态数据？

使用 Jinja2 模板语法：

steps:
  - name: "创建用户"
    body:
      username: "user_${now().strftime('%Y%m%d%H%M%S')}"
      email: "${random_string(10)}@example.com"

数据驱动测试需要外部文件吗？

不需要，可以内联数据：

config:
  data_source:
    - {username: "user1", age: 25}
    - {username: "user2", age: 30}
  data_iterations: true

---

📝 更新日志

v1.0.3 (2026-01-31) - Bug 修复版本

🔧 重要修复

• ✅ JSONPath 复杂表达式支持 - 升级到 jsonpath-ng 库

  • 支持过滤表达式：$.array[?(@.field == 'value')]
  • 支持数组索引：$.array[1]、通配符：$.array[*].field
  • 支持数值比较和布尔值过滤
  • 修复数组索引不稳定的问题

• ✅ 变量嵌套引用渲染 - 递归渲染支持

  • 支持多级嵌套变量引用（如 ${base}.${env}.com）
  • 添加循环引用保护机制（最多 10 次迭代）
  • 修复嵌套变量无法正确展开的问题

• ✅ Contains 验证器稳定性改进

  • 正确处理 None 值和所有数据类型
  • 修复对数组验证时偶尔报告不存在的问题
  • 改进列表、字符串、字典的包含检查

• ✅ 微秒级时间戳支持

  • 新增 timestamp_us() 函数（微秒级 Unix 时间戳）
  • 新增 now_us() 函数（格式化微秒时间字符串）
  • 修复快速运行时时间戳重复的问题

📝 测试覆盖

• 新增 22 个专项测试用例（tests/test_bugfixes.py）
• 所有测试通过（510+ 测试用例）

📚 文档更新

• 新增 CHANGELOG.md 完整变更记录

---

v1.0.0 (2026-01-29)

核心功能

• ✨ YAML 声明式测试语法
• ✨ 多环境配置管理（dev/test/prod）
• ✨ 强大的变量系统（Jinja2 模板）
• ✨ 17 种内置模板函数
• ✨ 多层级变量作用域

HTTP 测试

• ✨ HTTP/HTTPS 全方法支持（GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS）
• ✨ 完整的请求定制（headers/params/body/cookies）
• ✨ 17 种验证器（eq/ne/gt/lt/contains/regex/type/len_eq 等）
• ✨ 4 种变量提取器（JSONPath/正则/Header/Cookie）
• ✨ JSONPath 增强：支持 20+ 函数（length/sum/sort/unique 等）和链式调用
• ✨ 增强的重试机制（固定/指数退避/线性策略）

数据库集成

• ✨ MySQL/PostgreSQL/SQLite 支持
• ✨ 查询和执行操作
• ✨ 参数化查询防 SQL 注入

高级特性

• ✨ 步骤控制（skip_if/only_if/depends_on）
• ✨ 流程控制（Wait/For 循环/While 循环）
• ✨ 数据驱动测试（CSV/JSON/数据库）
• ✨ 并发测试（多线程并发执行）
• ✨ 脚本执行（Python 安全沙箱）
• ✨ Mock 服务器（接口模拟）
• ✨ WebSocket 实时推送
• ✨ 钩子函数（setup/teardown）

结果输出

• ✨ 多种格式（JSON/CSV/HTML/JUnit XML/Allure）
• ✨ HTML 报告支持中英文双语（通过 --report-lang 参数）
• ✨ 详细性能指标（DNS/TCP/TLS/服务器处理时间）
• ✨ 智能错误分类和诊断
• ✨ 变量追踪（调试模式）

质量保证

• ✨ 510+ 单元测试，100% 通过
• ✨ 完整的集成测试覆盖
• ✨ 24 个示例测试用例
• ✨ 详细的文档和最佳实践

代码规范

• ✨ Google Python Style Guide
• ✨ 完整的类型注解和文档字符串
• ✨ Black、isort、flake8、mypy、pylint 配置

💡 查看完整更新日志：详见 CHANGELOG.md 了解所有版本详细变更记录

---

📄 许可证

本项目采用 MIT License 开源协议。

---

👥 作者

koco-co

• GitHub: https://github.com/koco-co
• 邮箱: [e-mail]

---

🙏 致谢

• Requests - HTTP 库
• Jinja2 - 模板引擎
• JSONPath - JSON 路径表达式
• PyYAML - YAML 解析器

---

📮 联系我们

• 问题反馈: GitHub Issues
• 功能建议: GitHub Discussions
• 邮件: [e-mail]

---

如果这个项目对你有帮助，请给个 ⭐️ Star！

Made with ❤️ by koco-co