Skip to main content

Local Variables

Request-local variables are defined inside the [variables] block of a Request Node. These variables are scoped strictly to the file in which they are declared and can be used to avoid duplicating values in URLs, headers, params, or request bodies.

1. Placeholder Syntax Types​

Rumour supports three distinct formats for referencing variables inside request templates:

A. Double Braces ({{var}})​

The standard and most versatile placeholder syntax.

  • Use Case: Ideal for environment overrides, vault variables, and references to nested upstream dependency fields (e.g., {{../../auth/requests/login.token}}).
  • Nesting: Supports recursive resolution (e.g., {{user_{{id}}}}).
  • Example: url = "{{base_url}}/api/{{env.ENV_STAGE}}"

B. Single Braces ({var})​

A clean parameter-style placeholder designed for simple alphanumeric local variables.

  • Use Case: Best suited for request-local variables and headers.
  • Safety: Designed to prevent conflicts and avoid matching standard JSON payload brackets (e.g., {"token": "xyz"}).
  • Example: X-Client = "{client_name}"

C. Colon Prefix (:var / /:var)​

A REST-style path parameter placeholder.

  • Use Case: Used directly within URLs to denote dynamic path segments.
  • Rule: Matches identifiers that are placed at the beginning of the path string or immediately follow a forward slash.
  • Example: url = "https://httpbin.org/anything/:action" (resolves to https://httpbin.org/anything/get if action is set to "get").

2. Setup Environment​

To set up a test environment from scratch and replicate the workspace variables example, follow these steps:

A. Initialize the Workspace​

Create a new directory and initialize a clean, zero-clutter Rumour workspace root:

mkdir variable_example
cd variable_example
rumour init

B. Scaffold Modular Collections​

Scaffold two modular collections inside the workspace (auth and users) using the scaffolding tool:

rumour new auth
rumour new users

3. Directory Structure & File Contents​

After setting up the workspace, your directory structure will look like this:

variable_example/
├── workspace.env.toml
├── variable_example.config.toml
├── variable_example.suite.toml
├── auth/
│   ├── auth.config.toml
│   ├── auth.env.toml
│   ├── auth.suite.toml
│   └── requests/
│       └── login.toml
└── users/
    ├── users.config.toml
    ├── users.env.toml
    ├── users.suite.toml
    └── requests/
        └── get_users.toml

Here are the complete contents for each file in this setup:

A. Workspace Level Files​

workspace.env.toml​

Defines base variables and global environment definitions.

# workspace.env.toml
[variables]
base_url = "https://httpbin.org"
"env.ENV_STAGE" = "staging"

variable_example.config.toml​

Workspace-level request runner configurations.

[config]
# timeout_ms = 5000
# max_retries = 3

variable_example.suite.toml​

Global ordered execution suite.

[suite]
name = "Workspace Workflow Suite"
description = "Global ordered execution suite for all workspace request workflows."
ordered = true

requests = [
    # Add paths to your requests or modular collection suites here
]

B. auth Collection Files​

auth/auth.config.toml​

Collection-level configuration for the auth collection.

[config]
# timeout_ms = 5000
# max_retries = 3
# retry_backoff_ms = 500

auth/auth.env.toml​

Collection-level variables for the auth collection.

[variables]
# Collection-level variables for the 'auth' collection.

auth/auth.suite.toml​

Modular suite for executing auth requests.

[suite]
name = "Auth Workflow Suite"
description = "Modular ordered execution suite for Auth request workflows."
ordered = true

requests = [
    "requests/login.toml"
]

auth/requests/login.toml​

Performs authentication and extracts the returned token from the JSON body payload.

# auth/requests/login.toml
[request]
method = "POST"
url = "{{base_url}}/post"

[body]
raw = '{"username": "admin", "token": "session_secret_xyz123"}'

[extract]
token = "json.token"

C. users Collection Files​

users/users.config.toml​

Collection-level configurations.

[config]
# timeout_ms = 5000
# max_retries = 3
# retry_backoff_ms = 500

users/users.env.toml​

Collection-level variables.

[variables]
# Collection-level variables for the 'users' collection.

users/users.suite.toml​

Modular suite for executing users requests.

[suite]
name = "Users Workflow Suite"
description = "Modular ordered execution suite for Users request workflows."
ordered = true

requests = [
    "requests/get_users.toml"
]

users/requests/get_users.toml​

This file utilizes all three placeholder formats (double braces, single braces, and path colons) to define routing, headers, and params.

# users/requests/get_users.toml
[dependencies]
"../../auth/requests/login.toml" = "token"

[request]
method = "GET"
url = "{{base}}/anything/:action/client/{client_name}"

[headers]
Authorization = "Bearer {{../../auth/requests/login.token}}"
X-Client = "{client_name}"
X-Stage = "{{env.ENV_STAGE}}"

[params]
api_key = "{{vault.SECURE_KEY}}"

[variables]
# 1. Nesting / self-referential expansion using double braces
domain = "httpbin.org"
protocol = "https"
base = "{{protocol}}://{{domain}}"

# 2. Variable mapping for colon placeholder (:action)
action = "get"

# 3. Variable mapping for single brace placeholder ({client_name})
client_name = "RumourTestAgent"

4. Run the Requests & Outputs​

To run the execution of the main request, execute the following command. Pass your vault decryption password if utilizing secure parameters:

Command​

RUMOUR_VAULT_PASS=mypassword123 rumour run variable_example/users/requests/get_users.toml -tv

Output​

~/workspace/testing main* ❯ RUMOUR_VAULT_PASS=mypassword123 rumour run variable_example/users/requests/get_users.toml -tv
  POST https://httpbin.org/post
  URL: https://httpbin.org/post
  Body (json): {"username": "admin", "token": "session_secret_xyz123"}
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/variable_example/auth/requests/login.toml (1127ms)
  
  GET https://httpbin.org/anything/get/client/RumourTestAgent
  Header: Authorization: Bearer session_secret_xyz123
  Header: X-Client: RumourTestAgent
  Header: X-Stage: staging
  URL: https://httpbin.org/anything/get/client/RumourTestAgent?api_key=super_secure_vault_value_987
  Query Param: api_key=super_secure_vault_value_987
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/variable_example/users/requests/get_users.toml (346ms)
    ✓ variable_example/users/requests/get_users.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:          1521ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/variable_example/auth/requests/login.toml  [200] [1130ms]
  - /home/bugsfounder/workspace/testing/variable_example/users/requests/get_users.toml  [200] [390ms]

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

5. Scope Resolution Priority​

When Rumour encounters a placeholder, it resolves the value based on the following hierarchy (from highest precedence to lowest):

  1. Explicit dependency variables / Output variables (sourced from upstream dependency runs).
  2. Local variables (defined inside the [variables] block of the current file).
  3. Environment/Workspace variables (defined in *.env.toml or workspace.env.toml).
  4. Vault secrets (referenced as {{vault.SECRET}} with decryption key or system environment variables fallback).
Circular Dependencies

Avoid creating circular references within your local variables (e.g., a = "{{b}}" and b = "{{a}}"). Doing so will cause the variable resolver to throw a cycle resolution error and abort execution.