WireMock: Mock HTTP Services for Spring REST Testing

Every Spring Boot service I've worked on eventually needs to talk to an external API. Whether it's a payment gateway, a third-party identity provider, or a weather service, your code's correctness depends on how it handles those HTTP calls. And that's exactly where most integration tests fall short.

I remember a fintech startup I consulted for: their CI pipeline was a nightmare. Tests would fail randomly because the test Stripe account would occasionally return 429 rate limits or 500 errors. The team spent hours blaming each other's code, only to realize the external API was the culprit. That's when I introduced WireMock.

WireMock lets you stub HTTP endpoints, simulate delays, inject faults, and even verify that your code sent the right request. It's not just about making tests pass — it's about making them deterministic. In this article, I'll show you how to integrate WireMock with Spring Boot tests, what the official docs gloss over, and how to debug it when things go sideways.

Setting Up WireMock in Spring Boot

Let's start with the basics. The fastest way to get WireMock into your Spring Boot test is via the spring-cloud-contract-wiremock starter, but I prefer the standalone WireMock library for more control. Here's my go-to setup:

Add the dependency to your pom.xml:

``xml <dependency> <groupId>com.github.tomakehurst</groupId> <artifactId>wiremock-jre8</artifactId> <version>2.35.0</version> <scope>test</scope> </dependency> ``

Then in your test, use @WireMockTest to automatically start a WireMock server on a random port. Combine it with Spring's @SpringBootTest and @TestRestTemplate for a full integration test.

Here's a typical example: we have a service that calls an external API to get exchange rates. We'll stub that API with WireMock.

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@WireMockTest(httpPort = 8089)
class ExchangeRateServiceTest {

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void shouldReturnConvertedAmount() {
        // Stub external API
        stubFor(get(urlEqualTo("/api/rates?from=USD&to=EUR"))
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withBody("{\"rate\": 0.85}")));

        // Call our service
        ResponseEntity<String> response = restTemplate.getForEntity(
                "/convert?amount=100&from=USD&to=EUR", String.class);

        assertThat(response.getStatusCode()).isEqualTo(200);
        assertThat(response.getBody()).contains("85.0");
    }
}

Request Matching and Response Templating

WireMock's request matching is powerful. You can match on URL, method, headers, query parameters, and body. For dynamic responses, use response templating with Handlebars.

Consider a payment service that expects a JSON payload with a transaction_id. You can match the body and return a dynamic response:

``java stubFor(post(urlEqualTo("/payments")) .withRequestBody(matchingJsonPath("$.amount")) .willReturn(aResponse() .withStatus(201) .withHeader("Content-Type", "application/json") .withBody("{ \"id\": \"{{randomValue length=20 type='ALPHANUMERIC'}}\", \"status\": \"approved\" }") .withTransformers("response-template"))); ``

This uses the response-template transformer to generate a random ID. You need to enable the transformer globally or per stub.

For more complex scenarios, use WireMock's scenario feature to simulate stateful behavior, like a payment that is first pending then confirmed.

@Test
void shouldHandlePaymentFlow() {
    // Scenario: payment starts as pending, then approved
    stubFor(post(urlEqualTo("/payments"))
            .inScenario("Payment Flow")
            .whenScenarioStateIs(Scenario.STARTED)
            .willReturn(aResponse()
                    .withStatus(201)
                    .withBody("{\"status\":\"pending\"}"))
            .willSetStateTo("Approved"));

    stubFor(post(urlEqualTo("/payments"))
            .inScenario("Payment Flow")
            .whenScenarioStateIs("Approved")
            .willReturn(aResponse()
                    .withStatus(200)
                    .withBody("{\"status\":\"approved\"}")));

    // First call returns pending
    ResponseEntity<String> first = restTemplate.postForEntity("/pay", paymentRequest, String.class);
    assertThat(first.getBody()).contains("pending");

    // Second call returns approved
    ResponseEntity<String> second = restTemplate.postForEntity("/pay", paymentRequest, String.class);
    assertThat(second.getBody()).contains("approved");
}

Verifying Requests and Asserting Interactions

Testing that your service sent the correct request is just as important as stubbing the response. WireMock allows you to verify that a specific request was made, with exact matching.

For example, after calling your payment service, verify that it sent the correct payload to the external API:

``java verify(postRequestedFor(urlEqualTo("/payments")) .withRequestBody(matchingJsonPath("$.amount", equalTo("100.00"))) .withHeader("Authorization", containing("Bearer"))); ``

You can also verify the number of calls:

``java verify(exactly(1), postRequestedFor(urlEqualTo("/payments"))); ``

This is crucial for ensuring your service doesn't make duplicate requests or miss calls entirely.

@Test
void shouldSendCorrectPaymentRequest() {
    stubFor(post(urlEqualTo("/payments"))
            .willReturn(aResponse().withStatus(201)));

    restTemplate.postForEntity("/pay", new PaymentRequest(100.00), String.class);

    verify(postRequestedFor(urlEqualTo("/payments"))
            .withRequestBody(matchingJsonPath("$.amount", equalTo("100.0")))
            .withHeader("Authorization", containing("Bearer secret")));
}

Simulating Faults and Edge Cases

One of WireMock's superpowers is fault injection. You can simulate timeouts, connection resets, malformed responses, and HTTP errors. This is invaluable for testing your error handling and retry logic.

For example, to simulate a slow API:

``java stubFor(get(urlEqualTo("/slow")) .willReturn(aResponse() .withFixedDelay(5000) .withStatus(200))); ``

Or a connection reset:

``java stubFor(get(urlEqualTo("/reset")) .willReturn(aResponse().withFault(Fault.CONNECTION_RESET_BY_PEER))); ``

Combine this with Spring's @Retryable to ensure your service handles transient failures gracefully.

@Test
void shouldHandleTimeout() {
    stubFor(get(urlEqualTo("/api/data"))
            .willReturn(aResponse()
                    .withFixedDelay(10000)
                    .withStatus(200)));

    assertThrows(ResourceAccessException.class, () -> {
        restTemplate.getForEntity("/fetch-data", String.class);
    });
}

@Test
void shouldHandleConnectionReset() {
    stubFor(get(urlEqualTo("/api/data"))
            .willReturn(aResponse().withFault(Fault.CONNECTION_RESET_BY_PEER)));

    assertThrows(ResourceAccessException.class, () -> {
        restTemplate.getForEntity("/fetch-data", String.class);
    });
}

What the Official Docs Won't Tell You

After years of using WireMock in production-grade Spring Boot applications, here are the gotchas that the official documentation glosses over:

1. Static state pollution across test classes WireMock server, when used as a static field or via @WireMockTest, holds state across tests. If you don't reset it, stubs from one test can affect another. The official docs mention resetAll() but don't emphasize that you must call it in @BeforeEach or @AfterEach. I've seen CI builds fail randomly because of this.

2. Response templating is not enabled by default The response-template transformer must be registered explicitly. Many developers assume it works out of the box and waste hours debugging why {{randomValue}} isn't generating random data.

3. JSON matching with equalToJson can be tricky By default, equalToJson is strict about field ordering and whitespace. Use the lenient mode: equalToJson(body, true, true). The second parameter is ignoreArrayOrder, the third is ignoreExtraElements. Without these, tests can fail due to JSON formatting differences.

4. WireMock's HTTPS support requires extra setup If your application calls HTTPS endpoints, WireMock can simulate that, but you need to configure a keystore. The docs cover it, but most examples use HTTP. In production, your external APIs are likely HTTPS, so your tests should reflect that.

5. Record-playback can be a maintenance nightmare WireMock can record real API responses and play them back. It sounds great, but the recorded stubs are fragile. If the API changes even slightly, your tests break. I recommend using it only for initial test creation, then hand-tuning stubs for maintainability.

@WireMockTest(httpsEnabled = true)
class HttpsTest {

    @Test
    void testHttpsStub() {
        stubFor(get(urlEqualTo("/secure"))
                .willReturn(aResponse().withStatus(200)));

        // Your service must trust WireMock's self-signed certificate
        ResponseEntity<String> response = restTemplate.getForEntity("https://localhost:8443/secure", String.class);
        assertThat(response.getStatusCode()).isEqualTo(200);
    }
}

Integrating WireMock with Spring Cloud Contract

If you're working in a microservices ecosystem, Spring Cloud Contract (SCC) builds on top of WireMock to provide contract testing. SCC generates WireMock stubs from contract definitions, which can be shared between producer and consumer services.

Here's a minimal setup: add the spring-cloud-starter-contract-verifier dependency and write a contract in Groovy or YAML. SCC will generate tests and WireMock stubs automatically.

But be warned: SCC adds complexity. For simple projects, plain WireMock is often sufficient. I've seen teams over-engineer their testing with SCC when all they needed was a few stubs.

Contract.make {
    description "should return exchange rate"
    request {
        method GET()
        url "/api/rates?from=USD&to=EUR"
        headers {
            contentType applicationJson()
        }
    }
    response {
        status 200
        headers {
            contentType applicationJson()
        }
        body """
        {
            "rate": 0.85
        }
        """
    }
}