Variable Extraction

To build end-to-end integration workflows, requests often need to consume outputs produced by previous requests (such as API tokens, resource IDs, or headers). Rumour provides a powerful variable extraction system supporting both explicit path configuration and intelligent implicit auto-extraction.

1. Explicit Extraction Syntax

Explicit extraction rules are defined inside an [extract] block in your request TOML file. They map local variable names to specific parts of the response payload or headers:

[extract]
authToken = "json.access_token"
sessionExpiry = "json.expires_in"
serverHost = "header.host"

In this block, Rumour extracts:

authToken: from the JSON body key json -> access_token nested path.
sessionExpiry: from the JSON body key json -> expires_in nested path.
serverHost: from the HTTP response header Host.

2. Explicit Extraction Selectors

Rumour supports two selector modes: JSON paths and Header fields.

A. JSON Path Selectors

JSON selectors navigate through JSON response bodies using dot-notated paths.

Property Navigation: user.profile.email extracts from:

{
  "user": {
    "profile": {
      "email": "developer@example.com"
    }
  }
}

Array Indexing: You can use numbers in your dot-separated path to access elements inside arrays. For example, users.1.id extracts the id of the second element in the users array.

JSON Selector Evidence (httpbin.org)

Here is a live request (test_json.toml) fetching a structured payload from /json and extracting properties:

# test_json.toml
[request]
method = "GET"
url = "{{base_url}}/json"

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

[extract]
author = "slideshow.author"
second_slide = "slideshow.slides.1.title"

Verifying downstream via test_json_verify.toml:

# test_json_verify.toml
[dependencies]
"./test_json.toml" = ["author", "second_slide"]

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

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
X-Verify-Author = "{{author}}"
X-Verify-Slide = "{{second_slide}}"

Terminal Run Trace:

rumour run extract_example/users/requests/test_json_verify.toml -tv

  GET https://httpbin.org/json
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_json.toml (2621ms)

  GET https://httpbin.org/anything
  Header: User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
  Header: X-Verify-Slide: Overview
  Header: X-Verify-Author: Yours Truly
  URL: https://httpbin.org/anything
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_json_verify.toml (529ms)
    ✓ /home/bugsfounder/workspace/testing/extract_example/users/requests/test_json_verify.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:          3151ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_json.toml  [200] [2621ms]
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_json_verify.toml  [200] [529ms]

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

B. Header Selectors

To extract from HTTP response metadata, prepend the selector path with the header. prefix.

The matching is case-insensitive (e.g., header.Content-Type and header.content-type behave identically).

Header Selector Evidence (httpbin.org)

Here is a live request (test_headers.toml) fetching a custom response header and extracting it:

# test_headers.toml
[request]
method = "GET"
url = "{{base_url}}/response-headers?X-Custom-Server=RumourTestServer"

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

[extract]
custom_server = "header.x-custom-server"
content_type = "header.Content-Type"

Verifying downstream via test_headers_verify.toml:

# test_headers_verify.toml
[dependencies]
"./test_headers.toml" = ["custom_server", "content_type"]

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

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
X-Verify-Server = "{{custom_server}}"
X-Verify-Type = "{{content_type}}"

Terminal Run Trace:

rumour run extract_example/users/requests/test_headers_verify.toml -tv

  GET https://httpbin.org/response-headers?X-Custom-Server=RumourTestServer
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_headers.toml (1583ms)

  GET https://httpbin.org/anything
  Header: User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
  Header: X-Verify-Server: RumourTestServer
  Header: X-Verify-Type: application/json
  URL: https://httpbin.org/anything
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_headers_verify.toml (1198ms)
    ✓ /home/bugsfounder/workspace/testing/extract_example/users/requests/test_headers_verify.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:          2781ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_headers.toml  [200] [1583ms]
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_headers_verify.toml  [200] [1198ms]

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

3. Intelligent Auto-Extraction (Implicit Extraction)

To simplify configurations, Rumour features an implicit auto-extraction engine. When any request completes successfully, Rumour automatically scans the JSON response body for common authentication, identity, and session properties, extracting them even if you have no [extract] block configured.

Pre-Registered Keywords

Rumour normalizes keys (removing casing and separators like _ or -) and matches them against the following categories:

Category	Canonical Variable Name	Recognized Aliases / Patterns
Authentication	`accessToken`	`token`, `access_token`, `auth_token`, `authToken`, `jwt`, `bearer`, `api_key`, `apiKey`, `authorization`, `auth`
Admin Auth	`adminAccessToken`	`admin_token`, `adminAccessToken`, `admin_access_token`, `adminToken`
Refresh Tokens	`refreshToken`	`refresh_token`, `refreshToken`, `refresh`
Identity	`id`	`user_id`, `userId`, `uid`, `uuid`, `account_id`, `accountId`, `guid`
Session	`sessionId`	`session_id`, `sessionId`, `sid`, `session`, `csrf`, `xsrf`, `token_id`, `X-CSRF-TOKEN`, `X-XSRF-TOKEN`
Metadata	`version`, `status`	`v`, `ver`, `version`, `state`, `status`

Namespacing Rules

When a key is implicitly or explicitly extracted from a request (e.g., from login.toml), it is exposed to downstream files in two ways:

Global/Direct Name: Captured as accessToken or id.
Namespaced Name: Prefixed with the file stem of the request, e.g. login.accessToken or login.id. This ensures that downstream files can uniquely select variables if multiple upstream requests extract the same key.

Intelligent Auto-Extraction Evidence (httpbin.org)

Here is a live request (test_auto.toml) that performs a JSON POST with standard identifier keys inside the request body without declaring an [extract] block:

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

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

[body]
type = "json"
raw = '{"token": "intelligent_token_123", "user_id": "usr_999", "session_id": "sess_888"}'

Verifying downstream via test_auto_verify.toml:

# test_auto_verify.toml
[dependencies]
"./test_auto.toml" = ["accessToken", "id", "sessionId"]

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

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
X-Verify-Token-Global = "{{accessToken}}"
X-Verify-ID-Global = "{{id}}"
X-Verify-Session-Global = "{{sessionId}}"

Terminal Run Trace:

rumour run extract_example/users/requests/test_auto_verify.toml -tv

  POST https://httpbin.org/post
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_auto.toml (1165ms)

  GET https://httpbin.org/anything
  Header: User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
  Header: X-Verify-Token-Global: intelligent_token_123
  Header: X-Verify-ID-Global: usr_999
  Header: X-Verify-Session-Global: sess_888
  URL: https://httpbin.org/anything
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_auto_verify.toml (1183ms)
    ✓ /home/bugsfounder/workspace/testing/extract_example/users/requests/test_auto_verify.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:          2349ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_auto.toml  [200] [1165ms]
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_auto_verify.toml  [200] [1183ms]

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

4. Dataset Example & Directory Structure

We use a workspace dataset extract_example/ to demonstrate variable extraction. The folder layout is organized as follows:

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

5. File Configurations

Here are the complete contents for the files in the workspace:

A. Workspace Level

`workspace.env.toml`

Defines base variables for the workspace suite.

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

`extract_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 = [
    "auth/auth.suite.toml",
    "users/users.suite.toml"
]

B. `auth` Collection

`auth/requests/login.toml`

Sends login parameters, explicitly extracting the server software header and the echoed token value.

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

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

[extract]
token = "json.token"
server_software = "header.server"

C. `users` Collection

`users/requests/get_users.toml`

Declares a dependency on login.toml and references the extracted variables.

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

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

[headers]
Authorization = "Bearer {{../../auth/requests/login.token}}"
X-Server-Target = "{{../../auth/requests/login.server_software}}"

[variables]
client_name = "RumourTestAgent/2.0"

6. Execution Command & Output Trace

When executing get_users.toml, Rumour parses dependencies, runs login.toml first, extracts the variables, and substitutes them into get_users.toml.

Command

rumour run extract_example/users/requests/get_users.toml -tv

Output Trace

  POST https://httpbin.org/post
  URL: https://httpbin.org/post
  Body (json): {"username": "admin", "token": "session_secret_xyz123"}
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/auth/requests/login.toml (1043ms)
  
  GET https://httpbin.org/headers
  Header: Authorization: Bearer session_secret_xyz123
  Header: X-Server-Target: gunicorn/19.9.0
  URL: https://httpbin.org/headers
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/get_users.toml (249ms)
    ✓ extract_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:          1296ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/extract_example/auth/requests/login.toml  [200] [1044ms]
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/get_users.toml  [200] [251ms]

7. Referencing Extracted Variables

You can access extracted variables in downstream requests using two distinct syntaxes:

Option 1: Direct Dotted Relative Path

Access the variable by routing directly to the dependency's relative file location:

[headers]
Authorization = "Bearer {{../../auth/requests/login.token}}"
X-Server-Target = "{{../../auth/requests/login.server_software}}"

Option 2: Short Local Variable Mapping (Recommended)

You can declare a dependency mapping in your [dependencies] block to bind the relative request's exported value to a simple local variable name:

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

[headers]
Authorization = "Bearer {{token}}"

Why Local Mapping is Preferred

Declaring explicit dependency maps at the bottom or top of your request file namespaces your variables cleanly, making them easier to read and protecting them from collision conflicts if multiple upstream requests extract identically named variables.

8. Idempotent Fallback Handling

To support self-healing scenarios (such as resolving 409 Conflict errors during resource creation), Rumour features an idempotence fallback.

If a request fails or returns a response without the extracted field, Rumour falls back to the current local variable value of that name already stored in the execution scope instead of crashing. This allows subsequent assertions and healers to proceed using pre-existing values.

Fallback Safety Evidence (httpbin.org)

Here is a live request (test_fallback.toml) defining a local variable, attempting to extract a non-existent key, and demonstrating the fallback safety:

# test_fallback.toml
[request]
method = "GET"
url = "{{base_url}}/json"

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

[variables]
fallback_val = "pre_defined_value"

[extract]
fallback_val = "slideshow.non_existent_key"

Verifying downstream via test_fallback_verify.toml:

# test_fallback_verify.toml
[dependencies]
"./test_fallback.toml" = ["fallback_val"]

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

[headers]
User-Agent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
X-Verify-Fallback = "{{fallback_val}}"

Terminal Run Trace:

rumour run extract_example/users/requests/test_fallback_verify.toml -tv

  GET https://httpbin.org/json
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_fallback.toml (3368ms)

  GET https://httpbin.org/anything
  Header: User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36
  Header: X-Verify-Fallback: pre_defined_value
  URL: https://httpbin.org/anything
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/extract_example/users/requests/test_fallback_verify.toml (738ms)
    ✓ /home/bugsfounder/workspace/testing/extract_example/users/requests/test_fallback_verify.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:          4107ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_fallback.toml  [200] [3368ms]
  - /home/bugsfounder/workspace/testing/extract_example/users/requests/test_fallback_verify.toml  [200] [738ms]

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

1. Explicit Extraction Syntax​

2. Explicit Extraction Selectors​

A. JSON Path Selectors​

JSON Selector Evidence (httpbin.org)​

B. Header Selectors​

Header Selector Evidence (httpbin.org)​

3. Intelligent Auto-Extraction (Implicit Extraction)​

Pre-Registered Keywords​

Namespacing Rules​

Intelligent Auto-Extraction Evidence (httpbin.org)​

4. Dataset Example & Directory Structure​

5. File Configurations​

A. Workspace Level​

workspace.env.toml​

extract_example.suite.toml​

B. auth Collection​

auth/requests/login.toml​

C. users Collection​

users/requests/get_users.toml​

6. Execution Command & Output Trace​

Command​

Output Trace​

7. Referencing Extracted Variables​

Option 1: Direct Dotted Relative Path​

Option 2: Short Local Variable Mapping (Recommended)​

8. Idempotent Fallback Handling​

Fallback Safety Evidence (httpbin.org)​

1. Explicit Extraction Syntax

2. Explicit Extraction Selectors

A. JSON Path Selectors

JSON Selector Evidence (httpbin.org)

B. Header Selectors

Header Selector Evidence (httpbin.org)

3. Intelligent Auto-Extraction (Implicit Extraction)

Pre-Registered Keywords

Namespacing Rules

Intelligent Auto-Extraction Evidence (httpbin.org)

4. Dataset Example & Directory Structure

5. File Configurations

A. Workspace Level

`workspace.env.toml`

`extract_example.suite.toml`

B. `auth` Collection

`auth/requests/login.toml`

C. `users` Collection

`users/requests/get_users.toml`

6. Execution Command & Output Trace

Command

Output Trace

7. Referencing Extracted Variables

Option 1: Direct Dotted Relative Path

Option 2: Short Local Variable Mapping (Recommended)

8. Idempotent Fallback Handling

Fallback Safety Evidence (httpbin.org)