WireMock Standalone Docker Skill

Overview

unit-test-wiremock-rest-api

When to Use This Skill

• 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

docker-compose.yml

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

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

Step 3: Define API Mappings

wiremock/mappings/

• 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

http://localhost:8080

http://wiremock:8080

Step 6: Test Edge Cases

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

1. Organize mappings by feature: Use subdirectories like

   users/

   ,

   products/

2. Version control mappings: Keep mappings in git for reproducible tests
3. Test all error scenarios: 401, 403, 404, 429, 500, timeouts
4. Reset between test runs:

   curl -X POST http://localhost:8080/__admin/reset

5. 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

references/

• docker-compose.yml

  - Full Docker Compose configuration

• wiremock/mappings/

  - Complete stub examples for all scenarios