.. _request_matchers: 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 """"""" .. code:: json "matcher": "exact" "value": "?" .. raw:: html
String to match Matcher value Match
docs.hoverfly.io docs.hoverfly.io
specto.io docs.hoverfly.io
| | Negation matcher ------------- The opposite of the Exact matcher. This matcher will evaluate to true if the values being compared are not the same. Example """"""" .. code:: json "matcher": "negate" "value": "?" .. raw:: html
String to match Matcher value Match
cloud.hoverfly.io docs.hoverfly.io
cloud.hoverfly.io
cloud.hoverfly.io
cloud.hoverfly.io cloud.hoverfly.io
| | Glob matcher ------------ Allows wildcard matching (similar to BASH) using the ``*`` character. Example """"""" .. code:: json "matcher": "glob" "value": "?" .. raw:: html
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 """"""" .. code:: json "matcher": "regex" "value": "?" .. raw:: html
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 """"""" .. code:: json "matcher": "xml" "value": "?" .. raw:: html
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 """"""" .. code:: json "matcher": "xpath" "value": "?" .. raw:: html
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 """"""" .. code:: json "matcher": "json" "value": "?" .. raw:: html
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 """"""" .. code:: json "matcher": "jsonPartial" "value": "?" .. raw:: html
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 """"""" .. code:: json "matcher": "jsonpath" "value": "?" .. raw:: html
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 """"""" .. code:: json "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 """"""" .. code:: json "matcher": "array", "config": { "ignoreUnknown": "", "ignoreOrder": "", "ignoreOccurrences": "" }, "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 """"""" .. code:: json "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 example, one can use JSONPath to get a JSON node, then use another matcher to match the JSON node value as follows. Example """"""" .. code:: json "matcher": "jsonpath", "value": "$.user.id", "doMatch": { "matcher": "exact", "value": "1" } JWT JSONPath matcher -------------------- Parses the matcher value as a JSONPath expression and executes it against the decoded JWT header/payload. The JWT is transformed into a JSON document of the form ``{"header": {...}, "payload": {...}}`` (signature is not verified). When using a shorthand path like ``$.user_name``, it targets ``$.payload.user_name`` by default; you can explicitly reference ``$.header.*`` or ``$.payload.*``. This matcher is especially useful with matcher chaining, where the extracted value is passed to a second matcher (e.g., ``regex``) for further evaluation. Example """""" .. code:: json "headers": { "Authorization": [ { "matcher": "jwtjsonpath", "value": "$.user_name", "doMatch": { "matcher": "regex", "value": "stuart.kelly" } } ] }