Request matchers¶
A Request Matcher is used to define the desired value for a specific request field when matching against incoming requests. Given a matcher value and string to match, each matcher will transform and compare the values in a different way.
Exact matcher¶
Evaluates the equality of the matcher value and the string to match. There are no transformations. This is the default Request Matcher type which is set by Hoverfly when requests and responses are captured.
Example¶
"matcher": "exact"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| docs.hoverfly.io | docs.hoverfly.io | |
| specto.io | docs.hoverfly.io | |
Glob matcher¶
Allows wildcard matching (similar to BASH) using the * character.
Example¶
"matcher": "glob"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| docs.hoverfly.io | *.hoverfly.io | |
| docs.specto.io | *.hoverfly.io | |
| docs.hoverfly.io | h*verfly.* | |
| hooverfly.com | h*verfly.* | |
Regex matcher¶
Parses the matcher value as a regular expression which is then executed against the string to match. This will pass only if the regular expression successfully returns a result.
Example¶
"matcher": "regex"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| docs.hoverfly.io | (\\Ad) | |
| hoverfly.io | (\\Ad) | |
| docs.hoverfly.io | (.*).(.*).(io|com|biz) | |
| buy.stuff.biz | (.*).(.*).(io|com|biz) | |
XML matcher¶
Transforms both the matcher value and string to match into XML objects and then evaluates their equality.
Example¶
"matcher": "xml"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| <?xml version="1.0" encoding="UTF-8"?> <document type="book"> Hoverfly Documentation </document> | <?xml version="1.0" encoding="UTF-8"?> <document type="book"> Hoverfly Documentation </document> | |
| <?xml version="1.0" encoding="UTF-8"?> <documents type="book"> <document type="book"> Hoverfly Documentation </document> </document> | <?xml version="1.0" encoding="UTF-8"?> <document type="book"> Hoverfly Documentation </document> | |
XPath matcher¶
Parses the matcher value as an XPath expression, transforms the string to match into an XML object and then executes the expression against it. This will pass only if the expression successfully returns a result.
Example¶
"matcher": "xpath"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| <?xml version="1.0" encoding="UTF-8"?> <documents> <document> Hoverfly Documentation </document> </documents> | /documents | |
| <?xml version="1.0" encoding="UTF-8"?> <document> Hoverfly Documentation </document> | /documents | |
| <?xml version="1.0" encoding="UTF-8"?> <documents> <document type="book"> Hoverfly Documentation </document> </documents> | /documents/document[2] | |
| <?xml version="1.0" encoding="UTF-8"?> <documents type="book"> <document> Someone Else's Documentation </document> <document> Hoverfly Documentation </document> </documents> | /documents/document[2] | |
JSON matcher¶
Transforms both the matcher value and string to match into JSON objects and then evaluates their equality.
Example¶
"matcher": "json"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| { "objects": [ { "name": "Object 1", "set": true },{ "name": "Object 2", "set": false, "age": 400 }] } | { "objects": [ { "name": "Object 1", "set": true },{ "name": "Object 2", "set": false, "age": 400 }] } | |
| { "objects": [ { "name": "Object 1", "set": true }] } | { "objects": [ { "name": "Object 1", "set": true },{ "name": "Object 2", "set": false, "age": 400 }] } | |
JSON partial matcher¶
Unlike a JSON matcher which does the full matching of two JSON documents, this matcher evaluates if the matcher value is a subset of the incoming JSON document. The matcher ignores any absent fields and lets you match only the part of JSON document you care about.
Example¶
"matcher": "jsonPartial"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| { "objects": [ { "name": "Object 1", },{ "name": "Object 2", "set": false, "age": 400 }] } | { "objects": [ { "name": "Object 1" },{ "name": "Object 2" }] } | |
| { "objects": [ { "name": "Object 1", },{ "name": "Object 2", "set": false, "age": 400 }] } | { "name": "Object 2", "set": false, "age": 400 } | |
| { "objects": [ { "name": "Object 1", "set": true }] } | { "objects": [ { "name": "Object 1", "set": true },{ "name": "Object 2", "set": false, "age": 400 }] } | |
JSONPath matcher¶
Parses the matcher value as a JSONPath expression, transforms the string to match into a JSON object and then executes the expression against it. This will pass only if the expression successfully returns a result.
Example¶
"matcher": "jsonpath"
"value": "?"
| String to match | Matcher value | Match |
|---|---|---|
| { "objects": [ { "name": "Object 1", "set": true }] } | $.objects | |
| { "name": "Object 1", "set": true } | $.objects | |
| { "objects": [ { "name": "Object 1", "set": true }] } | $.objects[1].name | |
| { "objects": [ { "name": "Object 1", "set": true }, { "name": "Object 2", "set": false }] } | $.objects[1].name | |
Form matcher¶
Matches form data posted in the request payload with content type application/x-www-form-urlencoded.
You can match only the form params you are interested in regardless of the order. You can also leverage
jwt or jsonpath matchers if your form params contains JWT tokens or JSON document.
Please note that this matcher only works for body field.
Example¶
"matcher": "form",
"value": {
"grant_type": [
{
"matcher": "exact",
"value": "authorization_code"
}
],
"client_assertion": [
{
"matcher": "jwt",
"value": "{\"header\":{\"alg\":\"HS256\"},\"payload\":{\"sub\":\"1234567890\",\"name\":\"John Doe\"}}"
}
]
}
Array matcher¶
Matches an array contains exactly the given values and nothing else. This can be used to match multi-value query param or header in the request data.
The following configuration options are available to change the behaviour of the matcher:
ignoreOrder - ignore the order of the values.
ignoreUnknown - ignore any extra values.
ignoreOccurrences - ignore any duplicated values.
Example¶
"matcher": "array",
"config": {
"ignoreUnknown": "<true/false>",
"ignoreOrder": "<true/false>",
"ignoreOccurrences": "<true/false>"
},
"value": [
"access:vod",
"order:latest",
"profile:vd"
]
JWT matcher¶
This matcher is primarily used for matching JWT tokens. This matcher converts base64 encoded JWT to JSON document ({“header”: {}, “payload”: “”}) and does JSON partial match with the matcher value.
Matcher value contains only keys that they want to match in JWT.
Example¶
"matcher": "jwt"
"value": "{\"header\":{\"alg\":\"HS256\"},\"payload\":{\"sub\":\"1234567890\",\"name\":\"John Doe\"}}"
Matcher chaining¶
Matcher chaining allows you to pass a matched value into another matcher to do further matching.
It typically removes the stress of composing and testing complex expressions and make matchers more readable.
For an example, one can use JSONPath to get a JSON node, then use another matcher to match the JSON node value as follows.
Example¶
"matcher": "jsonpath",
"value": "$.user.id",
"doMatch": {
"matcher": "exact",
"value": "1"
}