Create simulations

Create and manage API simulations with Hoverfly Cloud, capturing real service activity for robust testing.

Capture real service activities

Capturing live traffic of a real service is a quick way to create a simulation.

You can do that on Hoverfly Cloud if the service is available on the internet. Otherwise, if the service is behind a firewall and Hoverfly Cloud has no access to it, you will need to use the Hoverfly Cloud CLI.

Let's take a look at how you can capture one of the end points from the Dog CEO API. The base URL for the API is https://dog.ceo.

Using Hoverfly Cloud

In the Simulations page, click the "Capture" button, and select "Yes" to confirm that the API you are going to capture is accessible from the internet.

Then you will be prompted to enter the base URL of the target API.

Click "OK", and a capture service will start on the Dashboard.

You should make your requests to the capture service URL instead of the original URL. For example, the original URL for getting a random dog image URL is:

https://dog.ceo/api/breeds/image/random

What you should call instead in this example is:

https://dog-ceo-stuawj8.hoverfly.io/api/breeds/image/random

You can inspect the requests and responses that have been captured by clicking on the unsaved simulation link. You will see that an endpoint has created to represent the request and a matching response.

The captured simulation can be edited and exported for future use and sharing. It can also be turned into a simulation so that it plays back the responses based on matching requests it receives.

Using CLI

Manual design using the Simulation Editor

If your API does not yet exist, you can design it using the Simulation Editor. On the Simulations page, click “Create”.

Click on “Add endpoint” to add your first request/response pair.

Use the editor to design the request you want to match and the corresponding response. For example, a simple request matcher for matching GET request to the path /api/breeds/image/random should look like this:

You can click on the “duplicate” burger menu item to reuse an existing pair.

Once you are happy about your simulation, you can click “Save” to create it.

Changes made in the Simulation Editor are not automatically saved. You should click "Save" if you need to keep your changes before navigating to other pages.

Convert from a Swagger Specification

Click “From Swagger” to create a simulation from a Swagger Specification.

The current supported Swagger version is 2.0. Both JSON and YAML formats are supported.

Click “Choose file” and select a Swagger file from disk.

Click "Confirm" to finish.

Hoverfly Cloud will create one request matcher for each combination of API path and operation in the specification. For example, the Swagger Petstore GET store order API will be converted to the following matcher:

Only one response per API specification is converted, which is usually the 200 successful response. The conversion will look for any example data to use for the response body, but if none were defined in the Swagger specification, Hoverfly Cloud will render a response body that conforms with the Swagger data schema.

For instance, the Swagger Petstore GET store order API defines the following response data schema:

Order{
    id	        integer($int64)
    petId	    integer($int64)
    quantity    integer($int32)
    shipDate	string($date-time)
    status	    string
                Order Status
                Enum:
                [ placed, approved, delivered ]
    complete	boolean
                default: false
}

Which converts to the following response body by Hoverfly Cloud:

{
  "id": 0,
  "petId": 0,
  "quantity": 0,
  "shipDate": "2000-01-01T00:00:00Z",
  "status": "placed",
  "complete": false
}

You can enhance the simulation converted from Swagger by using response templating.

Add templating functions to the above response and enable templating:

You should get back a response generated dynamically when you call the endpoint /v2/store/order/1:

{
  "id": 1,
  "petId": 156,
  "quantity": 3,
  "shipDate": "2019-05-20T13:35:08Z",
  "status": "placed",
  "complete": false
}

Upload from an existing simulation file

Hoverfly Cloud simulation files are interchangeable with Hoverfly. To upload a simulation file go to the Simulations page, and click "Upload", select a file and click "Confirm".

Learn more

Follow these tutorials to learn more about creating Simulations: Creating simulations and services