wiremock-standalone-docker

WireMock Standalone Docker Skill

Overview

Provides patterns for running WireMock as a standalone Docker container to mock external APIs during integration and end-to-end testing. Runs WireMock as a separate service that simulates real API behavior for testing HTTP clients, retry logic, and error handling.

When to Use

Use when you need to:

• Mock external APIs during integration or end-to-end testing
• Simulate error conditions (timeouts, 5xx, rate limiting) without real services
• Test HTTP client configurations, retry logic, and error handling
• Create portable, reproducible test environments
• Validate API contracts before implementing the real service

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

Step 2: Create Directory Structure

Create the WireMock configuration directories:

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

Step 5: Verify WireMock is Running

Expected: Returns empty array {"mappings":[]} if no stubs loaded, or your stub definitions. If you get connection refused, check that the container is running: docker compose ps

Step 6: Configure HTTP Client

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

Step 7: Test Edge Cases

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

Examples

Example 1: Mock Successful GET Request

Example 2: Mock Server Error

Example 3: Mock Timeout

Example 4: Docker Compose with Application

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 mappings on container restart

Troubleshooting

Requests don't match stubs? Check what WireMock received: curl http://localhost:8080/__admin/requests — shows unmatched requests with details about what was actually sent.

Stub file not loading? Verify file location: place JSON stubs in wiremock/mappings/ and response files in wiremock/__files/. Check file permissions.

Connection refused errors? Run docker compose ps to verify the container is running. Check port conflicts with lsof -i :8080.

References

See references/ for complete examples:

• docker-compose.yml - Full Docker Compose configuration
• wiremock/mappings/ - Complete stub examples for all scenarios