drun 8.1.3

Easy-to-use API testing with DevOps automation support

Drun: Modern HTTP API Testing Framework

English | 中文

Documentation · GitHub

Drun is a YAML-driven HTTP API testing framework. It lets you describe requests, variable extraction, checks, suite orchestration, and report output in concise YAML, making API validation, debugging, and CI/CD execution easier to maintain.

Highlights

• YAML DSL: write tests with config, steps, extract, check, and caseflow.
• Template system: supports $var, ${ENV(KEY)}, ${uuid()}, and other dynamic expressions.
• Rich checks: built-in checks such as eq, contains, regex, len_eq, and gt.
• Test orchestration: supports suites, invoke, step repeat, and tag filtering.
• Sleep steps: supports explicit wait DSL such as sleep: 2000, using milliseconds.
• Outputs: HTML, JSON, Allure reports, logs, and generated code snippets.
• Debug-friendly: drun q for quick requests, plus converters from cURL, Postman, HAR, and OpenAPI.

Installation

Python 3.10+ is recommended.

pip install drun

If you prefer uv:

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

Quick Start

1. Initialize a Project

drun i myproject
cd myproject

Default scaffold:

myproject/
├── tcases/
├── tsuites/
├── data/
├── converts/
├── logs/
├── reports/
├── snippets/
├── .env
└── Dhook.py

2. Configure Environment Variables

.env

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

3. Write Your First Test

tcases/tc_user_api.yaml

config:
  name: User API Test
  base_url: ${ENV(BASE_URL)}
  tags: [smoke, user]

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

  - name: Get User
    request:
      method: GET
      path: /users/${ENV(USER_ID)}
      headers:
        Authorization: Bearer ${ENV(API_KEY)}
    check:
      - eq: [status_code, 200]

4. Run Tests

drun r tcases/tc_user_api.yaml -env dev
drun r test_user_api -env dev
drun r tcases -env dev -k "smoke and not slow"
drun r test_user_api -env dev -html reports/report.html

Notes:

• .yaml can be omitted in run targets.
• Temporary single-file runs write only one log file to the current directory.
• Scaffolded project runs keep outputs in logs/, reports/, and snippets/.

Common Patterns

Single Test File

config:
  name: Login API
  base_url: ${ENV(BASE_URL)}

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

Suite File

config:
  name: Smoke Suite

caseflow:
  - name: Login
    invoke: test_login
  - name: Profile
    invoke: test_profile

Data-Driven Execution

config:
  name: Batch Registration
  parameters:
    - csv:
        path: data/users.csv

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

Repeated Steps

steps:
  - name: Retry Health Check
    repeat: 3
    request:
      method: GET
      path: /health
    check:
      - eq: [status_code, 200]

Sleep Steps

steps:
  - name: Wait for stabilization
    sleep: 2000

  - name: Wait from variable
    sleep: ${wait_ms}

Common Commands

Run and Debug

drun r PATH -env dev
drun q https://api.example.com/ping
drun q https://api.example.com/users -X POST -d '{"name":"alice"}'
drun t tcases
drun c tcases
drun f tcases

drun c aggregates YAML/DSL authoring diagnostics with stable error codes such as DRUN-YAML-003, file locations, fix hints, and minimal examples. drun r still stops quickly on blocking YAML errors.

Format Conversion

drun o sample.curl -outfile out.yaml
drun w spec/openapi/ecommerce_api.json -output-mode split -outfile converted/ecommerce.yaml
drun e curl tcases/tc_user_api.yaml -outfile request.curl

Report Server

drun s
drun s -port 8080

After startup, you can browse the report list and detail pages in the browser.

Reports and Outputs

• HTML: good for local viewing and sharing.
• JSON: good for CI pipelines and machine consumption.
• Allure: good for integration with test platforms.
• Snippets: generates Shell or Python request scripts for replaying requests.

Examples:

drun r tcases -env dev -html reports/report.html
drun r tcases -env dev -allure-results allure-results
allure serve allure-results

Develop from Source

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

Repository overview:

• drun/: core implementation.
• tests/: regression tests.
• spec/: sample OpenAPI specs.
• CHANGELOG.md: version history.
• drun-usage/: local deep-usage skill for AI coding assistants, covering drun YAML, CLI usage, conversion, and troubleshooting.
• AGENTS.md: contributor rules and local development notes.

AI Assistant Collaboration

This repository includes a local skill at drun-usage/. Its purpose is to help AI coding assistants answer drun questions using the repository's actual CLI and DSL behavior, and to return runnable YAML, CLI commands, and troubleshooting guidance instead of generic API testing advice.

Typical use cases:

• Generate drun YAML cases
• Explain invoke, invoke_case_name, invoke_case_names, repeat, and sleep
• Design drun r, drun q, convert, convert-openapi, and export curl commands
• Explain HTML / JSON / Allure / snippet / server
• Troubleshoot drun errors

Claude Code

If you use Claude Code, the safest approach is to mention the skill explicitly or ask it to read the skill files before working.

Example prompts:

Use drun-usage to generate a drun testsuite for login and profile lookup.

Read drun-usage/SKILL.md first, then convert this curl command into drun YAML and provide the run command.

Codex

If you use Codex, explicitly naming drun-usage works well. Natural trigger phrases such as "drun YAML", "drun invoke", or "drun troubleshooting" are also useful. When collaborating in this repository, read AGENTS.md first.

Example prompts:

Use drun-usage to explain the difference between invoke_case_name and invoke_case_names, and give me a runnable example.

Help me debug this drun error, and consult drun-usage/references/troubleshooting.md if needed.

OpenCode

If you use OpenCode and your workflow does not automatically discover local skills, explicitly ask it to read drun-usage/SKILL.md first, then load the matching file under references/ as needed.

Example prompts:

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 w command for this spec.

Usage Tips

• If you want runnable YAML and commands, mention drun-usage explicitly
• If you only need one DSL concept, ask directly, for example: "Explain drun repeat"
• If you change CLI, DSL, reporting, or troubleshooting behavior, update drun-usage/ accordingly

Use Cases

• HTTP API regression testing
• Smoke testing and release verification
• Data-driven execution
• API debugging and request replay
• CI/CD quality gates for interfaces

Contributing

Before opening a PR, run at least:

python -m pytest -q
drun --help

If you are contributing within this repository, read AGENTS.md first.

License

MIT