unit-test-wiremock-rest-api

SKILL.md

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