hurl-orchestra

Appearance

AI first API automation testing, on Hurl

Test your APIfrom login to checkout.

Write each step as a small text file: log in, add to cart, pay. hurl-orchestra runs the steps in the right order, passes the login token to the steps that need it and shows you which step broke. Easy to read for you and for your AI assistant.

Get started
pip install hurl-orchestra

Try it

Watch a test run, step by step.

Each box is one test file. A step starts only when the steps before it pass, and steps that do not depend on each other run at the same time. Click a box to make it fail, then see which steps stop and which continue.

tests/ 5 files
wave 1 wave 2 wave 3 wave 4authcatalogcreate_cartadd_itemcheckout
passesfailsknown failureskippedTap or click a box to change its result.
$

wave 1

Say what each step needs. The order follows. ​

Each file lists the steps that must pass first in deps. hurl-orchestra finds the correct order. You do not write a script for it, and you do not copy the login request into each file.

hurl
---
id: profile
deps: [auth]
---
GET {{base_url}}/profile
Authorization: Bearer {{auth_token}}
HTTP 200
[Asserts]
jsonpath "$.user" == "ada"

wave 2

Share a value, like a login token, between steps. ​

The login step saves the token from the response and lists it in outputs. Each later step reads it as auth_token: the name of the step, then the name of the value.

hurl
---
id: auth
outputs: [token]
---
POST {{base_url}}/login
{
  "user": "ada",
  "password": "{{password}}"
}
HTTP 200
[Captures]
token: jsonpath "$.token"

wave 3

Mark the failures that you already know about. ​

Sometimes a test fails for a known reason, for example a busy shared database. Describe that failure in known_failures. The run still passes, the report still shows the failure, and the exception ends on its until date.

hurl
---
id: create_order
outputs: [order_id]
known_failures:
  - name: db_pool_exhausted
    reason: The shared test database is at its connection limit
    until: 2026-12-31
    link: https://example.com/runbooks/test-db-pool
    status: 500
    header:
      name: X-Error-Code
      pattern: '^ERR-DB-\d+$'
---
POST {{base_url}}/orders
HTTP 200
[Captures]
order_id: jsonpath "$.id"

wave 4

Try again when the server is busy. ​

A retry block runs the step again after a short wait, and each wait is longer than the last one. It obeys the Retry-After header of the server, and it retries only the failures that you list in when.

hurl
---
id: create_order
retry:
  attempts: 4
  backoff_ms: 500
  max_backoff_ms: 20000
  multiplier: 2
  jitter: full
  when:
    - status: 429
    - status: 503
    - stderr: 'Connection refused'
---
POST {{base_url}}/orders
HTTP 201

wave 5

Let your AI assistant write the next test. ​

AI first means that an AI assistant, such as Claude Code, can read and check each part. The tests are plain text. The plan and the results are JSON, and each failure shows the expected value and the actual value. There is no AI inside hurl-orchestra, and there is nothing to configure.

Work with AI agents →

bash
hurl-orchestra --dry-run --json tests
json
{
  "ok": true,
  "waves": [["auth"], ["create_cart"]],
  "nodes": [
    {
      "id": "create_cart",
      "deps": ["auth"],
      "variables": ["auth_token"]
    }
  ]
}

Results that you can share ​

Each run saves a report of each request. On GitHub, each request shows as a test in the summary of the job, so your team and your AI assistant read the same result.

Report in GitHub Actions