CtrlK
BlogDocsLog inGet started
Tessl Logo

unit-test-wiremock-rest-api

Unit tests for external REST APIs using WireMock to mock HTTP endpoints. Use when testing service integrations with external APIs.

Install with Tessl CLI

npx tessl i github:giuseppe-trisciuoglio/developer-kit --skill unit-test-wiremock-rest-api
What are skills?

78

Review — 76%

Does it follow best practices?

Validation — 11 / 16 Passed

Validation for skill structure

SKILL.md
Review
Evals

Unit Testing REST APIs with WireMock

Test interactions with third-party REST APIs without making real network calls using WireMock. This skill focuses on pure unit tests (no Spring context) that stub HTTP responses and verify requests.

When to Use This Skill

Use this skill when:

  • Testing services that call external REST APIs
  • Need to stub HTTP responses for predictable test behavior
  • Want to test error scenarios (timeouts, 500 errors, malformed responses)
  • Need to verify request details (headers, query params, request body)
  • Integrating with third-party services (payment gateways, weather APIs, etc.)
  • Testing without network dependencies or rate limits
  • Building unit tests that run fast in CI/CD pipelines

Core Dependencies

Maven

<dependency>
  <groupId>org.wiremock</groupId>
  <artifactId>wiremock</artifactId>
  <version>3.4.1</version>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>org.assertj</groupId>
  <artifactId>assertj-core</artifactId>
  <scope>test</scope>
</dependency>

Gradle

dependencies {
  testImplementation("org.wiremock:wiremock:3.4.1")
  testImplementation("org.junit.jupiter:junit-jupiter")
  testImplementation("org.assertj:assertj-core")
}

Basic Pattern: Stubbing and Verifying

Simple Stub with WireMock Extension

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")));
  }
}

Testing Error Scenarios

Test 4xx and 5xx Responses

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

  WeatherApiClient client = new WeatherApiClient(wireMock.getRuntimeInfo().getHttpBaseUrl());
  
  assertThatThrownBy(() -> client.getUser(999))
    .isInstanceOf(UserNotFoundException.class)
    .hasMessageContaining("User not found");
}

@Test
void shouldRetryOnServerError() {
  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 Verification

Verify Request Details and Payload

@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")));
}

Best Practices

  • Use dynamic port to avoid port conflicts in parallel test execution
  • Verify requests to ensure correct API usage
  • Test error scenarios thoroughly
  • Keep stubs focused - one concern per test
  • Reset WireMock between tests automatically via @RegisterExtension
  • Never call real APIs - always stub third-party endpoints

Troubleshooting

WireMock not intercepting requests: Ensure your HTTP client uses the stubbed URL from wireMock.getRuntimeInfo().getHttpBaseUrl().

Port conflicts: Always use wireMockConfig().dynamicPort() to let WireMock choose available port.

References

  • WireMock Official Documentation
  • WireMock Stubs and Mocking
  • JUnit 5 Extensions
Repository
giuseppe-trisciuoglio/developer-kit
Commit

6ecd0d8

Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill