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