unit-test-wiremock-rest-api

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, 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 for query params.