WireMock

intermediate

API mocking and service virtualization.

Overview

WireMock is a powerful API mocking and service virtualization tool originally developed for Java applications but now available as a standalone service. It enables developers and testers to create realistic HTTP service stubs that can simulate real APIs with complex behaviors, including response delays, fault conditions, and stateful interactions. WireMock has become essential in modern software development for testing microservices, enabling parallel development, and creating predictable test environments. This Docker configuration deploys WireMock as a containerized service with persistent volume mappings for stub definitions and static response files. The setup maps local directories for both JSON mapping files that define API endpoints and response behaviors, plus a files directory for serving static content. The verbose logging mode provides detailed request/response information for debugging mock behaviors during development. Development teams building microservices architectures, QA engineers creating comprehensive test suites, and DevOps professionals setting up CI/CD pipelines will find this configuration particularly valuable. The containerized WireMock instance allows teams to maintain consistent API mocks across different environments while enabling rapid iteration on service contracts without dependency on actual backend services.

Key Features

HTTP request matching with URL patterns, headers, query parameters, and request body content
Response templating with dynamic content generation using Handlebars syntax
Request recording and playback functionality to capture real API interactions
Stateful behavior simulation with scenarios for multi-step API workflows
Fault injection capabilities including random delays, connection resets, and HTTP error responses
Admin REST API for runtime stub creation and management without file system access
JSON-based stub definitions with support for complex request matching rules
Static file serving for binary content, images, and documents through __files directory

Common Use Cases

1Frontend development teams mocking backend APIs that are still under development
2Integration testing of microservices without dependencies on external third-party APIs
3Performance testing with controlled response times and failure scenarios
4Contract testing between API consumers and providers during parallel development
5Demo environments where real services are unavailable or expensive to run
6CI/CD pipelines requiring predictable API responses for automated testing
7Training and development environments simulating production API behaviors

Prerequisites

Docker Engine 20.10+ and Docker Compose V2 for container orchestration
Minimum 512MB RAM allocation for WireMock JVM and request processing
Port 8080 available on host system for WireMock HTTP interface
Local filesystem permissions for creating ./wiremock/mappings and ./wiremock/__files directories
Basic understanding of HTTP request/response structure and JSON formatting
Familiarity with REST API concepts for creating effective mock definitions

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  wiremock: 
3    image: wiremock/wiremock:latest
4    container_name: wiremock
5    restart: unless-stopped
6    volumes: 
7      - ./wiremock/mappings:/home/wiremock/mappings
8      - ./wiremock/__files:/home/wiremock/__files
9    ports: 
10      - "8080:8080"
11    command: --verbose

.env Template

.env

1# Create stubs in ./wiremock/mappings

Usage Notes

1Docs: https://wiremock.org/docs/
2API at http://localhost:8080 - serves mocked endpoints
3Admin API at /__admin for dynamic stub creation
4Define stubs in ./wiremock/mappings as JSON files
5Record mode: --record-mappings to capture real API responses
6Fault injection, delays, and stateful scenarios supported

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  wiremock:
5    image: wiremock/wiremock:latest
6    container_name: wiremock
7    restart: unless-stopped
8    volumes:
9      - ./wiremock/mappings:/home/wiremock/mappings
10      - ./wiremock/__files:/home/wiremock/__files
11    ports:
12      - "8080:8080"
13    command: --verbose
14EOF
15
16# 2. Create the .env file
17cat > .env << 'EOF'
18# Create stubs in ./wiremock/mappings
19EOF
20
21# 3. Start the services
22docker compose up -d
23
24# 4. View logs
25docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/wiremock/run | bash

Troubleshooting

WireMock returns 404 for all requests: Verify JSON mapping files exist in ./wiremock/mappings with valid request matching patterns
Container fails to start with permission denied: Ensure Docker has read/write access to local wiremock directories or adjust file ownership
Admin API returns connection refused: Check that requests target /__admin path and port 8080 is properly mapped
Mapping files not loading on container restart: Validate JSON syntax in mapping files using a JSON linter before mounting
Static file responses return 404: Confirm files are placed in ./wiremock/__files directory and referenced correctly in mapping bodyFileName
Request matching too broad or narrow: Review urlPattern versus urlPathPattern usage and header matching case sensitivity

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

wiremock

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download