Tutorial 5: Simulate, Capture, Spy and Passthrough modes

In this walkthrough you will work with each of the 4 Hoverfly modes to understand what they are used for.

• Hoverfly has various modes which we will use against worldtimeapi.org :

  • Capture: To act as a proxy to an existing real HTTP API, whereby any requests made via the proxy and returned via the proxy are recorded into a simulation.

  • Simulate: To act as a webserver to serve up a pre-configured simulation consisting of pre-recorded or coded HTTP request/response pairs. In addition in Simulation mode, Hoverfly can adopt different matching strategies and use a combination of response templating and behavior injection to simulate realistic data and physical API behaviors.

  • Spy: To act primarily as a webserver exactly as in Simulate mode, but, if the matching strategy cannot find a response to match a given request, to then act as a passthrough proxy to the real service and return the actual API response.

  • Passthrough: To act as if it isn't there. Purely for convenience, this mode will pass all requests and responses straight to the real API and back to the caller for when you want to use the real API without having to reconfigure the environment.

Part 1. Capture mode

Follow these steps:

1. Using your API client or browser, make a call to the following real API to get the current date and time for London:

   http://worldtimeapi.org/api/timezone/Europe/London

2. The data returned shows the real time and date in the BST timezone:

{
    "abbreviation": "BST",
    "client_ip": "151.230.54.226",
    "datetime": "2023-08-16T11:08:00.896767+01:00",
    "day_of_week": 3,
    "day_of_year": 228,
    "dst": true,
    "dst_from": "2023-03-26T01:00:00+00:00",
    "dst_offset": 3600,
    "dst_until": "2023-10-29T01:00:00+00:00",
    "raw_offset": 0,
    "timezone": "Europe/London",
    "unixtime": 1692180480,
    "utc_datetime": "2023-08-16T10:08:00.896767+00:00",
    "utc_offset": "+01:00",
    "week_number": 33
}

1. Now configure a Hoverfly Cloud service in capture mode to record requests and responses to and from this API:

2. Click +Add service from the Dashboard.

3. Leave Simulation blank (we will be recording a Simulation in capture mode), give it a name of worldtimeapi, check enable proxying and provide a Target URL of https://worldtimeapi.org. Make sure to set the Mode to capture.

   
4. You will be returned to Dashboard and your new service will be blinking orange as the service is deployed. Once green, it is ready to be used.

5. Using your API client or browser, make a call to the new Hoverfly service in capture mode to get the current date and time for London:

   • https://worldtimeapi-<<your unique id>>.hoverfly.io/api/timezone/Europe/London

   • In doing so the request will be proxied through the Hoverfly service, recorded, and when the response comes back that will also be recorded.

6. Now click the (unsaved) link for the Simulation associated with your new service from the Dashboard.

   • You will see the simulation that was recorded, because the Hoverfly service was running in capture mode.

   • It will consist of one GET request method, and various fields showing Request matchers as well as the associated response for this request/response pair in the simulation.

   • At this point you could save the new simulation (Export simulation as new) from the simulation screen for this service, whereby it would appear in the Simulations section, and could be shared with your team for use in their Hoverfly services, or downloaded and kept in a source repository.

Part 2. Simulate mode

Follow these steps:

1. Return to the Dashboard and switch the running worldtimeapi service from capture to simulate mode via the dropdown.

2. Once again using your API client or browser, make a call to the Hoverfly service in simulate mode to get the current date and time for London:

   • https://worldtimeapi-<<your unique id>>.hoverfly.io/api/timezone/Europe/London

   • In doing so the request will be served by the Hoverfly service, not proxied through to the real service. The real service is out of the picture.

   • Of course in our case, this does mean that every request (with the matching Request matchers) will be returned by the Hoverfly service with exactly the same response and the time won't change.

3. Now change the last segment of the path to Paris

   • https://worldtimeapi-<<your unique id>>.hoverfly.io/api/timezone/Europe/Paris

   • Now, because the Hoverfly service is in simulate mode, and it cannot match the path as the matcher has been configured, you will receive a matching error.

4. At this point you could fiddle with the simulation, duplicate and edit the request/response pairs that the simulation will serve, match based on glob or regular expressions, add templating to make it return the real time, inject delays into the simulation, or add other behaviors to the running service to simulate errors or change headers. You have control over the responses that Hoverfly Cloud will serve based on the request matchers that you set for a request/response pair.

Part 3. Spy mode

Follow these steps:

1. Spy mode is Simulate mode, with the addition that if a request cannot be matched, instead of returning a matching error, the Hoverfly service will instead do a passthrough proxy of the request to the real service, and return the real result to the caller.

2. Return to the Dashboard and Change the worldtimeapi's mode to spyfrom the dropdown.

3. Once again using your API client or browser, make a call to the Hoverfly service, now in spy mode, to get the current date and time for London:

   • https://worldtimeapi-<<your unique id>>.hoverfly.io/api/timezone/Europe/London

   • Because it found a match, the request will be served by the Hoverfly service, not proxied through to the real service. The time will still show the time in the past that was stored when the response was captured in Part 1.

4. Now change the last segment of the path to Paris

   • https://worldtimeapi-<<your unique id>>.hoverfly.io/api/timezone/Europe/Paris

   • Now, because the Hoverfly service is in spy mode, and it cannot match the request as it has been configured, it will pass the request on to the real service and the response should come back with the real time for Paris.

5. With Spy mode it is possible to switch between the simulated service and the real service by setting a matching strategy that will purposefully mismatch based on a header or parameter that you set in the request, should you want to control which calls must go through and be served by the real service, and which should be served by the Hoverfly simulation.

Part 4. Passthrough mode

Follow these steps:

1. Passthrough mode will simply pass all requests through to the real service without attempting to perform matching.

2. Return to the Dashboard and Change the worldtimeapi's mode to passthrough from the dropdown.

3. Now try various combinations of paths including the one that has a matching request matcher (/Europe/London) and you will note that the response is always returned from the real service no matter what.

Part 5. Remove the service

Follow these steps:

1. Unless you want to keep the service, they can be deleted.

2. To delete the service and it's copy of the simulation navigate to the Dashboard, open the ellipse to the right of the product service that you created, and select Delete.

Congratulations! You have completed this Tutorial, "Tutorial 4: Simulate, Capture, Spy and Passthrough modes."