Skip to main content

Core Assertions

The [assert] block allows you to define constraints on incoming HTTP responses. If any assertion fails, the request is marked as failed, and retries or self-healing triggers will activate if configured.

1. Syntax & Configuration​

Core assertions validate general metadata about the response, such as HTTP status codes, execution duration, and schema layout:

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

[assert]
# Exact status code validation
status = 200

# Substring presence in raw response body
body_contains = "success"

# Performance SLA limit (duration in milliseconds)
duration = 1000

2. Assertion Fields & Behaviors​

Rumour supports five key assertions in the [assert] block:

Status Code (status)​

Asserts that the HTTP status matches the exact integer code specified.

  • Syntax: status = <integer>
  • Example: status = 200

Status Range (status_range)​

Asserts that the HTTP status falls within a range, or matches one of a comma-separated list of status codes.

  • Syntax formats:
    • status_range = "<min>-<max>": Inclusive status code range. Example: "200-299" checks if status is between 200 and 299 inclusive.
    • status_range = "<status1>,<status2>,...": Exact matching list of acceptable codes. Example: "200,201,204".
    • status_range = "<status>": Single status string fallback. Example: "200".
Status Precedence

If both status and status_range are defined in the same [assert] block, the exact status assertion takes precedence, and status_range will be ignored.

Response Duration (duration)​

Asserts that the total network roundtrip transport duration is less than or equal to the specified limit in milliseconds.

  • Syntax: duration = <integer>
  • Example: duration = 500 (fails if the response takes strictly greater than 500ms).

Substring Search (body_contains)​

Asserts that the raw response body contains the specified substring.

  • Syntax: body_contains = "<string>"
  • Example: body_contains = "session_secret"

JSON Schema Validation (schema)​

Validates that the JSON response body conforms to a Draft 7 JSON Schema. Rumour supports two ways to specify the schema:

  1. Path-Based Schema: A path to a local JSON file containing the schema. The path is evaluated relative to the request TOML file. 
    [assert]
    schema = "./schemas/user.schema.json"
  2. Inline Schema: A multi-line string defining the JSON schema directly in the request TOML file. Rumour treats any schema value that starts with { or [ or contains a newline as an inline schema. 
    [assert]
    schema = """
    {
      "type": "object",
      "properties": {
        "slideshow": { "type": "object" }
      },
      "required": ["slideshow"]
    }
    """
Schema Strictness & Additive Constraints

By default, JSON Schema Draft 7 operates on an additive constraint system. It is highly permissive.

  • If you define a field in "properties" but do not include it in the "required" array, the field is considered optional. If it is missing from the API response, the schema validation will still pass.
  • If the API response contains additional properties that are not defined in your schema, the validation will still pass.

To strictly enforce your schema and trigger failures on unexpected structures:

  1. Enforce required fields: Explicitly list all mandatory keys in the "required" array.
  2. Forbid extra fields: Set "additionalProperties": false at the object level to fail validation if the response returns undocumented properties.

3. Schema Assertion Examples (httpbin.org)​

To demonstrate how schema assertions behave during runs, consider the following files configured against httpbin.org.

A. Path-Based Schema Case​

JSON Schema file (user.schema.json):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "slideshow": {
      "type": "object",
      "properties": {
        "author": { "type": "string" },
        "date": { "type": "string" },
        "title": { "type": "string" },
        "slides": { "type": "array" }
      },
      "required": ["author", "date", "title", "slides"]
    }
  },
  "required": ["slideshow"]
}

Request file (test_schema_file.toml):

# test_schema_file.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"

[assert]
status = 200
schema = "./user.schema.json"

Run Trace​

  GET https://httpbin.org/json
  URL: https://httpbin.org/json
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_file.toml (1177ms)
    ✓ /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_file.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:          1180ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_file.toml  [200] [1180ms]

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

B. Inline Schema Case​

Request file (test_schema_inline.toml):

# test_schema_inline.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"

[assert]
status = 200
schema = """
{
  "type": "object",
  "properties": {
    "slideshow": {
      "type": "object",
      "properties": {
        "author": { "type": "string" }
      },
      "required": ["author"]
    }
  },
  "required": ["slideshow"]
}
"""

Run Trace​

  GET https://httpbin.org/json
  URL: https://httpbin.org/json
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_inline.toml (1171ms)
    ✓ /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_inline.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:          1176ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_inline.toml  [200] [1176ms]

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

C. Advanced: Conditional Validation (if/then/else)​

Because Rumour natively uses the JSON Schema Draft 7 engine, you can use powerful conditional logic directly in your schemas without any extra configuration.

1. Path-Based Schema Case​

JSON Schema file (conditional.schema.json):

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "slideshow": {
      "type": "object",
      "properties": {
        "author": { "type": "string" }
      }
    }
  },
  "if": {
    "properties": {
      "slideshow": {
        "properties": { "author": { "const": "Yours Truly" } }
      }
    }
  },
  "then": {
    "properties": {
      "slideshow": { "required": ["title"] }
    }
  },
  "else": {
    "properties": {
      "slideshow": { "required": ["missing_property"] }
    }
  }
}

Request file (test_schema_conditional_file.toml):

# test_schema_conditional_file.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"

[assert]
status = 200
schema = "./conditional.schema.json"
Run Trace​
  GET https://httpbin.org/json
  URL: https://httpbin.org/json
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_conditional_file.toml (2368ms)
    ✓ /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_conditional_file.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:          2372ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_conditional_file.toml  [200] [2372ms]

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

2. Inline Schema Case​

Request file (test_schema_conditional.toml):

# test_schema_conditional.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"

[assert]
status = 200
schema = """
{
  "type": "object",
  "properties": {
    "slideshow": {
      "type": "object",
      "properties": {
        "author": { "type": "string" }
      }
    }
  },
  "if": {
    "properties": {
      "slideshow": {
        "properties": { "author": { "const": "Yours Truly" } }
      }
    }
  },
  "then": {
    "properties": {
      "slideshow": { "required": ["title"] }
    }
  },
  "else": {
    "properties": {
      "slideshow": { "required": ["missing_property"] }
    }
  }
}
"""
Run Trace​
  GET https://httpbin.org/json
  URL: https://httpbin.org/json
  ✓ SUCCESS: /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_conditional.toml (3182ms)
    ✓ /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_conditional.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:          3188ms                                              │
╰──────────────────────────────────────────────────────────────────────────╯

✓ Successful Requests:
  - /home/bugsfounder/workspace/testing/assert_example/users/requests/test_schema_conditional.toml  [200] [3188ms]

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

D. Failing Schema Validation Output​

When a response body does not match the schema, the validation results report the exact structural errors:

  ✗ FAILED: test_schema_invalid.toml (887ms) - JSON Schema: Schema validation failed: "slideshow" is a required property

4. Advanced Assertions​

For validating specific elements inside headers or nested JSON payloads, please refer to the dedicated guides: