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            },

View entire simulation file

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               ]

View entire simulation file

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               ]

View entire simulation file

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               ]

View entire simulation file

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            }

View entire simulation file

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,

View entire simulation file

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/"