Testing HTTP Clients in Java with WireMock and Spring Boot

When a Spring Boot application calls an external REST API, integration tests face a familiar problem: the real service might be slow, unavailable, or simply impossible to control. WireMock solves this by running a local HTTP server that simulates the external API. You define stubs — rules that say „if a request looks like X, respond with Y“ — and your client talks to WireMock as if it were the real thing.

Core concepts

WireMock revolves around three ideas:

Stub: a rule matching an incoming request (method, URL, headers, body) to a predefined response.
Server: an embedded HTTP server, typically started on a random or fixed port for the duration of a test.
Verification: an optional check that a particular request was actually made, useful for testing side effects like outgoing webhook calls.

In a Spring Boot context, the goal is to start this server automatically, point your application’s HTTP client at it, and stub the endpoints your code depends on.

Maven dependency

The official Spring Boot integration is wiremock-spring-boot. Add it with test scope:

xml

			
<dependency>
    <groupId>org.wiremock.integrations</groupId>
    <artifactId>wiremock-spring-boot</artifactId>
    <version>4.2.1</version>
    <scope>test</scope>
</dependency>

		

This single artifact pulls in WireMock’s core engine and the Spring glue code needed for autoconfiguration. No manual server lifecycle management is required.

Starting the server with autoconfiguration

The integration exposes one annotation: @EnableWireMock. Place it on a Spring Boot test class, and a WireMock server starts before the application context loads, then shuts down afterward automatically.

java

			
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@EnableWireMock
class OrderServiceTest {
    @Value("${wiremock.server.baseUrl}")
    private String wireMockUrl;
    @Autowired
    private OrderService orderService;
    // tests go here
}

		

wiremock.server.baseUrl is injected automatically as a Spring property. Use it to wire your application’s HTTP client (e.g. RestClient or WebClient) to point at WireMock instead of the real endpoint — typically via application-test.yml or a @DynamicPropertySource.

A stub example

Stubs are defined with WireMock’s fluent API, usually inside the test method:

java

			
@Test
void returnsOrderDetails() {
    stubFor(get(urlEqualTo("/api/orders/42"))
            .willReturn(okJson("""
                {"id": 42, "status": "SHIPPED"}""")));
    Order order = orderService.fetchOrder(42);
    assertThat(order.status()).isEqualTo("SHIPPED");
}

		

stubFor registers the rule; get(urlEqualTo(...)) matches the request; willReturn(okJson(...)) defines a 200 response with a JSON body. WireMock also supports matching on headers, query parameters, and request bodies, plus simulating errors (aResponse().withStatus(500)) and delays — handy for testing timeout and retry logic.

Why this matters

Stubbing external calls makes tests deterministic and fast, removes network flakiness from your test suite, and lets you exercise edge cases — timeouts, malformed responses, 4xx/5xx errors — that are hard to trigger against a real service on demand.

This os a minimal approach: one dependency, one annotation, one stub. From here, explore request matchers, scenario-based stateful stubs, and fault injection as your test suite grows.

Dabbaghi.com