Unit Test Wiremock Rest Api
Stub external REST APIs with WireMock so Spring or Java clients can be unit-tested for success, 4xx, 5xx, and request-body contracts without hitting real services.
Overview
Unit Test WireMock REST API is an agent skill for the Ship phase that teaches WireMock stubbing and verification for REST client unit tests including 4xx, 5xx, and JSON body checks.
Install
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-wiremock-rest-apiWhat is this skill?
- 404 and 500 error-path tests with assertThatThrownBy and domain exceptions
- Request body and JSON path verification on outbound POST stubs
- Runtime base URL wiring via WireMockExtension getHttpBaseUrl for ApiClient tests
- Patterns for matching headers and structured error JSON bodies
- Advanced WireMock scenarios beyond happy-path GET stubs
Adoption & trust: 1.2k installs on skills.sh; 271 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your Java service calls external HTTP APIs but you have no reliable way to test failure handling and request shapes without live endpoints.
Who is it for?
Solo builders shipping JVM services with HTTP clients who need CI-friendly contract tests before launch.
Skip if: Pure frontend apps, teams standardizing on Testcontainers-only integration tests with no WireMock, or non-HTTP protocols.
When should I use this skill?
Writing or extending JUnit tests for HTTP API clients that need stubbed 4xx/5xx responses and request verification.
What do I get? / Deliverables
You get JUnit tests that stub REST partners locally, assert exceptions on error statuses, and verify outbound request bodies match your contract.
- WireMock stub and verify test methods
- Error-path and POST body assertion examples
Recommended Skills
Journey fit
WireMock tests belong in Ship when you harden integrations before production deploy, not during initial feature coding. Testing is the canonical shelf because the skill focuses on isolated HTTP stubbing and verification, not implementing API handlers.
How it compares
Focused WireMock REST recipes rather than a full Spring Boot Test slice or end-to-end Playwright flow.
Common Questions / FAQ
Who is unit-test-wiremock-rest-api for?
Java developers and indie SaaS builders who test API clients against WireMock instead of production or staging URLs.
When should I use unit-test-wiremock-rest-api?
In Ship testing when adding coverage for downstream REST failures, POST payload verification, or hardening an ApiClient before you tag a release.
Is unit-test-wiremock-rest-api safe to install?
Review the Security Audits panel on this Prism page and the skill source in developer-kit; the examples are test code only and should not require production secrets.
SKILL.md
READMESKILL.md - Unit Test Wiremock Rest Api
# WireMock Advanced Examples Additional patterns for complex WireMock testing scenarios. ## Error Scenario Testing (4xx/5xx) ```java @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 ```java @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 ```java @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 ```java @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) ```java @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"))); } ``` --- name: unit-test-wiremock-rest-api description: Provides 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. allowed-tools: Read, Write, Bash, Glob, Grep --- # 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,