Unit Testing REST APIs with WireMock

Overview

Patterns for testing external REST API integrations with WireMock: stubbing responses, verifying requests, error scenarios, and fast tests without network dependencies.

When to Use

• Testing services calling external REST APIs

• Stubbing HTTP responses for predictable test behavior

• Testing error scenarios (timeouts, 5xx errors, malformed responses)

• Verifying request details (headers, query params, request body)

Instructions

• Add dependency: WireMock in test scope (Maven/Gradle)

• Register extension: @RegisterExtension WireMockExtension with dynamicPort()

• Configure client: Use wireMock.getRuntimeInfo().getHttpBaseUrl() as base URL

• Stub responses: stubFor() with request matching (URL, headers, body)

• Execute and assert: Call service methods, validate results with AssertJ

• Verify requests: verify() to ensure correct API usage

If stub not matching: Check URL encoding, header names, use urlEqualTo for query params.

If tests hanging: Configure connection timeouts in HTTP client; use withFixedDelay() for timeout simulation.

If port conflicts: Always use wireMockConfig().dynamicPort().

Examples

Maven Dependencies

<dependency>

  <groupId>org.wiremock</groupId>

  <artifactId>wiremock</artifactId>

  <version>3.4.1</version>

  <scope>test</scope>

</dependency>

<dependency>

  <groupId>org.assertj</groupId>

  <artifactId>assertj-core</artifactId>

  <scope>test</scope>

</dependency>

Basic Stubbing and Verification

import com.github.tomakehurst.wiremock.junit5.WireMockExtension;

import org.junit.jupiter.api.Test;

import org.junit.jupiter.api.extension.RegisterExtension;

import static com.github.tomakehurst.wiremock.client.WireMock.*;

import static org.assertj.core.api.Assertions.assertThat;

class ExternalWeatherServiceTest {

  @RegisterExtension

  static WireMockExtension wireMock = WireMockExtension.newInstance()

    .options(wireMockConfig().dynamicPort())

    .build();

  @Test

  void shouldFetchWeatherDataFromExternalApi() {

    wireMock.stubFor(get(urlEqualTo("/weather?city=London"))

      .withHeader("Accept", containing("application/json"))

      .willReturn(aResponse()

        .withStatus(200)

        .withHeader("Content-Type", "application/json")

        .withBody("{\"city\":\"London\",\"temperature\":15,\"condition\":\"Cloudy\"}")));

    String baseUrl = wireMock.getRuntimeInfo().getHttpBaseUrl();

    WeatherApiClient client = new WeatherApiClient(baseUrl);

    WeatherData weather = client.getWeather("London");

    assertThat(weather.getCity()).isEqualTo("London");

    assertThat(weather.getTemperature()).isEqualTo(15);

    wireMock.verify(getRequestedFor(urlEqualTo("/weather?city=London"))

      .withHeader("Accept", containing("application/json")));

  }

}

See references/advanced-examples.md for error scenarios, body verification, timeout simulation, and stateful testing.

Best Practices

• Dynamic port: Prevents conflicts in parallel test execution

• Verify requests: Ensures correct API usage by the client

• Test errors: Cover timeouts, 4xx, 5xx scenarios

• Focused stubs: One concern per test

• Auto-reset: @RegisterExtension resets WireMock between tests

• Never call real APIs: Always stub third-party endpoints

Constraints and Warnings

• Dynamic ports required: Fixed ports cause parallel execution conflicts

• HTTPS testing: Configure WireMock TLS settings if testing TLS connections

• Stub precedence: More specific stubs take priority over general ones

• Performance: WireMock adds overhead; mock at client layer for faster tests

• API changes: Keep stubs synchronized with actual API contracts

References

• WireMock Documentation

• WireMock Stubbing Guide

• references/advanced-examples.md - Error scenarios, body verification, timeouts