Collection Config Files
To guarantee deterministic execution, eliminate external network dependency flakiness, and enable advanced state-based testing (such as auto-cleanup and healing), the Rumour configuration and example suites in this section are verified against our Local Mock Server (http://localhost:4000/api/v2) instead of public API endpoints (like httpbin.org or jsonplaceholder).
Why this change was made:
- Zero Flakiness: Public endpoints are subject to rate limiting and network latency, causing tests to fail randomly.
- Stateful Flows: Advanced features like Auto-Cleanup (
-C) and Hard Self-Healing (-X) require a mock server that maintains stateful resources (e.g. tracking created user and post IDs) to simulate real-world API behaviors. - Offline Hermetic Testing: Running against a local mock server allows you to test entirely offline or inside secure air-gapped CI/CD environments.
To get the mock server, clone the rumour_datasets repository and start it:
git clone https://github.com/swahira/rumour_datasets.git
cd rumour_datasets/mock-server
npm install
node server.js
The mock server will listen on http://localhost:4000/api/v2.
Rumour uses collection config files to apply shared settings — headers, query parameters, variables, and execution flags — to all requests in a directory and its subdirectories. This eliminates repetition across individual request files.
File Names
Rumour recognizes the following collection config filenames:
| Filename | Notes |
|---|---|
*.config.toml | Preferred format. Any name ending in .config.toml (e.g., auth.config.toml). |
collection.toml | Legacy standard name. |
_collection.toml | Legacy underscore-prefixed name. |
collection.env.toml | Legacy env-style name. |
Multiple .config.toml files in the same directory are loaded in alphabetical order and merged cumulatively.
Supported Sections
A config file is a TOML file with four optional top-level sections:
# auth/auth.config.toml
[headers]
Authorization = "Bearer {{access_token}}"
X-API-Version = "2"
[params]
debug = "true"
format = "json"
[variables]
base_url = "http://localhost:4000/api/v2"
timeout = "30"
[config]
parallel = true
heal = false
hard_heal = false
auto_cleanup = false
resume = false
# Requests that should NOT receive the headers/params/variables above:
exclude_files = ["health.toml", "*_public.toml"]
[headers]
Inherited by every request in the directory. Request-level headers override collection-level headers with the same name.
[params]
Query parameters injected into every request URL.
[variables]
Variables injected into the variable scope. These have higher priority than directory .env.toml files and CLI -V overrides. See [Variable Precedence](/ environments/variable-precedence) for the full priority stack.
[config]
Execution behaviour flags for the whole collection:
| Key | CLI Equivalent | Default | Description |
|---|---|---|---|
parallel | -p | false | Run non-dependent nodes concurrently |
heal | -H | false | Enable soft self-healing |
hard_heal | -X | false | Enable 404 resource reconstruction |
auto_cleanup | -C | false | Delete created resources after run |
resume | -r | false | Resume from previous execution state |
CLI flags always take precedence over [config] values in collection files when both are provided.
exclude_files
A top-level array of file name patterns. Any request whose filename matches a pattern will not inherit the headers, params, or variables from this config file. See Config Exclusions for full details and pattern syntax.
Directory Scoping & Cascading
Config files cascade from the workspace root down to the target directory. A config in a parent directory applies to all child directories unless overridden by a closer config.
project/
├── workspace.env.toml # base_url = "http://localhost:4000/api/v2"
├── api.config.toml # Applied to all requests in project/
└── auth/
├── auth.config.toml # Applied to auth/ only — merged with parent
└── get_post.toml # Inherits from both api.config.toml + auth.config.toml
Example
The following example was verified against the local mock server.
File Layout
config_examples/01_config_files/
├── workspace.env.toml
├── api.config.toml
└── auth/
├── auth.config.toml
└── get_post.toml
workspace.env.toml
base_url = "http://localhost:4000/api/v2"
api.config.toml
[headers]
X-App-Version = "{{app_version}}"
Accept = "application/json"
[variables]
api_env = "production"
app_version = "3.0"
auth/auth.config.toml
[headers]
X-Auth-Service = "true"
[variables]
service = "auth"
auth/get_post.toml
name = "verify_config_inheritance"
[request]
method = "GET"
url = "{{base_url}}/users/1"
[assert]
status = 200
[assert.json."id"]
equal = 1
[assert.json."email"]
contains = "test.com"
Run
rumour run ./config_examples/01_config_files/auth/ -v
Output
~/workspace/testing main ❯ rumour run ./config_examples/01_config_files/auth/ -v
GET http://localhost:4000/api/v2/users/1
Header: Accept: application/json
Header: X-Auth-Service: true
Header: X-App-Version: 3.0
URL: http://localhost:4000/api/v2/users/1
✓ SUCCESS: /home/bugsfounder/workspace/testing/config_examples/01_config_files/auth/get_post.toml (1ms)
✓ ./config_examples/01_config_files/auth/ → PASS (1 Pass, 0 Fail, 0 Skip)
╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests: 1 │
│ Successful: 1 │
│ Failed: 0 │
│ Skipped: 0 │
│ Success Rate: 100.0% │
│ Total Time: 2ms │
╰──────────────────────────────────────────────────────────────────────────╯
✓ Successful Requests:
- /home/bugsfounder/workspace/testing/config_examples/01_config_files/auth/get_post.toml [200] [2ms]
Actionable Recommendations:
→ Run with --json to export this report for your CI/CD pipeline.
get_post.toml inherits X-App-Version and Accept from api.config.toml, as well as X-Auth-Service and service from auth/auth.config.toml — avoiding any duplication across individual requests.