How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill wiremock-standalone-dockerBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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:
- "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 filesStep 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 -dStep 5: Verify WireMock is Running
curl http://localhost:8080/__admin/mappingsExpected: 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
{
"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:
- wiremockBest 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-templatingfor 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 configurationwiremock/mappings/- Complete stub examples for all scenarios



