Work with instances

Start an instance

Starting an instance creates a public available HTTP service that simulates an API. Click on “Start” will prompt you to enter the URL of the real service. Later on you can change the instance mode to simulate / capture / spy / passthrough to suit different test purposes. However, you can leave the “Target URL” input blank to create a simulate-only service.

You will then need to enter a name for your instance, which forms part of the instance URL. An optional step is to select a simulation from the dropdown which will be imported when the instance starts.

Click “OK”, and your instance should be up and running within a few seconds.

Start an instance with behaviors (for Pro account)

A Hoverfly Behavior is a function that intercepts and modifies the API response before it returns to the client. With Behaviors, it is possible to introduce bad responses, latency modeling and more to mimic real world behavior of an API which is otherwise hard to reproduce.

Currently Hoverfly Cloud supports these predefined Behaviors:

You can add a Behavior in the Start Instance dialog.

Instance add behavior

Click on the toggle next to the Behavior name, for example “Random status code”, select status code you want it to return, and use the slider to change the probability of this status code.

You can add additional entries. Probabilities that total over one will get sampled down. When the probability total is less than one, the left over probability is used for the original status code.

Make requests to the instance

Sending a request to the instance requires an API token. Please follow the quickstart guide to create a token and we would recommend you to export it as an environment variable.

To authenticate your access to the instance, an request must contains an authentication header:

curl -H "X-Hoverfly-Authorization: Bearer $HFC_TOKEN" <instance URL>

In your project, you may not want to change your code to use Hoverfly Cloud. That’s why we provide an command line tool hoverfly-cloud-agent to handle the authentication, and you can call your Hoverfly Cloud instance like a localhost service.

./hoverfly-cloud-agent start-reverse-proxy --name <instance name> --api-token $HFC_TOKEN

Once you run the above command, the instance would be available on http://localhost:8500

View instance details and journal

You can click on the instance name to open up the instance details page. It gives you information about the instance, such as launch time, mode, URL, and target URL etcs.

You can also view the journal which is a list of access logs to the instance. A green entry indicates a successful match and a red entry indicates a failed match.

Instance details

Change mode

You can change instance mode using the mode dropdown. Hoverfly Cloud currently supports 4 different modes:

Change simulations

You can update your instance to use a different simulation stored in your account.

Go to instance detail pages, and select the simulation name from the dropdown.

Hoverfly Cloud will take care of updating the simulations in the instance.

View and edit running simulations

Click on the simulation link to view the simulations loaded in the instance.

You can make change to it using the editor, and click “Apply” to make your change effective.

Export running simulations

You can also export the simulation in an active instance for future sharing or reuse, especially the simulations are created via capturing.

Click on the dropdown menu in the toolbar and select “Export”, it will prompt you for the simulation name.

Instance simulation export