Suite Variables

The [variables] section in a suite file injects key-value pairs into the runtime variable scope for every request in that suite. This is the primary mechanism for parameterizing a suite without modifying any individual request file.

Defining Suite Variables

[suite]
name    = "Staging Run"
ordered = true

requests = [
  "auth/login.toml",
  "users/get_profile.toml",
]

[variables]
base_url     = "https://staging.api.example.com"
api_version  = "v2"
target_user  = "42"

All requests in the suite can use {{base_url}}, {{api_version}}, and {{target_user}} without those variables being declared anywhere else.

Priority in the Resolution Chain

Suite variables are merged into the runtime variable map before execution begins. Their priority is lower than CLI -V overrides:

Priority	Source
1 (Highest)	Vault secrets
2	Request [variables]
3	Collection [variables] (.config.toml)
4	CLI -V overrides
5	Suite [variables] ← this section
6	Directory .env.toml files
7 (Lowest)	-e custom env file

note

This means a .config.toml in the same directory as a request file can override both CLI -V overrides and suite variables for that specific subdirectory. If you need suite variables or CLI overrides to take absolute precedence, consider using vault secrets or request-level [variables].

Values Are Always Strings

All variable values must be TOML strings:

[variables]
timeout    = "30"          # ✅ string
page_size  = "10"          # ✅ string
debug      = "false"       # ✅ string
retries    = 3             # ❌ integer — will cause a parse error

Variable Interpolation

Suite variables can reference other variables, including those from workspace.env.toml:

# workspace.env.toml
base_url = "https://api.example.com"

# targeted.suite.toml
[variables]
users_url = "{{base_url}}/users"
posts_url = "{{base_url}}/posts"

Rumour resolves these with multi-pass expansion (up to 3 passes).

Nested Suite Variable Merging

When a suite references nested suites, each nested suite's [variables] are merged in expansion order. Later nested suites override earlier ones for the same key:

# parent.suite.toml
[suite]
requests = [
  "suite_a.suite.toml",   # provides: env = "staging"
  "suite_b.suite.toml",   # provides: env = "production" → wins
]

Example

A suite that targets specific resource IDs without modifying the request files.

File Layout

suite_examples/04_suite_variables/
├── workspace.env.toml
├── targeted.suite.toml
├── get_post.toml
└── get_user.toml

workspace.env.toml

base_url = "http://localhost:4000/api/v2"

targeted.suite.toml

[suite]
name    = "Targeted Run"
ordered = true

requests = [
  "get_post.toml",
  "get_user.toml",
]

[variables]
target_post_id = "2"
target_user_id = "3"

get_post.toml

name = "get_post_with_suite_var"

[request]
method = "GET"
url    = "{{base_url}}/users/{{target_post_id}}"

[assert]
status = 200

[assert.json."id"]
equal = 2

get_user.toml

name = "get_user_with_suite_var"

[request]
method = "GET"
url    = "{{base_url}}/users/{{target_user_id}}"

[assert]
status = 200

[assert.json."id"]
equal = 3

Run

rumour run ./targeted.suite.toml -v

Output

✓ ./targeted.suite.toml → PASS (2 Pass, 0 Fail, 0 Skip)

╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT                                                  │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests:      2                                                   │
│ Successful:          2                                                   │
│ Failed:              0                                                   │
│ Skipped:             0                                                   │
│ Success Rate:        100.0%                                              │
│ Total Time:          4ms                                                 │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - get_post.toml  [200] [3ms]
  - get_user.toml  [200] [1ms]

target_post_id = "2" and target_user_id = "3" are injected from the suite — the request files themselves have no knowledge of which IDs to use. To run against different IDs, only the suite file needs to change.

Parameterized CI/CD Runs

Use CLI -V overrides to further parameterize a suite at runtime without modifying any file:

# Override a suite variable from the command line
rumour run ./targeted.suite.toml -V target_post_id=5 -V target_user_id=7

This lets a single suite file serve multiple CI environments by passing different values at invocation time.