Hoverfly simulates APIs by matching incoming requests from the client to stored requests. Stored requests have an associated stored response which is returned to the client if the match is successful.
The matching logic that Hoverfly uses to compare incoming requests with stored requests can be configured using Request Matchers.
When Hoverfly captures a request, it creates a Request Matcher for each field in the request. A Request Matcher consists of the request field name, the type of match which will be used to compare the field in the incoming request to the field in the stored request, and the request field value.
By default, Hoverfly will set the type of match to exact for each field.
There are many types of Request Matcher. Please refer to request_matchers for a list of the types available, and examples of how to use them.
There alse are two different matching strategies: strongest match (default) and first match (legacy). Please refer to matching for more information.
An example Request Matcher Set might look like this:
| Field | Matcher Type | Value |
|---|---|---|
| scheme | exact | "https" |
| method | exact | "GET" |
| destination | exact | "docs.hoverfly.io" |
| path | exact | "/pages/keyconcepts/templates.html" |
| query | exact | "query=true" |
| body | exact | "" |
| headers | exact |
In the Hoverfly simulation JSON file, this Request Matcher Set would be represented like this:
../../simulations/basic-simulation.json
View entire simulation file <basic_simulation>
The matching logic that Hoverfly uses to compare an incoming request to a stored request can be changed by editing the Request Matchers in the simulation JSON file.
It is not necessary to have a Request Matcher for every request field. By omitting Request Matchers, it is possible to implement partial matching - meaning that Hoverfly will return one stored response for multiple incoming requests.
For example, this Request Matcher will match any incoming request to the docs.hoverfly.io destination:
../../simulations/all-matchers-simulation.json
View entire simulation file <all_matchers_simulation>
In the example below, the globMatch Request Matcher type is used to match any subdomain of hoverfly.io:
../../simulations/all-matchers-simulation.json
View entire simulation file <all_matchers_simulation>
It is also possible to use more than one Request Matcher for each field.
In the example below, a regexMatch and a globMatch are used on the destination field.
This will match on any subdomain of hoverfly.io which begins with the letter d. This means that incoming requests to docs.hoverfly.io and dogs.hoverfly.io will be matched, but requests to cats.hoverfly.io will not be matched.
../../simulations/all-matchers-simulation.json
View entire simulation file <all_matchers_simulation>
There are many types of Request Matcher. Please refer to request_matchers for a list of the types available, and examples of how to use them.
For a practical example of how to use a Request Matcher, please refer to loosematching in the tutorials section.
There alse are two different matching strategies: strongest match (default) and first match (legacy). Please refer to matching for more information.
Each Request Matcher Set has a response associated with is. If the request match is successful, Hoverfly will return the response to the client.
../../simulations/basic-simulation.json
View entire simulation file <basic_simulation>
Editing the fields in response, combined with editing the Request Matcher set, makes it possible to configure complex request/response logic.
JSON is a text-based file format so it has no intrinsic support for binary data. Therefore if Hoverfly a response body contains binary data (images, gzipped, etc), the response body will be base64 encoded and the encodedBody field set to true.
../../simulations/basic-encoded-simulation.json
View entire simulation file <basic_encoded_simulation>