SpectoLabs / hoverfly-java

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

Create API simulation using capture mode

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


// After the capturing, switch to inSimulationMode to spin up a stub server
@ClassRule
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
@ClassRule
public static HoverflyRule hoverflyRule = HoverflyRule.inCaptureOrSimulationMode("simulation.json");

Create API simulation using DSL

@ClassRule
public static HoverflyRule hoverflyRule = HoverflyRule.inSimulationMode(dsl(
    service("www.my-test.com")
        .get("/api/bookings/1")
        .willReturn(created("http://localhost/api/bookings/1"))
));

@Test
public void shouldBeAbleToGetABookingUsingHoverfly() {
    // When
    final ResponseEntity<String> getBookingResponse = restTemplate.getForEntity("http://www.my-test.com/api/bookings/1", String.class);

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

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
hoverflyRule.verifyZeroRequestTo(service(matches("*.flight.*")));

// Verify all the stubbed requests were made at least once
hoverflyRule.verifyAll();

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.