Suite Files

A suite file (*.suite.toml) is a curated list of requests that Rumour executes as a single named workflow. Suites let you define smoke tests, regression runs, or any ordered collection without manually listing files on the command line.

File Format

Suite files use the .suite.toml extension and contain two top-level sections:

[suite]
name        = "Smoke Test Suite"
description = "Quick health check for auth and posts endpoints"
ordered     = true

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

[variables]
test_env = "staging"

[suite] Fields

Field	Type	Default	Description
name	string	required	Human-readable name for the suite
description	string	optional	Short description shown in reports
ordered	bool	true	Whether requests execute in list order (sequential)
requests	string[]	required	Paths to .toml request files, directories, or nested .suite.toml files

[variables]

An optional map of key-value strings injected into every request in the suite. See Suite Variables for full details.

Running a Suite

rumour run ./smoke.suite.toml

Rumour detects the .suite.toml extension automatically and enters suite execution mode.

Common flags

# Verbose summary
rumour run ./smoke.suite.toml -v

# Parallel (only effective when ordered = false)
rumour run ./smoke.suite.toml -p

# With healing enabled
rumour run ./smoke.suite.toml -H

# JUnit output for CI
rumour run ./smoke.suite.toml --junit results.xml

Path Resolution

Paths in the requests array are resolved relative to the suite file's location:

requests = [
  "auth/login.toml",       # → <suite-dir>/auth/login.toml
  "posts/create.toml",     # → <suite-dir>/posts/create.toml
  "../shared/setup.toml",  # → parent directory
]

If a relative path is not found, Rumour falls back to the workspace root (the directory containing workspace.env.toml).

The .toml extension is optional in path entries:

requests = [
  "auth/login",     # resolved as auth/login.toml
  "posts/create",
]

Directory References

You can list a directory instead of individual files:

requests = [
  "auth/",       # all *.toml files in auth/ (alphabetical, recursive)
  "posts/",
]

Rumour discovers all .toml files recursively, sorted alphabetically, while automatically excluding *.env.toml, *.config.toml, *.suite.toml, collection.toml, and _collection.toml.

Example

Verified against the local mock server.

File Layout

suite_examples/01_suite_files/
├── workspace.env.toml
├── smoke.suite.toml
├── auth/
│   └── get_user.toml
└── posts/
    └── get_post.toml

smoke.suite.toml

[suite]
name        = "Smoke Test Suite"
description = "Quick health check for auth and posts endpoints"
ordered     = true

requests = [
  "auth/get_user.toml",
  "posts/get_post.toml",
]

auth/get_user.toml

name = "get_user"

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

[assert]
status = 200

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

posts/get_post.toml

name = "get_post"

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

[assert]
status = 200

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

Run

rumour run ./suite_examples/01_suite_files/smoke.suite.toml -v

Output

~/workspace/testing main ❯ rumour run ./suite_examples/01_suite_files/smoke.suite.toml -v
  GET http://localhost:4000/api/v2/users/1
  URL: http://localhost:4000/api/v2/users/1
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/suite_examples/01_suite_files/auth/get_user.toml (2ms)
  GET http://localhost:4000/api/v2/users/2
  URL: http://localhost:4000/api/v2/users/2
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/suite_examples/01_suite_files/posts/get_post.toml (1ms)
    ✓ /home/bugsfounder/workspace/testing/suite_examples/01_suite_files/smoke.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:          5ms                                                 │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/suite_examples/01_suite_files/auth/get_user.toml  [200] [3ms]
  - /home/bugsfounder/workspace/testing/suite_examples/01_suite_files/posts/get_post.toml  [200] [1ms]

Actionable Recommendations:
  → Run with --json to export this report for your CI/CD pipeline.

Explanation

When you execute a .suite.toml file:

• Rumour parses the requests array relative to the suite file's directory.
• Because ordered = true is set in smoke.suite.toml, the requests are executed sequentially in the declared order: get_user.toml first, then get_post.toml.
• If one request fails, the execution stops immediately (unless healing -H or specific skip policies are active).