WireMock Standalone Docker Skill

Overview

This skill provides comprehensive patterns for running WireMock as a standalone Docker container to mock external third-party APIs during integration and end-to-end testing phases. Unlike the unit-test-wiremock-rest-api skill which embeds WireMock within Java unit tests, this skill focuses on running WireMock as a separate service that simulates real API behavior.

When to Use This Skill

Use this skill when:

• Setting up mock servers for integration testing

• Simulating third-party API responses without modifying test code

• Testing error scenarios (timeouts, 5xx errors, rate limiting)

• Running end-to-end tests with external service dependencies

• Creating portable, reproducible test environments

• Testing HTTP client configurations and retry logic

• Demonstrating API contracts before real service implementation

Instructions

Step 1: Set Up Docker Compose

Create a docker-compose.yml with WireMock 3.5.2, port mapping, and volume mounts for mappings and files:

version: "3.8" services: wiremock: image: wiremock/wiremock:3.5.2 ports: - "8080:8080" volumes: - ./wiremock:/home/wiremock command: ["--global-response-templating"]

Step 2: Create Directory Structure

Create the WireMock configuration directories:

wiremock/ ├── mappings/ # JSON stub definitions └── __files/ # Response body files

Step 3: Define API Mappings

Create JSON stub files in wiremock/mappings/ for each scenario:

• Success: Return 200 with JSON body

• Not Found: Return 404

• Server Error: Return 500

• Timeout: Use fixedDelayMilliseconds

• Rate Limit: Return 429 with Retry-After header

Step 4: Start WireMock

docker compose up -d

Step 5: Configure HTTP Client

Point your application to http://localhost:8080 (or http://wiremock:8080 in Docker network) instead of the real API.

Step 6: Test Edge Cases

Always test: 200, 400, 401, 403, 404, 429, 500, timeouts, malformed responses.

Examples

Example 1: Mock Successful GET Request

{ "request": { "method": "GET", "url": "/api/users/123" }, "response": { "status": 200, "jsonBody": { "id": 123, "name": "Mario Rossi" } } }

Example 2: Mock Server Error

{ "request": { "method": "GET", "url": "/api/error" }, "response": { "status": 500, "body": "Internal Server Error" } }

Example 3: Mock Timeout

{ "request": { "method": "GET", "url": "/api/slow" }, "response": { "status": 200, "fixedDelayMilliseconds": 5000, "jsonBody": { "message": "delayed" } } }

Example 4: Docker Compose with Application

services: wiremock: image: wiremock/wiremock:3.5.2 ports: - "8080:8080" volumes: - ./wiremock:/home/wiremock

app: build: . environment: - API_BASE_URL=http://wiremock:8080 depends_on: - wiremock

Best Practices

• Organize mappings by feature: Use subdirectories like users/ , products/

• Version control mappings: Keep mappings in git for reproducible tests

• Test all error scenarios: 401, 403, 404, 429, 500, timeouts

• Reset between test runs: curl -X POST http://localhost:8080/__admin/reset

• Use descriptive file names: get-user-success.json , post-user-error.json

Constraints and Warnings

• Ensure port 8080 is available or map to a different port

• Configure Docker networking when running multiple containers

• Enable --global-response-templating for dynamic responses

• WireMock resets on container restart

References

See references/ for complete examples:

• docker-compose.yml

• Full Docker Compose configuration

• wiremock/mappings/

• Complete stub examples for all scenarios