Skip to main content

Built-in Special Variables

Rumour provides built-in dynamic placeholders and special variable resolution mechanics. These allow you to inject randomized identifiers, generate timestamps, perform directory-relative lookups, and automatically swap auth contexts.

Dynamic Placeholders​

These placeholders are evaluated dynamically at runtime whenever a request is compiled.

1. Unique Random Identifier ({{random}})​

The {{random}} placeholder generates a unique random string, designed for request correlation, generating unique identifiers (like email addresses, usernames, or transaction IDs), and seeding test data dynamically.

Its format and generation mechanism depend on the execution context:

  • Workflow/Directory Execution Context: When executed as part of a directory run or a workflow suite (using the workflow executor), the engine pre-populates the random seed with the first 8 characters of a fresh UUID v4 (e.g., 381406ce, baba76ff).
  • Single Request/Standalone Context: When executing a single request file directly outside of a workflow session (where the random seed remains uninitialized), the engine falls back to generating a 12-digit decimal string derived from the last 12 digits of the current system epoch nanosecond timestamp (e.g., 801938261307).

Single Request Consistency​

Regardless of the generation method, the resolved value is cached for the duration of a single request's execution. If you reference {{random}} multiple times inside the same request (e.g., in both the request body and custom tracking headers), all instances resolve to the exact same value. This is crucial for API flows where a generated ID in the body must match a correlation header or URL path parameter.

Multi-Request Uniqueness​

Every request execution in a workflow has its own independent lifecycle. When a new request starts, the cache is reset, and a fresh seed is generated. This guarantees that different request nodes in your test suite receive different random values.

Usage: Correlating Request and Header IDs​

name = "create_transaction"

[request]
method = "POST"
url = "{{base_url}}/transactions"

[headers]
Content-Type = "application/json"
X-Correlation-ID = "txn-{{random}}"

[body]
type = "json"
raw = '{"transaction_id": "txn-{{random}}", "amount": 100.0}'

Both X-Correlation-ID and transaction_id resolve to the same value (e.g., txn-381406ce).

Usage: Seeding Unique User Accounts​

Append {{random}} to standard strings to avoid collision errors in registration databases:

name = "register_user"

[request]
method = "POST"
url = "{{base_url}}/register"

[body]
type = "json"
raw = '{"email": "user_{{random}}@example.com", "username": "player_{{random}}"}'
note

If you need to persist a random value across different request files (for example, registering a user in step 1 and logging them in in step 2), do not rely on {{random}} in both files. Instead, use Rumour's Variable Extraction to capture the generated value from the response of the first request and reference it in the second using a relative path lookup.

2. Timestamps​

Rumour provides built-in placeholders to inject the current system epoch time:

  • {{timestamp}} or {{timestamp_ms}}: Returns the current system Unix epoch time in milliseconds (13-digit decimal string).
  • {{timestamp_sec}}: Returns the current system Unix epoch time in seconds (10-digit decimal string).

Syntax Example​

name = "placeholders"

[request]
method = "POST"
url = "{{base_url}}/post"

[body]
type = "json"
raw = '{"random_1": "{{random}}", "random_2": "{{random}}", "ts_ms": "{{timestamp}}", "ts_sec": "{{timestamp_sec}}"}'

[headers]
Content-Type = "application/json"

Resolved Output Example (Workflow Execution)​

When the above request is executed within a workflow, the placeholders are replaced before transmission:

{
  "json": {
    "random_1": "381406ce",
    "random_2": "381406ce",
    "ts_ms": "1780629151502",
    "ts_sec": "1780629151"
  }
}

(Notice that random_1 and random_2 resolve to the exact same cached value.)

Relative Path-Aware Lookups​

By default, variables extracted from requests are isolated to their request namespace. If your workspace contains nested directory structures, you can query extracted variables from another request file using relative paths (e.g., ../).

How It Works Under the Hood​

  1. Rumour detects a path separator (/ or \) and a dot (.) inside the placeholder name (e.g., {{../auth/login.token}}).
  2. The engine splits the key by the last dot. The prefix before the last dot is parsed as a path, and the suffix after is the variable name.
  3. The engine checks if the path ends with .toml. If not, it automatically appends .toml.
  4. It resolves the path relative to the current request file's directory and canonicalizes it.
  5. Finally, it queries the runtime context using the absolute path of the target file as the namespace (e.g. /workspace/auth/login.toml.token).

Directory Layout Example:​

workspace/
├── auth/
│   └── login.toml        # Extracts 'token'
└── users/
    └── get_user.toml     # References token from login.toml

Auth Request (auth/login.toml):​

name = "login"

[request]
method = "POST"
url = "{{base_url}}/post"

[body]
type = "json"
raw = '{"access_token": "token_xyz"}'

[extract]
token = "json.access_token"

Resource Request (users/get_user.toml):​

To use the extracted token from login.toml relative to the users folder, reference it using relative pathing:

name = "get_user"

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

[headers]
Authorization = "Bearer {{../auth/login.token}}"

Resolved Output Example​

When running the resource request get_user.toml, the engine evaluates the path-aware lookup and transmits the resolved header:

{
  "headers": {
    "Authorization": "Bearer token_xyz"
  }
}
note

The .toml file extension is optional inside the path placeholder. Rumour automatically resolves ../auth/login to ../auth/login.toml relative to the current request folder.

Administrative Token Context Promotion​

To simplify authorization templates for admin endpoints, Rumour contains a built-in promotion rule that redirects the resolution of accessToken to an administrative token if the request is run in an admin context.

Promotion Trigger​

A request is flagged as an admin context if:

  1. The file path or node ID contains the substring "admin" (case-insensitive).
  2. The URL route contains any segment matching the following administrative keywords (case-insensitive):
    • "admin"
    • "approve"
    • "review"
    • "publish"

Promotion Resolution Logic​

When the engine resolves the variable accessToken (exact casing) inside an admin request context, it automatically intercepts the resolution and replaces it with one of the following variables defined in your environment files:

  1. adminaccessToken (all lowercase token)
  2. admin_accessToken (case-sensitive camelCase with underscore separator)
warning

The promotion lookups are case-sensitive. Defining the environment variable as adminAccessToken (capital T with no underscore separator) will not be matched by the engine during admin variable promotion.

Example Request (05_admin_request.toml):​

name = "admin_request"

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

[headers]
# Resolves to the value of 'adminaccessToken' or 'admin_accessToken' automatically
Authorization = "Bearer {{accessToken}}"

Resolved Output Example​

Given an environment configuration containing:

adminaccessToken = "super_secret_admin_token"

Running the 05_admin_request.toml file (flagged as an admin context because of the "admin" in the filename) resolves the headers to:

{
  "headers": {
    "Authorization": "Bearer super_secret_admin_token"
  }
}

(Without admin promotion context, this request would fail due to the undefined accessToken variable.)