Create simulations

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 Todo-Backend API implementation. The base URL for the API is

Using Hoverfly Cloud
Using CLI
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 list of todo items is:

What you should call instead in this example is:

You can inspect the requests and responses that have been captured by clicking on the simulation link. The captured simulation can be edited and exported for future use and sharing.

Using CLI

Download the CLI here.

Run the following command to start a capture service on localhost:

hcc capture start --target-url

You should provide the base URL of the service to the destination flag.

Once the capture service is started, any requests you made to http://localhost:8500 will be forwarded to the real service and the requests/responses will be recorded.

You can stop the capture and upload your simulation to your Hoverfly Cloud account with the following command:

hcc capture stop --simulation-name NAME --api-token TOKEN

An API token can be created from your account page.

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 /todos should look like this:

You can click on the “duplicate” icon 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:

id integer($int64)
petId integer($int64)
quantity integer($int32)
shipDate string($date-time)
status string
Order Status
[ 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".