Sisyphus-api-engine

YAML 驱动的接口自动化测试引擎，为 Sisyphus-X 平台提供 核心执行器 能力。
当前仓库是面向 Python 3.12+ 的「轻量核心版」，聚焦：

• YAML 用例 → Pydantic 数据模型
• 场景运行器（Runner）
• HTTP 请求执行
• JSON 结果输出（对齐内部输出规范）

完整功能版（含 Mock、WebSocket、多格式报告等）请参考已发布的 PyPI 包
Sisyphus-api-engine。

---

目录

• Sisyphus-api-engine
  • 目录
  • 简介
  • 特性概览
  • 技术栈与约束
  • 安装
    • 使用 uv（推荐）
    • 使用 pip
  • 快速开始
    • 编写最小 YAML 用例
    • 通过 CLI 执行
  • 配置管理（.sisyphus）
  • 项目结构
  • 运行与调试
    • 单元测试
    • 代码质量与类型检查
  • 版本与发布策略
    • 发布流程（PyPI）
  • 开发规范
  • 关联文档
  • 许可证

---

简介

Sisyphus-api-engine 是 Sisyphus-X 自动化测试管理平台的 核心执行器：

• 解析 YAML 格式的接口测试用例
• 按步骤执行 HTTP 请求
• 组合变量系统与模板渲染
• 输出标准化 JSON 结果给平台消费

本仓库对应的是「核心执行器重构线」，优先保证核心链路稳定：

YAML → Pydantic 模型 → 场景运行器 → HTTP 请求 → JSON 输出

高级特性（数据库、数据驱动、断言引擎、WebSocket 推送等）会按照内部开发任务清单逐步补齐。

---

特性概览

• YAML 驱动：用例以 YAML 描述，结构清晰、易读易维护
• 强类型模型：基于 Pydantic v2 构建核心数据模型，保证输入合法性
• 变量系统：
  • 内置函数（随机串、时间戳等），见 apirun/utils/functions.py
  • 递归模板渲染，见 apirun/utils/variables.py
• HTTP 请求执行：
  • 基于 requests，支持常见 HTTP 方法
  • 支持 base_url + 相对路径拼接
  • 支持 URL / headers / params / body 的变量渲染
  • 支持 files 字段引用 MinIO 路径，自动下载为临时文件后上传
• JSON 输出：
  • 执行结果统一输出为 JSON
  • 输出结构与内部《JSON 输出规范》文档对齐（逐步完善中）

---

技术栈与约束

• 语言：Python 3.12+
• 包管理器：uv
• 代码风格：Google Python Style，注释统一使用中文
• 静态检查：Ruff + Pyright
• 测试框架：pytest
• 构建系统：hatchling（由 pyproject.toml 管理）

详细技术约束与架构说明参见：

• docs/Sisyphus-api-engine需求文档.md
• docs/开发任务清单.md

---

安装

使用 uv（推荐）

# 1. 创建虚拟环境（Python 3.12+）
uv venv -p 3.12 .venv
source .venv/bin/activate  # macOS / Linux

# 2. 安装依赖
uv sync

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

使用 pip

python -m venv .venv
source .venv/bin/activate  # macOS / Linux

pip install -e ".[dev]"

pyproject.toml 中 requires-python = ">=3.12"，低于 3.12 的 Python 版本不支持。

---

快速开始

当前核心能力为 HTTP 请求 + JSON 输出，高级特性按任务清单逐步实现。

编写最小 YAML 用例

示例：tests/yaml/simple_get.yaml（可自行创建）：

config:
  name: "简单 GET 示例"
  base_url: "https://httpbin.org"
  variables:
    api_key: "demo-key"

teststeps:
  - name: "GET /get"
    keyword_type: "request"
    request:
      method: "GET"
      url: "/get"

通过 CLI 执行

本地开发（推荐使用 Python 模块方式）：

# 激活虚拟环境后执行
source .venv/bin/activate

# 执行单个用例
python -m apirun.cli --case tests/yaml/simple_get.yaml -O json

# 批量执行用例
python -m apirun.cli --cases tests/yaml/ -O json

PyPI 安装后使用命令方式：

# 安装
uv pip install sisyphus-api-engine

# 直接使用命令
sisyphus-api-engine --case tests/yaml/simple_get.yaml -O json
sisyphus-api-engine --cases tests/yaml/ -O json

注意：本地开发时推荐使用 python -m apirun.cli 方式，这是 Python 官方推荐的做法（PEP 338）。PyPI 安装后可直接使用 sisyphus-api-engine 命令。

---

配置管理（.sisyphus）

项目根目录下的 .sisyphus/config.yaml 用于统一环境配置：

profiles:
  dev:
    base_url: "http://dev.example.com"
    variables:
      api_key: "dev-key-please-change"

  prod:
    base_url: "https://api.example.com"
    variables:
      api_key: "prod-key-please-change"

active_profile: "dev"

variables:
  common_headers:
    User-Agent: "sisyphus-api-engine/0.2.0"

• 支持双来源公共配置：
  • 全局来源：.sisyphus/config.yaml 的 active_profile（base_url + variables）
  • 用例来源：config.base_url / config.variables / config.environment.*
• 同名冲突时用例 YAML 优先（例如 config.base_url 优先于全局 base_url）
• 向后兼容旧写法：config.environment.base_url 仍然可用

平台对接（Sisyphus-X 自动生成 YAML）推荐直接输出：

config:
  name: "平台生成场景"
  base_url: "https://api.test.example.com"
  variables:
    tenant_id: "t-001"

对应请求 URL 的前缀优先级为： config.base_url > config.environment.base_url > .sisyphus/config.yaml。

---

项目结构

Sisyphus-api-engine/
├── .sisyphus/              # 统一环境配置
│   └── config.yaml
├── apirun/                 # 主 Python 包
│   ├── __init__.py         # 导出 __version__ / 公共 API（预留）
│   ├── cli.py              # CLI 入口 (sisyphus)
│   ├── core/
│   │   ├── models.py       # CaseModel / Config / StepDefinition 等
│   │   └── runner.py       # 场景运行器
│   ├── executor/
│   │   └── request.py      # HTTP 请求执行器
│   ├── utils/
│   │   ├── functions.py    # 内置函数
│   │   └── variables.py    # 变量渲染引擎
│   ├── parser/             # YAML 解析（预留）
│   ├── validation/         # 断言引擎（预留）
│   ├── extractor/          # 变量提取器（预留）
│   ├── data_driven/        # 数据驱动（预留）
│   ├── result/             # 结果模型与导出（预留）
│   └── websocket/          # WebSocket 推送（预留）
├── docs/                   # 需求 & 规范 & 任务清单
├── tests/
│   ├── unit/               # Python 单元测试（pytest）
│   └── yaml/               # YAML 集成用例（通过 CLI 执行）
├── CHANGELOG.md
├── LICENSE
├── MANIFEST.in
├── pyproject.toml
├── pypi_publish.sh         # PyPI 发布脚本
└── uv.lock

---

运行与调试

单元测试

# 运行所有单元测试
uv run python -m pytest tests/unit -v

代码质量与类型检查

# 代码格式化（Ruff）
uv run ruff format .

# 静态检查（Ruff）
uv run ruff check .

# 类型检查（Pyright）
uv run pyright

推荐安装 pre-commit 钩子（已在 .pre-commit-config.yaml 中配置）：

pre-commit install

---

版本与发布策略

当前仓库版本号仅针对「核心执行器重构线」，与历史完整引擎版本解耦。

• 内部版本（本仓库）
  • 当前版本：2.2.2
  • 历史内部版本：0.1.0 / 0.2.0（未作为独立 PyPI 版本发布）
  • 版本变更记录：见 CHANGELOG.md
• PyPI 已发布版本（完整引擎）
  • 包名：Sisyphus-api-engine
  • 最新稳定版：2.2.2
  • 页面：https://pypi.org/project/Sisyphus-api-engine/

发布流程（PyPI）

推荐使用项目自带的 pypi_publish.sh 脚本发布新版本：

# 1. 确认版本号已更新为目标版本（例如 2.2.2）
#    - pyproject.toml [project].version
#    - apirun/__init__.py 中 __version__

# 2. 更新 CHANGELOG.md / README.md / docs/开发任务清单.md

# 3. 安装发布工具（可选，脚本会自动检测并安装）
uv pip install -e ".[publish]"

# 4. 设置 PyPI 凭据（正式仓库）
export PYPI_API_TOKEN="your-token-here"

# 如需使用 TestPyPI 验证发布流程，可设置：
# export PYPI_REPOSITORY=testpypi
# 或：
# export PYPI_REPOSITORY_URL="https://test.pypi.org/legacy/"

# 5. 运行发布脚本（会自动运行测试、构建并上传）
./pypi_publish.sh

脚本会在发布成功后创建 v<version> Git 标签（例如 v2.2.2），根据提示手动执行：

git push origin v2.2.2

未来规划：

• 先在本仓库完成核心执行器的重构与简化
• 与需求文档和任务清单对齐后，再规划下一代主线版本（例如 3.x）

---

开发规范

• 代码风格：Google Python Style
• 注释：统一使用中文，解释「意图」而非「语法」
• 类型：尽量补全类型注解，保持 Pyright 通过
• 测试：新增/修改功能时应补充或更新 tests/unit 与 tests/yaml 中的用例
• 提交信息：建议使用前缀（如 feat:, fix:, chore:, docs:, refactor: 等）

---

关联文档

• 需求规格说明：docs/Sisyphus-api-engine需求文档.md
• YAML 输入规范：docs/Sisyphus-api-engine YAML 输入规范.md
• JSON 输出规范：docs/Sisyphus-api-engine JSON 输出规范.md
• 开发任务清单：docs/开发任务清单.md

---

许可证

本项目基于 MIT License 开源。欢迎在遵守协议的前提下自由使用、修改和分发。