Regex Field Inferences
Welcome to the Regex Field Inferences documentation!
When standard exact match (equal) or substring match (contains) assertions are not powerful enough, Rumour allows you to use Regular Expressions (regex) for complex string validation. This is particularly useful for verifying formats like emails, UUIDs, dates, or custom access tokens.
The regex engine uses standard regular expression syntax, which is highly compatible with PCRE (Perl Compatible Regular Expressions).
Structuring Regex Assertions in TOML
Because TOML is a highly flexible configuration language, Rumour supports multiple ways to structure your regex assertions. The best syntax to use depends on whether you are trying to chain multiple assertions compactly, or if you are writing a very long, complex regex pattern.
You can apply the regex constraint to specific fields in a JSON body (using [assert.json]) or specific Response Headers (using [assert.headers]).
Method 1: Inline Table Syntax (Compact & Chained)
The Inline Table syntax is the recommended approach for most validations. It allows you to define the regex compactly on a single line.
More importantly, it allows you to chain multiple assertions together for the same field (e.g., verifying a string matches a regex and contains a specific substring).
regex_inline_demo.toml
name = "regex_inline_demo"
[request]
method = "GET"
url = "{{base_url}}/users/1"
[assert]
status = 200
[assert.json]
"email" = { regex = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$", contains = "@test.com" }
Output (Success)
When the server responds with a valid email (e.g., "user@test.com"), both the regex and contains constraints pass flawlessly:
rumour run ./regex_inline_demo.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/regex_inline_pass.toml (1ms)
✓ ./regex_inline_demo.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: 1ms │
╰──────────────────────────────────────────────────────────────────────────╯
✓ Successful Requests:
- /home/bugsfounder/workspace/testing/assertion_examples/regex_inline_pass.toml [200] [1ms]
Method 2: Dotted Subtable Syntax (Detailed)
If your regex pattern is extremely long, or if you simply prefer a more vertical, descriptive layout, you can use the Dotted Subtable syntax. This pulls the target field directly into the TOML table header, allowing you to define the regex property on its own dedicated line.
regex_dotted_demo.toml
name = "regex_dotted_demo"
[request]
method = "GET"
url = "{{base_url}}/users/1"
[assert]
status = 200
[assert.json."email"]
regex = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
Output (Success)
rumour run ./regex_dotted_demo.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/regex_dotted_pass.toml (1ms)
✓ ./regex_dotted_demo.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 │
╰──────────────────────────────────────────────────────────────────────────╯
Type Restrictions & Mismatches
The regex assertion strictly requires the target value to be a string. If the regex doesn't match, or if the target field is a number, boolean, or array, the assertion will fail immediately.
Let's assert that the id field (which is an integer) is a string of letters to demonstrate the failure intelligence.
regex_demo_fail.toml
name = "regex_demo_fail"
[request]
method = "GET"
url = "{{base_url}}/users/1"
[assert]
status = 200
[assert.json]
"id" = { regex = "^[a-zA-Z]+$" }
Output (Failure)
When we run the test, the regex validation catches the type mismatch and stops execution:
✗ FAILED: /home/bugsfounder/workspace/testing/assertion_examples/regex_demo_fail.toml (1ms) - JSON Path: id: Value is not a string or not found (expected regex match)
✗ ./regex_demo_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: 1508ms │
╰──────────────────────────────────────────────────────────────────────────╯
✗ Failed Requests:
- /home/bugsfounder/workspace/testing/assertion_examples/regex_demo_fail.toml: [200]
Reason: JSON Path: id: Value is not a string or not found (expected regex match)
Let's break down what just happened:
- The Type Mismatch: We tried to run a string regex on the
idfield, but the server returned a number. Rumour's regex engine strictly requires strings, so it instantly threw an✗ FAILEDerror. - The Clear Error: In the
Reason:block, Rumour explains the exact problem:Value is not a string or not found. This saves you from wondering if your regex pattern was just written incorrectly!
Regex on Headers
You can perfectly map these exact same TOML structural syntaxes to validate response headers (like Content-Type structures or Cache-Control directives).
Inline Table Syntax for Headers:
[assert.headers]
"content-type" = { regex = "^application\\/json.*" }
"cache-control" = { regex = "max-age=\\d+" }
Dotted Subtable Syntax for Headers:
[assert.headers."content-type"]
regex = "^application\\/json.*"
[assert.headers."cache-control"]
regex = "max-age=\\d+"
In TOML strings, remember to escape backslashes twice (\\) when writing regex patterns (e.g., \\d+ instead of \d+).