Request Responses Pairs¶
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.
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.
See also
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 strategies 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:
1 "request": {
2 "path": [
3 {
4 "matcher": "exact",
5 "value": "/pages/keyconcepts/templates.html"
6 }
7 ],
8 "method": [
9 {
10 "matcher": "exact",
11 "value": "GET"
12 }
13 ],
14 "destination": [
15 {
16 "matcher": "exact",
17 "value": "docs.hoverfly.io"
18 }
19 ],
20 "scheme": [
21 {
22 "matcher": "exact",
23 "value": "http"
24 }
25 ],
26 "body": [
27 {
28 "matcher": "exact",
29 "value": ""
30 }
31 ],
32 "query": {
33 "query": [
34 {
35 "matcher": "exact",
36 "value": "true"
37 }
38 ]
39 }
40 },
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:
1 "destination": [
2 {
3 "matcher": "exact",
4 "value": "docs.hoverfly.io"
5 }
6 ]
In the example below, the globMatch
Request Matcher type is used to match any subdomain of hoverfly.io
:
1 "destination": [
2 {
3 "matcher": "glob",
4 "value": "*.hoverfly.io"
5 }
6 ]
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.
1 "destination": [
2 {
3 "matcher": "glob",
4 "value": "*.hoverfly.io"
5 },
6 {
7 "matcher": "regex",
8 "value": "(\\Ad)"
9 }
10 ]
See also
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 Loose request matching using a Request Matcher in the tutorials section.
There alse are two different matching strategies: strongest match (default) and first match (legacy). Please refer to Matching strategies for more information.
Responses¶
Each Request Matcher Set has a response associated with is. If the request match is successful, Hoverfly will return the response to the client.
1 "response": {
2 "status": 200,
3 "body": "Response from docs.hoverfly.io/pages/keyconcepts/templates.html",
4 "encodedBody": false,
5 "headers": {
6 "Hoverfly": [
7 "Was-Here"
8 ]
9 },
10 "templated": false
11 }
Editing the fields in response, combined with editing the Request Matcher set, makes it possible to configure complex request/response logic.
Binary data in responses¶
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.
1 "body": "YmFzZTY0IGVuY29kZWQ=",
2 "encodedBody": true,
Serving response bodies from files¶
Starting from version 1.3.0 hoverfly can return response body from a specific file:
"response": {
"status": 200,
"encodedBody": false,
"templated": false,
"bodyFile": "responses/200-success.json"
}
response/200-success.json is resolved against the directory specified in -response-body-files-path
which is your current working directory by default.
When both body
and bodyFile
are specified, body
takes precedence.
bodyFile
is read into memory only on simulation import, not in runtime.
Reading response bodies sometimes might not be comfortable. Imagine a developer team that needs a single updating “files provider”. Syncing to this provider can be a challenge and that’s why hoverfly supports downloading response bodies from external urls:
"response": {
"status": 200,
"encodedBody": false,
"templated": false,
"bodyFile": "https://raw.githubusercontent.com/SpectoLabs/hoverfly/master/core/handlers/v2/schema.json"
}
Like local files, this feature is supported only on simulation import. To escape security issues there’s another
mandatory option to specify -response-body-files-allow-origin
that lets you explicitly set the collections of
urls to allow body files to be downloaded from. For the above to work you need to run hoverfly like this:
hoverfly -response-body-files-allow-origin="https://raw.githubusercontent.com/"