Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Hoverfly Java - Easy Creation of Stub Http Servers for Testing

CircleCI Read the Docs Codecov Known Vulnerabilities Maven Central

A Java native language binding for Hoverfly, a Go proxy which allows you to simulate http services in your unit tests. Another term for this is Service Virtualisation.


  • Simulation of http/https services

  • Strict or loose http request matching based on URL, method, body and header combinations

  • Fluent and expressive DSL for easy generation of simulated services

  • Automatic marshalling of objects into JSON during request / response body generation

  • Create simulations by capturing live traffic

  • Hoverfly is a proxy, so you don’t need to alter the host that you make requests to

  • Multiple hosts / services per single instance of Hoverfly

  • Https automatically supported, no extra configuration required

  • Supports Mutual TLS authentication capture

  • Interoperable with standard Hoverfly JSON, making it easy to re-use data between Java and other native language bindings.

  • Use externally managed Hoverfly cluster for API simulations

  • Request verification

  • Response templating

  • Stateful capture / simulation

  • JUnit 5 extension


Full documentation is available here

Maven Dependency



Create API simulation using capture mode

// Capture and output HTTP traffic to json file
public static HoverflyRule hoverflyRule = HoverflyRule.inCaptureMode("simulation.json");

// After the capturing, switch to inSimulationMode to spin up a stub server
public static HoverflyRule hoverflyRule = HoverflyRule.inSimulationMode(defaultPath("simulation.json"));

// Or you can use both approaches at once. If json file not present in capture mode, if present in simulation mode
public static HoverflyRule hoverflyRule = HoverflyRule.inCaptureOrSimulationMode("simulation.json");

Create API simulation using DSL

public static HoverflyRule hoverflyRule = HoverflyRule.inSimulationMode(dsl(

public void shouldBeAbleToGetABookingUsingHoverfly() {
    // When
    final ResponseEntity<String> getBookingResponse = restTemplate.getForEntity("", String.class);

    // Then
    assertEquals(bookFlightResponse.getStatusCode(), CREATED);
    assertEquals(bookFlightResponse.getHeaders().getLocation(), "http://localhost/api/bookings/1");

Some code examples for the DSL are available here.

More code examples for the DSL using request matchers can be found here.

Verify requests

// Verify that at least one request to a specific endpoint with any query params
hoverflyRule.verify(service(matches("*.flight.*")).get("/api/bookings").anyQueryParams(), atLeastOnce());

// Verify that an external service/dependency was not called

// Verify all the stubbed requests were made at least once


Contributions are welcome!

To submit a pull request you should fork the Hoverfly-Java repository, and make your change on a feature branch of your fork.

As of v0.10.2, hoverfly binaries are no longer stored in the repository. You should run ./gradlew clean test once to cache the binaries for development with your IDE.

If you have forked this project prior to v0.10.2, please re-fork to get a slimmer version of the repository.


Feel free to raise an issues on Github.


Apache License version 2.0.

(c) SpectoLabs 2020.