Metadata-Version: 2.4
Name: Sisyphus-api-engine
Version: 2.1.0
Summary: 企业级 API 自动化测试引擎，使用 YAML 声明式语法，支持 HTTP/HTTPS、数据库操作、数据驱动测试、并发执行和 WebSocket 实时推送。
Author-email: koco-co <kopohub@gmail.com>
Maintainer-email: koco-co <kopohub@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/koco-co/Sisyphus-api-engine
Project-URL: Documentation, https://github.com/koco-co/Sisyphus-api-engine/blob/main/README.md
Project-URL: Repository, https://github.com/koco-co/Sisyphus-api-engine.git
Project-URL: Bug Tracker, https://github.com/koco-co/Sisyphus-api-engine/issues
Project-URL: Changelog, https://github.com/koco-co/Sisyphus-api-engine/blob/main/README.md#-更新日志
Keywords: api,testing,automation,yaml,json,mock,concurrent,allure,websocket,ddt,data-driven
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Testing :: Unit
Classifier: Topic :: Software Development :: Testing :: Acceptance
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Natural Language :: Chinese (Simplified)
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Jinja2>=3.1.0
Requires-Dist: jsonpath-ng>=1.6.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: pyyaml-include>=1.3
Requires-Dist: requests>=2.32.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: PyMySQL>=1.1.0
Requires-Dist: SQLAlchemy>=2.0.36
Requires-Dist: sqlmodel>=0.0.32
Requires-Dist: typing-extensions>=4.12.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: Flask>=3.1.0
Requires-Dist: websockets>=14.0
Requires-Dist: rich>=13.9.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: ruff>=0.9.0; extra == "dev"
Requires-Dist: pyright>=1.1.390; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=8.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=3.0.0; extra == "docs"
Requires-Dist: myst-parser>=4.0.0; extra == "docs"
Provides-Extra: all
Requires-Dist: Sisyphus-api-engine[dev,docs]; extra == "all"
Dynamic: license-file

# Sisyphus API Engine

![Sisyphus](https://img.shields.io/badge/Sisyphus-API%20Engine-blue)
![Python](https://img.shields.io/badge/python-3.12%2B-brightgreen)
![License](https://img.shields.io/badge/license-MIT-green)
![Version](https://img.shields.io/badge/version-2.1.0-orange)
![Status](https://img.shields.io/badge/status-stable-brightgreen)

**企业级 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.3+）** - 支持 ANSI 颜色和 Emoji 图标，中英文双语界面
- **🆕 增强型验证器（v2.0.0+）** - YAML 语法检查、未定义关键字检测、美观中文提示

### 🌟 v2.0.5 新功能亮点

- **🆕 项目级全局配置文件（v2.0.5+）** - 支持项目根目录的 `.sisyphus/config.yaml` 全局配置
  - 配置自动向上搜索，支持子目录中的测试用例
  - 三级配置优先级：测试用例 config > 全局 config > 默认值
  - 深度合并策略，支持部分覆盖
  - 完全向后兼容现有测试用例

- **🆕 版本化配置支持（v2.0.5+）** - 支持多版本 API 管理
  - 嵌套 profiles 结构（如 `v1.dev`, `v2.prod`）
  - 自动展平嵌套结构为可访问的路径
  - 模板中可使用 `${config.profiles.v2.dev.base_url}` 访问

使用示例：

```yaml
# .sisyphus/config.yaml (项目根目录)
profiles:
  v1:  # API v1 版本
    dev:
      base_url: "https://v1.api.dev.com"
      variables:
        api_version: "v1"
    prod:
      base_url: "https://v1.api.prod.com"
  v2:  # API v2 版本
    dev:
      base_url: "https://v2.api.dev.com"
      variables:
        api_version: "v2"

active_profile: "v2.dev"

variables:
  common_headers:
    User-Agent: "Sisyphus/2.0"
```

**优势**：
- ✅ 配置集中管理，所有环境配置在一个文件中
- ✅ 一键切换环境，无需修改用例
- ✅ 配置复用，多个用例共享同一配置
- ✅ 支持多版本 API 并行测试

### 🌟 v2.0.0 新功能亮点

- **🆕 变量嵌套引用增强** - 支持在顶层 variables 中嵌套引用 `config.profiles.*`
- **🆕 异步轮询机制** - 新增 `poll` 步骤类型，支持等待异步操作完成
- **🆕 多种轮询策略** - 支持 fixed/exponential/linear 退避策略
- **🆕 超时处理** - 支持 fail/continue 两种超时行为
- **🆕 提取器默认值（v2.0.1+）** - 提取器支持默认值，字段不存在时使用默认值
- **🆕 自定义错误消息（v2.0.1+）** - 验证失败时显示自定义错误消息，提升测试报告可读性
- **彩色命令行输出** - ANSI 颜色 + Emoji 图标 + 中英文双语
- **JSONPath 过滤表达式** - 支持 `$.users[?(@.role == 'admin')]` 语法
- **微秒时间戳** - `now_us()` 返回 20 位唯一时间戳
- **数组通配符** - `$.items[*].name` 获取所有元素的字段

---

## 🚀 安装指南

### 环境要求

- **Python 3.12 或更高版本**（推荐使用 Python 3.14）
- **uv** 包管理器（推荐）或 pip

### 安装步骤

#### 方法一：使用 uv（推荐）

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

# 创建虚拟环境（Python 3.14）
uv venv -p 3.14 .venv

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

# 安装项目（开发模式）
uv pip install -e .

# 或安装包含开发依赖
uv pip install -e ".[dev]"
```

#### 方法二：使用 pip

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

# 安装依赖
pip install -e .

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

### 验证安装

```bash
# 查看帮助
sisyphus --help

# 验证 YAML 文件语法（新增关键字检测、!include 支持、简写语法）
sisyphus-validate examples/24_最佳实践.yaml

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

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

# 静默模式（仅显示汇总）
sisyphus-validate examples/ -q

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

---

## 🎬 快速开始

### 1. 创建第一个测试用例

创建 `my_first_test.yaml`：

```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. 运行测试

```bash
# 基本运行（单个文件，中文彩色输出）
sisyphus --cases my_first_test.yaml

# 英文界面
sisyphus --lang en --cases my_first_test.yaml

# 禁用颜色（适合脚本）
sisyphus --no-color --cases my_first_test.yaml

# 禁用 Emoji
sisyphus --no-emoji --cases my_first_test.yaml

# 详细输出（显示每个步骤的详细信息）
sisyphus --cases my_first_test.yaml -v

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

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

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

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

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

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

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

# 生成 Allure 报告
sisyphus --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 --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%
============================================================
```

---

## 🎓 核心概念

### 测试用例结构

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

### ⭐⭐ 中级 (8-14)

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

### ⭐⭐⭐ 进阶级 (15-18)

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

### ⭐⭐⭐⭐ 高级 (19-22)

- **[19_完整流程测试.yaml](examples/19_完整流程测试.yaml)** - 完整业务流程测试
- **[20_Mock服务器测试.yaml](examples/20_Mock服务器测试.yaml)** - Mock服务测试
- **[21_WebSocket实时推送.yaml](examples/21_WebSocket实时推送.yaml)** - WebSocket实时推送
- **[22_性能测试.yaml](examples/22_性能测试.yaml)** - 性能测试与压测

### ⭐⭐⭐⭐⭐ 专家级 (23-26)

- **[23_数据库操作.yaml](examples/23_数据库操作.yaml)** - 数据库操作（MySQL/PostgreSQL/SQLite）
- **[24_最佳实践.yaml](examples/24_最佳实践.yaml)** - 综合最佳实践示例
- **[26_增强功能测试.yaml](examples/26_增强功能测试.yaml)** - 提取器默认值和自定义错误消息（v2.0.1+）

---

## 🌍 环境切换与配置管理

### 为什么需要配置管理?

当项目有大量测试用例时,如果每个用例都单独配置环境信息,会导致:
- ❌ 配置分散,难以维护
- ❌ 修改环境需要改动多个文件
- ❌ 容易出现配置不一致的问题

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

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

创建 `config/global_config.yaml`:

```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"
```

在测试用例中引入:

```yaml
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` 分层配置**

创建分层配置文件:

```yaml
# 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/config.yaml` 全局配置 (v2.0.5+)**

在项目根目录创建 `.sisyphus/config.yaml`:

```yaml
# .sisyphus/config.yaml
profiles:
  dev:
    base_url: "http://dev.example.com"
    variables:
      api_key: "dev-key-12345"
  prod:
    base_url: "https://api.example.com"
    variables:
      api_key: "prod-key-abcde"

active_profile: "dev"
```

测试用例中无需配置（自动使用全局配置）:

```yaml
name: "我的测试"
# 无需 config 部分，自动使用 .sisyphus/config.yaml

steps:
  - name: "测试请求"
    type: request
    url: "${config.profiles.dev.base_url}/api/users"
```

如需覆盖全局配置，在测试用例中添加 `config` 部分:

```yaml
name: "我的测试"
config:
  profiles:
    dev:
      base_url: "http://override.example.com"  # 覆盖全局配置
```

**配置优先级**（从高到低）:
1. 测试用例中的 `config`
2. `.sisyphus/config.yaml` 全局配置
3. 系统默认值

**一键切换环境:**

```bash
# 开发环境
sisyphus --cases test.yaml --profile dev

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

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

### 优势

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

### 示例参考

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

### 📁 目录结构

<details>
<summary>查看完整示例列表和运行方式</summary>

#### 运行 YAML 测试用例

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

# 运行所有 YAML 示例
for file in examples/*.yaml; do
    sisyphus --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` 掌握生产级实践

</details>

---

## ⚙️ 配置参考

### 环境配置

```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"  # 当前激活环境
```

### 重试策略

```yaml
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              # 是否添加随机抖动
```

### 数据驱动测试

```yaml
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"]` |

更多验证器请参考[输入协议规范](docs/API-Engine输入协议规范.md)。

### 🆕 提取器默认值（v2.0.1+）

提取器现在支持 `default` 参数，当提取的字段不存在时，使用指定的默认值：

```yaml
extractors:
  # 字段存在时提取实际值
  - type: jsonpath
    name: user_id
    path: "$.user.id"
    default: "anonymous"  # 字段不存在时使用默认值

  # 正则表达式匹配失败时使用默认值
  - type: regex
    name: order_id
    path: "$.response"
    pattern: "Order ID: (\\d+)"
    default: "N/A"

  # Header 不存在时使用默认值
  - type: header
    name: auth_token
    path: "Authorization"
    default: "Bearer default_token"
```

**适用场景**：
- 可选字段提取（如用户昵称、头像等）
- 向后兼容测试（新版本新增字段）
- 降级处理（字段不存在时使用默认逻辑）

### 🆕 自定义错误消息（v2.0.1+）

验证器现在支持 `error_message` 参数，验证失败时显示自定义错误消息：

```yaml
validations:
  # 简单验证 - 自定义错误消息
  - type: eq
    path: "$.status"
    expect: "success"
    error_message: "❌ 状态错误: 响应状态必须为'success'，请检查后端服务"
    description: "验证状态为success"

  # 数值验证 - 带详细说明
  - type: between
    path: "$.age"
    expect: [18, 65]
    error_message: "⚠️ 年龄限制: 用户年龄必须在18-65岁之间，当前值不符合要求"
    description: "验证年龄范围"

  # 逻辑运算符 - 统一错误消息
  - type: and
    error_message: "❌ 业务验证失败: 状态必须为success且码为1"
    sub_validations:
      - type: eq
        path: "$.status"
        expect: "success"
      - type: eq
        path: "$.code"
        expect: 1
```

**优势**：
- ✅ 更清晰的错误提示，快速定位问题
- ✅ 支持多语言错误消息（中文/英文）
- ✅ 提升测试报告的可读性
- ✅ 便于向开发团队反馈具体问题

### 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()`

**函数链式调用示例**：

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

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

详细文档请参考：
- **[输入协议规范 - JSONPath 函数](docs/API-Engine输入协议规范.md#53-jsonpath-增强)**
- **[11_JSONPath函数演示.yaml](examples/11_JSONPath函数演示.yaml)**

---

## 📖 文档

### 核心文档

- **[输入协议规范](docs/API-Engine输入协议规范.md)** - 完整的 YAML 语法和配置说明
- **[输出协议规范](docs/API-Engine输出协议规范.md)** - 测试结果输出格式

---

## 🔧 开发指南

### 项目结构

```
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
```

### 扩展指南

<details>
<summary>添加自定义验证器</summary>

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

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

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

</details>

<details>
<summary>添加新的步骤类型</summary>

1. 创建执行器类：

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

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

2. 在 `TestCaseExecutor` 中注册：

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

</details>

---

## 🤝 贡献指南

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

### 贡献流程

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

### 代码规范

项目使用现代化 Python 开发工具链：

#### 🛠️ 开发工具

- **uv** - 极速包管理器（替代 pip）
- **Ruff** - 代码检查和格式化（替代 black/isort/flake8）
- **Pyright** - 静态类型检查（替代 mypy）
- **pre-commit** - Git 钩子自动化
- **rich** - 终端美化输出

> **工具安装方式**：
> - **项目级**：通过 `uv pip install -e ".[dev]"` 安装（推荐用于贡献者）
> - **全局级**：通过 `uv tool install` 安装（推荐用于多项目开发者）
> 两种方式都可以，选择适合你的方式即可。

#### 📝 开发工作流

```bash
# 1. 激活虚拟环境
source .venv/bin/activate

# 2. 安装项目依赖（包含开发工具）
uv pip install -e ".[dev]"

# 3. 安装 pre-commit 钩子
pre-commit install

# 4. 代码格式化
ruff format .

# 5. 代码检查并自动修复
ruff check . --fix

# 6. 类型检查
pyright .

# 7. 运行测试
pytest

# 8. 提交代码（pre-commit 自动运行检查）
git add .
git commit -m "feat: add new feature"
```

#### 🔍 代码质量要求

- 遵循 [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
- 使用类型注解（Pyright strict mode）
- 单元测试覆盖率 ≥ 80%
- 所有注释使用中文
- 通过 pre-commit 钩子检查

#### 📋 Ruff 配置

```toml
[tool.ruff]
target-version = "py312"
line-length = 88

[tool.ruff.lint]
select = ["E", "W", "F", "I", "UP", "C4", "TID", "ARG", "PTH"]
```

#### 🔬 类型检查

项目使用 Pyright strict mode：

```json
{
  "typeCheckingMode": "strict",
  "pythonVersion": "3.12"
}
```

---

## ❓ 常见问题

<details>
<summary>如何切换测试环境？</summary>

使用 `--profile` 参数：

```bash
sisyphus --cases test.yaml --profile staging
```

或在 YAML 中设置：

```yaml
config:
  active_profile: "staging"
```

</details>

<details>
<summary>如何调试失败的测试？</summary>

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

```bash
sisyphus --cases test.yaml -v
```

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

</details>

<details>
<summary>如何处理动态数据？</summary>

使用 Jinja2 模板语法：

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

</details>

<details>
<summary>数据驱动测试需要外部文件吗？</summary>

不需要，可以内联数据：

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

</details>

---

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

---

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

---

## 👥 作者

**koco-co**

- GitHub: [https://github.com/koco-co](https://github.com/koco-co)
- 邮箱: kopohub@gmail.com

---

## 🙏 致谢

- [Requests](https://requests.readthedocs.io/) - HTTP 库
- [Jinja2](https://jinja.palletsprojects.com/) - 模板引擎
- [JSONPath](https://github.com/h2non/jsonpath-ng) - JSON 路径表达式
- [PyYAML](https://pyyaml.org/) - YAML 解析器

---

## 📮 联系我们

- **问题反馈**: [GitHub Issues](https://github.com/koco-co/Sisyphus-api-engine/issues)
- **功能建议**: [GitHub Discussions](https://github.com/koco-co/Sisyphus-api-engine/discussions)
- **邮件**: kopohub@gmail.com

---

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

Made with ❤️ by koco-co
