wiremock-standalone-docker

Q: How do I install wiremock-standalone-docker?

Run npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill wiremock-standalone-docker in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/wiremock-standalone-docker/ (personal) or .claude/skills/wiremock-standalone-docker/ (project).

by giuseppe-trisciuoglioDevOps & Cloud

Provides patterns and configurations for running WireMock as a standalone Docker container. Generates mock HTTP endpoints, creates stub mappings for testing, validates integration scenarios, and simulates error conditions. Use when you need to mock APIs, create a mock server, stub external services, simulate third-party APIs, or fake API responses for integration testing.

Installs: 3.4K
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill wiremock-standalone-docker

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads wiremock-standalone-docker automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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 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: Verify WireMock is Running

curl http://localhost:8080/__admin/mappings

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

{
  "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 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

FAQ

What does the wiremock-standalone-docker skill do?

How do I install wiremock-standalone-docker?

Run npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill wiremock-standalone-docker in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/wiremock-standalone-docker/ (personal) or .claude/skills/wiremock-standalone-docker/ (project).

Which AI agents can use wiremock-standalone-docker?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is wiremock-standalone-docker safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains wiremock-standalone-docker?

It is published by giuseppe-trisciuoglio in giuseppe-trisciuoglio/developer-kit. It has 3,406 recorded installs.