Configuration reference

Loady reads one YAML file and converts its scenarios into an ordered execution plan. The current schema is defined by core/config/yaml_config.go.

Complete schema example

The reserved .test domain below is illustrative. Replace it with a target you own or have explicit permission to test.

name: "Checkout workload"
target: "https://api.example.test"

scenarios:
  - name: "Browse and add to basket"
    virtual_users: 25
    duration: 2m
    ramp_up_duration: 30s
    ramp_down_duration: 30s

    steps:
      - name: "List products"
        think_time: 500ms-1s
        request:
          method: GET
          url: "https://api.example.test/products"
          timeout: 5s
          headers:
            x-api-key: "${API_KEY}"

      - name: "Add product to basket"
        think_time: 1s-2s
        request:
          method: POST
          url: "https://api.example.test/basket"
          timeout: 5s
          headers:
            Content-Type: "application/json"
            x-api-key: "${API_KEY}"
          body: '{"product_id":"product-1","quantity":1}'

Top-level fields

Field	Required	Current behavior
name	Yes	Non-empty name for the load test.
target	Yes	Must be an absolute HTTP or HTTPS URL. It is displayed by the CLI but is not used to resolve request URLs.
scenarios	Yes	One or more scenarios. They run sequentially in file order.

Scenario fields

Field	Required	Current behavior
name	No	Display name printed before the scenario runs.
virtual_users	Yes	Integer from 1 through 300.
duration	Yes	Go duration of at least 60 seconds and less than one hour. This includes ramp-up, hold, and ramp-down.
ramp_up_duration	Yes	Go duration used to add virtual users gradually.
ramp_down_duration	Yes	Go duration used to remove virtual users gradually.
steps	Yes	Ordered list of steps repeated by every active virtual user.

ramp_up_duration + ramp_down_duration must not exceed duration. The remaining time is the steady hold period.

Step fields

Field	Required	Current behavior
name	Yes	Non-empty step name.
think_time	Yes	Two valid Go durations separated by -, for example 250ms-1s. Use a lower bound smaller than the upper bound.
request	Yes	HTTP request executed after think time.

The CLI chooses a random think time in the configured range before each request.

Request fields

Field	Required	Current behavior
method	Yes	One of GET, POST, PATCH, or DELETE.
url	Yes	Complete absolute HTTP or HTTPS URL. Relative paths are not supported.
timeout	Yes	Valid Go duration applied to the request context.
headers	No	String-to-string HTTP header map.
body	No	String sent as the request body. Loady does not add a content type automatically.

Environment variables in headers

Loady replaces ${NAME} placeholders in header values with environment variables after parsing:

headers:
  Authorization: "Bearer ${API_TOKEN}"

API_TOKEN=secret ./bin/loady start config.yml

Substitution currently applies only to header values. Missing variables remain as their literal ${NAME} placeholders. The target, request URL, and body are not interpolated.

Execution and response handling

Scenarios run sequentially. Within a scenario, each virtual user repeatedly executes every step in order until ramp-down or cancellation.

Every received HTTP response records its latency and status code and currently counts as successful regardless of whether the status is 2xx, 4xx, or 5xx. Transport errors and request deadline failures produce unsuccessful outcomes. Response bodies are not retained or evaluated, and configurable assertions or status-code success criteria are not currently supported.

Cancellation and debug mode

Loady propagates cancellation through scenarios, virtual users, steps, and HTTP requests. Press Ctrl+C to stop a run.

Pass --debug to expose Go's pprof endpoints on localhost:6060 while the test runs:

./bin/loady start config.yml --debug