giuseppe-trisciuoglio/developer-kit / plugins/developer-kit-java/skills/unit-test-wiremock-rest-api
unit-test-wiremock-rest-api
VerifiedProvides patterns for unit testing external REST APIs using WireMock. Stubs API responses, verifies request details, simulates failures (timeouts, 4xx/5xx errors), and validates HTTP client behavior without real network calls. Use when testing service integrations with external APIs or mocking HTTP endpoints.
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 WireMockExtensionwithdynamicPort() - 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:
@RegisterExtensionresets 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |