drun 7.2.19

Easy-to-use API testing with DevOps automation support

Drun：现代 HTTP API 测试框架

中文 | English

Drun 是一个面向 HTTP API 的 YAML 驱动测试框架。你可以用简洁的 YAML 描述接口、变量提取、断言、套件编排和报告输出，把接口验证、调试和 CI/CD 串成一条可维护的链路。

核心能力

• YAML DSL：通过 config、steps、extract、validate、caseflow 编写测试。
• 模板系统：支持 $var、${ENV(KEY)}、${uuid()} 等动态表达式。
• 丰富断言：内置 eq、contains、regex、len_eq、gt 等校验。
• 测试编排：支持测试套件、invoke 调用、步骤 repeat、标签过滤。
• 延时步骤：支持 sleep: 2000 这类显式等待 DSL，单位为毫秒。
• 结果输出：支持 HTML、JSON、Allure 报告，以及日志、代码片段导出。
• 调试友好：支持 drun q 快速发请求，支持从 cURL、Postman、HAR、OpenAPI 转换用例。

安装

推荐 Python 3.10+。

pip install drun

如果你使用 uv：

uv venv
source .venv/bin/activate
uv pip install drun

快速开始

1. 初始化项目

drun init myproject
cd myproject

默认会生成类似结构：

myproject/
├── testcases/
├── testsuites/
├── data/
├── converts/
├── logs/
├── reports/
├── snippets/
├── .env
└── Dhook.py

2. 配置环境变量

.env

BASE_URL=https://api.example.com
API_KEY=demo-token

3. 编写第一个测试

testcases/test_user_api.yaml

config:
  name: 用户接口测试
  base_url: ${ENV(BASE_URL)}
  tags: [smoke, user]

steps:
  - name: 创建用户
    request:
      method: POST
      path: /users
      headers:
        Authorization: Bearer ${ENV(API_KEY)}
      body:
        username: test_${uuid()}
        email: [e-mail]
    extract:
      userId: $.data.id
    validate:
      - eq: [status_code, 201]
      - regex: [$.data.id, '^\d+$']

  - name: 查询用户
    request:
      method: GET
      path: /users/${ENV(USER_ID)}
      headers:
        Authorization: Bearer ${ENV(API_KEY)}
    validate:
      - eq: [status_code, 200]

4. 执行测试

drun run testcases/test_user_api.yaml -env dev
drun run test_user_api -env dev
drun run testcases -env dev -k "smoke and not slow"
drun run test_user_api -env dev -html reports/report.html

说明：

• 支持省略 .yaml 扩展名。
• 单文件临时运行时，默认只在当前目录输出一个日志文件。
• 脚手架项目运行时，会默认输出到 logs/、reports/、snippets/。

常用写法

单用例文件

config:
  name: 登录接口
  base_url: ${ENV(BASE_URL)}

steps:
  - name: 登录
    request:
      method: POST
      path: /login
      body:
        username: admin
        password: pass123
    extract:
      token: $.data.token
    validate:
      - eq: [status_code, 200]

套件文件

config:
  name: 冒烟套件

caseflow:
  - name: 登录
    invoke: test_login
  - name: 查询资料
    invoke: test_profile

数据驱动

config:
  name: 批量注册
  parameters:
    - csv:
        path: data/users.csv

steps:
  - name: 注册 $username
    request:
      method: POST
      path: /register
      body:
        username: $username
        email: $email
    validate:
      - eq: [status_code, 201]

重复执行

steps:
  - name: 重试健康检查
    repeat: 3
    request:
      method: GET
      path: /health
    validate:
      - eq: [status_code, 200]

延时步骤

steps:
  - name: 等待服务稳定
    sleep: 2000

  - name: 按变量等待
    sleep: ${wait_ms}

常用命令

运行与调试

drun run PATH -env dev
drun q https://api.example.com/ping
drun q https://api.example.com/users -X POST -d '{"name":"alice"}'
drun tags testcases
drun check testcases
drun fix testcases

格式转换

drun convert sample.curl -outfile out.yaml
drun convert-openapi spec/openapi/ecommerce_api.json -output-mode split -outfile converted/ecommerce.yaml
drun export curl testcases/test_user_api.yaml -outfile request.curl

报告服务

drun server
drun server -port 8080

启动后可浏览测试报告列表并查看详情页。

报告与输出

• HTML：适合本地查看与分享。
• JSON：适合流水线消费。
• Allure：适合集成到测试平台。
• Snippets：自动生成 Shell 或 Python 请求脚本，便于复现请求。

示例：

drun run testcases -env dev -html reports/report.html
drun run testcases -env dev -allure-results allure-results
allure serve allure-results

从源码开发

git clone https://github.com/Devliang24/drun.git
cd drun
pip install -e ".[dev]"
python -m pytest -q
python -m drun.cli --version

仓库主目录说明：

• drun/：核心实现。
• tests/：回归测试。
• spec/：示例 OpenAPI 规范。
• CHANGELOG.md：版本历史。
• drun-usage/：面向 AI 编码助手的本地深度使用 skill，提供 drun YAML、CLI、排障与转换说明。
• AGENTS.md：贡献者约定与本地开发说明。

AI 助手协作

仓库内置了本地 skill drun-usage/，用于让 AI 编码助手在处理 drun 相关问题时，优先按当前仓库真实能力给出可执行 YAML、CLI 命令和排障建议，而不是泛化地讨论 API 测试理论。

适用场景包括：

• 生成 drun YAML 用例
• 解释 invoke、invoke_case_name、invoke_case_names、repeat、sleep
• 设计 drun run、drun q、convert、convert-openapi、export curl
• 解释 HTML / JSON / Allure / snippet / server
• 根据报错做 drun 排障

Claude Code

如果你使用 Claude Code，建议在仓库根目录直接明确点名这个 skill，或要求它先读该目录下说明再执行。

示例提示词：

请使用 drun-usage，帮我写一个登录后查询资料的 drun testsuite。

先阅读 drun-usage/SKILL.md，再帮我把这个 curl 转成 drun YAML，并给出 run 命令。

Codex

如果你使用 Codex，推荐直接提 drun-usage 名称，或用自然语言触发词，例如“drun YAML”“drun invoke”“drun 排障”。在本仓库协作时，也建议先阅读 AGENTS.md。

示例提示词：

使用 drun-usage，解释 invoke_case_name 和 invoke_case_names 的区别，并给我可运行示例。

帮我排查这个 drun 报错，必要时参考 drun-usage/references/troubleshooting.md。

OpenCode

如果你使用 OpenCode，且当前工作流不会自动发现本地 skill，最稳妥的方式是显式要求它先读取 drun-usage/SKILL.md，再按需要读取 references/ 下对应文件。

示例提示词：

Read drun-usage/SKILL.md first, then generate a drun YAML case for file upload and provide the matching run command.

Read drun-usage/references/debug-convert-export.md and give me a drun convert-openapi command for this spec.

使用建议

• 需要“直接产出可运行 YAML 和命令”时，优先显式提 drun-usage
• 只问单个 DSL 点时，可以直接说“解释 drun repeat”或“解释 drun export curl”
• 如果改动了 drun 的 CLI、DSL、报告输出或排障行为，记得同步更新 drun-usage/

适用场景

• HTTP API 回归测试
• 冒烟测试与发布验证
• 测试数据驱动执行
• 接口调试与请求复现
• CI/CD 中的接口质量门禁

贡献

欢迎提交 issue 或 PR。提交前建议至少执行以下命令：

python -m pytest -q
drun --help

如果你在仓库内协作开发，请先阅读 AGENTS.md。

License

MIT