Response Body Validation
Welcome to the Response Body Validation documentation!
When testing APIs, the response body is often the most critical payload to verify. In Rumour's execution engine, there are three distinct ways to assert against the response body, depending entirely on the format and structure of the data returned by your server.
This guide explores body_contains for raw text, and explicitly maps out the other advanced body validation tools ([assert.json] and schema) available in the ecosystem.
1. Raw Substring Match (body_contains)
If your API returns plain text, HTML, XML, or if you simply want to do a fast "dumb" string search across a massive JSON payload without parsing it, the body_contains assertion is the only tool you need.
It performs a high-performance, raw memory scan of the entire response body string. It is the only assertion in Rumour designed specifically for unstructured raw body text.
Example: Successful Match
Let's test an endpoint and assert that it contains the text "Test User".
body_contains.toml
name = "body_contains_demo"
[request]
method = "GET"
url = "{{base_url}}/users/1"
[assert]
status = 200
body_contains = "Test User"
Output (Success)
When the server responds with a body containing "Test User", the test passes. Running this node with the verbose (-v) flag produces a detailed trace:
rumour run ./body_contains.toml -v
GET http://localhost:4000/api/v2/users/1
URL: http://localhost:4000/api/v2/users/1
✓ SUCCESS: /home/bugsfounder/workspace/testing/assertion_examples/body_contains.toml (1ms)
✓ ./body_contains.toml → 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/assertion_examples/body_contains.toml [200] [2ms]
Let's break down what just happened:
- The Live Action: Rumour immediately fires off the request and streams the output. Because it found the exact text
"Test User"hidden somewhere in the raw response, it prints a green✓ SUCCESS. - The Big Picture: In the final
RUMOUR EXECUTION REPORT, you see that the single request passed flawlessly with a100.0%success rate. - The Roll Call: The successful files are cleanly listed at the bottom so you can verify exactly which endpoints are behaving properly.
Example: Failing Match
If we assert that the body contains a string that doesn't exist, the request will fail.
body_contains_fail.toml
name = "body_contains_fail_demo"
[request]
method = "GET"
url = "{{base_url}}/users/1"
[assert]
status = 200
body_contains = "Super Admin"
Output (Failure)
When we run the test, the body_contains validation fails and gives a clear error message.
✗ FAILED: /home/bugsfounder/workspace/testing/assertion_examples/body_contains_fail.toml (1ms) - Body Contains: Body does not contain 'Super Admin'
✗ ./body_contains_fail.toml → FAIL (0 Pass, 1 Fail, 0 Skip)
╭──────────────────────────────────────────────────────────────────────────╮
│ RUMOUR EXECUTION REPORT │
├──────────────────────────────────────────────────────────────────────────┤
│ Total Requests: 1 │
│ Successful: 0 │
│ Failed: 1 │
│ Skipped: 0 │
│ Success Rate: 0.0% │
│ Total Time: 1510ms │
╰──────────────────────────────────────────────────────────────────────────╯
✗ Failed Requests:
- /home/bugsfounder/workspace/testing/assertion_examples/body_contains_fail.toml: [200]
Reason: Body Contains: Body does not contain 'Super Admin'
Let's break down what just happened:
- The Instant Failure: Rumour downloaded the response body, scanned it, and couldn't find the phrase
"Super Admin". It immediately flags the execution as✗ FAILED. - The Post-Mortem: If you look at the
✗ Failed Requestsblock in the final report, Rumour tells you in plain English exactly what went wrong:Body does not contain 'Super Admin'. This saves you from having to manually open up the API and dig through the payload yourself!
2. Structured Body Validation ([assert.json])
While body_contains is the only raw-string assertion, you should never use it to validate complex JSON payloads. For instance, if you search for body_contains = "admin", it might falsely pass because of a comment or a completely unrelated field.
For precise validation of JSON response bodies, Rumour provides the dedicated [assert.json] block. This engine parses the response body into memory and allows you to target specific nodes using dot notation.
Example: Granular JSON Assertion
[assert.json."data.users.0.role"]
equal = "admin"
[assert.json."data.success"]
equal = true
For full, in-depth documentation on the dozens of operators (like greater_than, regex, exists) available for JSON bodies, read the JSON Path Assertions Guide.
3. Contract Body Validation (schema)
If you want to assert the entire structural integrity of a response body at once (e.g., ensuring no unexpected fields are returned, verifying data types, and checking required parameters), Rumour supports Draft-07 JSON Schema validation against the response body.
Example: Schema Assertion
[assert]
schema = "./schemas/user_contract.json"
For full, in-depth documentation on mapping and caching schema files, read the JSON Schema Validation Guide.
Summary: Which Body Assertion to Use?
body_contains: Use for unstructured data (HTML/XML/Text) or when you need a blazing fast substring match across the entire payload.[assert.json]: Use when the response body is JSON and you need to mathematically or logically validate a specific leaf node (e.g., verifying a price is> 100).schema: Use when the response body is JSON and you want to enforce a strict API contract over the entire payload structure.