Awesome Open Source
Awesome Open Source

== Hoverfly Java - Easy Creation of Stub Http Servers for Testing

image:["CircleCI", link=""] image:["Read the Docs", link=""] image:["Codecov", link=""] image:["Known Vulnerabilities", link=""] image:["Maven Central", link=""]

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^].

== Features

  • 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^]

== Documentation

Full documentation is available[here^]

== Maven Dependency


== Example === 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

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.

== Issues

Feel free to raise an issues on Github.

== License

Apache License version 2.0.

(c) SpectoLabs 2020.

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
java (29,706
testing (881
http (859
proxy (492
https (197
testing-tools (188
mocking (97
stubbing (14

Find Open Source By Browsing 7,000 Topics Across 59 Categories