Hoverfly hoverctl for coding agents

A coding agent that can run a service’s tests from the shell can use Hoverfly’s hoverctl command-line tool to run them against saved HTTP interactions. Hoverfly runs as a local proxy, an intermediary that receives requests and passes them to a service or returns saved responses. It can record requests and responses, then replay them from a portable simulation file. This lets the agent test how the code handles known API responses without sending replayed requests to the real service.

hoverctl controls a running Hoverfly instance. The official command reference documents commands for starting Hoverfly, changing its mode, and importing or exporting simulations. The steps below use an existing local simulation file; they do not capture live traffic or change a remote service.

Install and start Hoverfly

Install Hoverfly and hoverctl using the method for your operating system in the official installation guide. The guide links archives with both programs for the major operating systems. They come from the Hoverfly releases on GitHub. Extract them and put both programs in a directory on your PATH. On macOS, the guide also documents a Homebrew install:

brew install SpectoLabs/tap/hoverfly

The Hoverfly Docker image does not contain hoverctl. Check that the installed hoverctl version matches the Hoverfly version you plan to run.

For a local replay, start Hoverfly and load a simulation file that already exists in the repository:

hoverctl start
hoverctl import ./fixtures/catalog.json
hoverctl mode simulate

Replace ./fixtures/catalog.json with the path to a real Hoverfly simulation file. The example does not create that file. start launches the local Hoverfly instance, import loads saved interactions into it, and mode simulate tells Hoverfly to answer matching requests from those interactions. According to the simulate mode documentation, Hoverfly then responds itself and no traffic reaches the real API.

For a local instance, hoverctl does not require an account login. It sends control commands to Hoverfly through its administrative interface. If you point it at a remote instance or a secured deployment, check that deployment’s connection and access requirements separately. Do not put credentials in an agent prompt or command history.

Run a test through the local proxy

Configure the test client to send the target API requests through Hoverfly’s local proxy, then run the relevant test command. The Hoverfly tutorials use localhost:8500 as the proxy address. Many clients read the HTTP_PROXY and HTTPS_PROXY environment variables, but the proxy documentation notes that not all software respects them. For example, an agent working on a catalog client could replay saved catalog responses while running the client’s existing tests.

The test command depends on the project and the HTTP client’s proxy settings, so there is no universal command to copy here. Check that the client sends requests through Hoverfly. If it does not, its requests go directly to the configured API. When the client routes requests through Hoverfly, replayed interactions are served by the local instance. For HTTPS APIs, the client also has to trust Hoverfly’s certificate. The HTTPS tutorial shows this with curl and says other environments need the certificate in their trust store. The project’s test runner produces the test output.

After the test, stop the local instance if you no longer need it:

hoverctl stop

These commands change local Hoverfly state and run a local process. They do not write to the simulation file or contact the real API during replay. The test itself can still make other network requests if its configuration sends them outside the Hoverfly proxy.

Give the agent a bounded task

A useful prompt names the fixture, the code under test, and the expected scope:

Use Hoverfly to replay ./fixtures/catalog.json while running the catalog client tests. Configure the test client to use the local Hoverfly proxy. Do not capture live traffic or edit the fixture. Report the test command, its result, and any requests that did not match the saved interactions.

A mismatch means the loaded simulation has no saved interaction that matches the request. It does not, by itself, establish whether the code or fixture is wrong. The troubleshooting page explains that Hoverfly answers an unmatched request with an error. With the default matching strategy, the error shows the request it got and the closest saved matcher. hoverctl logs shows the same information. The agent should compare the request the test sent with the saved interaction before changing either one.

Know what replay proves

Hoverfly simulates HTTP and HTTPS interactions. A passing replay test shows how the code handles the responses saved in the fixture. It does not prove that the live API still returns those responses or conforms to a formal schema. Hoverfly’s documentation describes capture mode as the usual starting point for creating a simulation, so treat fixtures as recorded examples rather than complete API specifications.

If the repository lacks a suitable simulation, a developer can capture traffic and export it for later replay. During capture, Hoverfly sends requests to the live destination. Capture only when those network calls are intended and permitted. By default, capture does not save request headers. If you add --headers or --all-headers, check the file for tokens before you commit it. The tutorial uses hoverctl mode capture and hoverctl export; keep capture separate from an agent’s replay-only task.