Unit Test Wiremock Rest Api

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

1. Add dependency: WireMock in test scope (Maven/Gradle) 2. Register extension: @RegisterExtension WireMockExtension with dynamicPort() 3. Configure client: Use wireMock.getRuntimeInfo().getHttpBaseUrl() as base URL 4. Stub responses: stubFor() with request matching (URL, headers, body) 5. Execute and assert: Call service methods, validate results with AssertJ 6. 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

WireMock Advanced Examples

Additional patterns for complex WireMock testing scenarios.

Error Scenario Testing (4xx/5xx)

@Test
void shouldHandleNotFoundError() {
  wireMock.stubFor(get(urlEqualTo("/api/users/999"))
    .willReturn(aResponse()
      .withStatus(404)
      .withBody("{\"error\":\"User not found\"}")));

  ApiClient client = new ApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl());

  assertThatThrownBy(() -> client.getUser(999))
    .isInstanceOf(UserNotFoundException.class)
    .hasMessageContaining("User not found");
}

@Test
void shouldHandleServerError() {
  wireMock.stubFor(get(urlEqualTo("/api/data"))
    .willReturn(aResponse()
      .withStatus(500)
      .withBody("{\"error\":\"Internal server error\"}")));

  ApiClient client = new ApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl());

  assertThatThrownBy(() -> client.fetchData())
    .isInstanceOf(ServerErrorException.class);
}

Request Body Verification

@Test
void shouldVerifyRequestBody() {
  wireMock.stubFor(post(urlEqualTo("/api/users"))
    .willReturn(aResponse()
      .withStatus(201)
      .withBody("{\"id\":123,\"name\":\"Alice\"}")));

  ApiClient client = new ApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl());
  UserResponse response = client.createUser("Alice");

  assertThat(response.getId()).isEqualTo(123);

  wireMock.verify(postRequestedFor(urlEqualTo("/api/users"))
    .withRequestBody(matchingJsonPath("$.name", equalTo("Alice")))
    .withHeader("Content-Type", containing("application/json")));
}

Timeout Simulation

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

  // Configure client timeout < 5000ms
  assertThatThrownBy(() -> client.fetchSlowEndpoint())
    .isInstanceOf(SocketTimeoutException.class);
}

Partial Response Matching

@Test
void shouldMatchPartialRequestBody() {
  wireMock.stubFor(post(urlEqualTo("/api/orders"))
    .withRequestBody(matchingJsonPath("$.items[*]", equalTo("[1,2,3]")))
    .willReturn(aResponse()
      .withStatus(201)));

  ApiClient client = new ApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl());
  client.createOrder(List.of(1, 2, 3));

  wireMock.verify(postRequestedFor(urlEqualTo("/api/orders")));
}

Scenarios (Stateful Behavior)

@Test
void shouldSupportStatefulScenarios() {
  wireMock.stubFor(get(urlEqualTo("/api/status"))
    .inScenario("OrderWorkflow")
    .whenScenarioStateIs(STARTED)
    .willSetStateTo("PROCESSING")
    .willReturn(aResponse()
      .withStatus(202)
      .withBody("{\"status\":\"processing\"}")));

  wireMock.stubFor(get(urlEqualTo("/api/status"))
    .inScenario("OrderWorkflow")
    .whenScenarioStateIs("PROCESSING")
    .willSetStateTo("COMPLETED")
    .willReturn(aResponse()
      .withStatus(200)
      .withBody("{\"status\":\"completed\"}")));

  // First call
  client.getOrderStatus();
  wireMock.verify(getRequestedFor(urlEqualTo("/api/status"))
    .inScenario("OrderWorkflow"));

  // Second call
  client.getOrderStatus();
  wireMock.verify(getRequestedFor(urlEqualTo("/api/status")));
}