giuseppe-trisciuoglio/developer-kit

unit-test-wiremock-rest-api

Provides patterns for unit testing external REST APIs using WireMock.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill unit-test-wiremock-rest-api

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

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

xml
<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

java
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

Related by task

from this repository

More skills

All skills
giuseppe-trisciuoglio
Community

drizzle-orm-patterns

Provides comprehensive Drizzle ORM patterns for schema definition, CRUD operations, relations, queries, transactions, and migrations. Proactively use for any Drizzle ORM development including defining database schemas, writing type-safe queries, implementing relations, managing transactions, and setting up migrations with Drizzle Kit. Supports PostgreSQL, MySQL, SQLite, MSSQL, and CockroachDB.

1h installs
3
GitHub stars
372
Updated
Sep 10
giuseppe-trisciuoglio
Community

tailwind-css-patterns

Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.

1h installs
1
GitHub stars
372
Updated
Sep 10
giuseppe-trisciuoglio
Community

dynamodb-toolbox-patterns

Provides TypeScript patterns for DynamoDB-Toolbox v2 including schema/table/entity modeling, .build() command workflow, query/scan access patterns, batch and transaction operations, and single-table design with computed keys. Use when implementing type-safe DynamoDB access layers with DynamoDB-Toolbox v2 in TypeScript services or serverless applications.

1h installs
1
GitHub stars
371
Updated
Sep 10
giuseppe-trisciuoglio
Community

spring-boot-dependency-injection

Provides dependency injection patterns for Spring Boot projects, including constructor-first design, optional collaborator handling, bean selection, and wiring validation. Use when creating services and configurations, replacing field injection, or troubleshooting ambiguous or fragile Spring wiring.

1h installs
1
GitHub stars
371
Updated
Sep 10