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

image:https://circleci.com/gh/SpectoLabs/hoverfly-java.svg?style=shield["CircleCI", link="https://circleci.com/gh/SpectoLabs/hoverfly-java"] image:https://readthedocs.org/projects/hoverfly-java/badge/?version=latest["Read the Docs", link="https://hoverfly-java.readthedocs.io/en/latest/"] image:https://codecov.io/gh/spectolabs/hoverfly-java/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/spectolabs/hoverfly-java"] image:https://snyk.io/test/github/SpectoLabs/hoverfly-java/badge.svg?targetFile=build.gradle["Known Vulnerabilities", link="https://snyk.io/test/github/SpectoLabs/hoverfly-java?targetFile=build.gradle"] image:https://img.shields.io/maven-central/v/io.specto/hoverfly-java.svg["Maven Central", link="https://mvnrepository.com/artifact/io.specto/hoverfly-java"]

A Java native language binding for http://hoverfly.io/[Hoverfly^], a Go proxy which allows you to simulate http services in your unit tests. Another term for this is https://en.wikipedia.org/wiki/Service_virtualization[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
• http://hoverfly-java.readthedocs.io/en/latest/pages/junit5/junit5.html[JUnit 5 extension^]

== Documentation

Full documentation is available http://hoverfly-java.readthedocs.io/[here^]

== Maven Dependency

<dependency>
    <groupId>io.specto</groupId>
    <artifactId>hoverfly-java</artifactId>
    <version>0.19.0</version>
    <scope>test</scope>
</dependency>

== Example === 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");
}

Some code examples for the DSL are available https://github.com/SpectoLabs/hoverfly-java/blob/master/src/test/java/io/specto/hoverfly/ruletest/HoverflyDslTest.java[here^].

More code examples for the DSL using request matchers can be found https://github.com/SpectoLabs/hoverfly-java/blob/master/src/test/java/io/specto/hoverfly/ruletest/HoverflyDslMatcherTest.java[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
hoverflyRule.verifyZeroRequestTo(service(matches("*.flight.*")));

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

== 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) https://ioco.uk/[iOCO^] 2024.