wiremock-standalone-docker

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WireMock Standalone Docker Skill

WireMock独立Docker技能

Overview

概述

This skill provides comprehensive patterns for running WireMock as a standalone Docker container to mock external third-party APIs during integration and end-to-end testing phases. Unlike the

unit-test-wiremock-rest-api

skill which embeds WireMock within Java unit tests, this skill focuses on running WireMock as a separate service that simulates real API behavior.

本技能提供了在集成测试和端到端测试阶段，将WireMock作为独立Docker容器运行以模拟外部第三方API的完整方案。与在Java单元测试中嵌入WireMock的

unit-test-wiremock-rest-api

技能不同，本技能专注于将WireMock作为独立服务运行，模拟真实API行为。

When to Use This Skill

适用场景

Use this skill when:

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

在以下场景中使用本技能：

为集成测试设置模拟服务器
无需修改测试代码即可模拟第三方API响应
测试错误场景（超时、5xx错误、速率限制）
运行带有外部服务依赖的端到端测试
创建可移植、可复现的测试环境
测试HTTP客户端配置和重试逻辑
在真实服务实现前演示API契约

Instructions

操作步骤

Step 1: Set Up Docker Compose

步骤1：配置Docker Compose

Create a

docker-compose.yml

with WireMock 3.5.2, port mapping, and volume mounts for mappings and files:

yaml

version: "3.8"
services:
  wiremock:
    image: wiremock/wiremock:3.5.2
    ports:
      - "8080:8080"
    volumes:
      - ./wiremock:/home/wiremock
    command: ["--global-response-templating"]

创建包含WireMock 3.5.2、端口映射以及映射和文件卷挂载的

docker-compose.yml

文件：

yaml

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

步骤2：创建目录结构

Create the WireMock configuration directories:

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

创建WireMock配置目录：

wiremock/
├── mappings/   # JSON存根定义
└── __files/   # 响应体文件

Step 3: Define API Mappings

步骤3：定义API映射

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

在

wiremock/mappings/

目录中为每个场景创建JSON存根文件：

成功场景：返回200状态码和JSON响应体
未找到：返回404状态码
服务器错误：返回500状态码
超时：使用
```
fixedDelayMilliseconds
```
配置
速率限制：返回429状态码并带有Retry-After响应头

Step 4: Start WireMock

步骤4：启动WireMock

bash

docker compose up -d

bash

docker compose up -d

Step 5: Configure HTTP Client

步骤5：配置HTTP客户端

Point your application to

http://localhost:8080

(or

http://wiremock:8080

in Docker network) instead of the real API.

将应用的API地址指向

http://localhost:8080

（或在Docker网络中使用

http://wiremock:8080

），而非真实API地址。

Step 6: Test Edge Cases

步骤6：测试边缘场景

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

务必测试以下场景：200、400、401、403、404、429、500、超时、格式错误的响应。

Examples

示例

Example 1: Mock Successful GET Request

示例1：模拟成功的GET请求

json

{
  "request": { "method": "GET", "url": "/api/users/123" },
  "response": {
    "status": 200,
    "jsonBody": { "id": 123, "name": "Mario Rossi" }
  }
}

json

{
  "request": { "method": "GET", "url": "/api/users/123" },
  "response": {
    "status": 200,
    "jsonBody": { "id": 123, "name": "Mario Rossi" }
  }
}

Example 2: Mock Server Error

示例2：模拟服务器错误

json

{
  "request": { "method": "GET", "url": "/api/error" },
  "response": { "status": 500, "body": "Internal Server Error" }
}

json

{
  "request": { "method": "GET", "url": "/api/error" },
  "response": { "status": 500, "body": "Internal Server Error" }
}

Example 3: Mock Timeout

示例3：模拟超时

json

{
  "request": { "method": "GET", "url": "/api/slow" },
  "response": {
    "status": 200,
    "fixedDelayMilliseconds": 5000,
    "jsonBody": { "message": "delayed" }
  }
}

json

{
  "request": { "method": "GET", "url": "/api/slow" },
  "response": {
    "status": 200,
    "fixedDelayMilliseconds": 5000,
    "jsonBody": { "message": "delayed" }
  }
}

Example 4: Docker Compose with Application

示例4：包含应用的Docker Compose配置

yaml

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

yaml

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

按功能组织映射：使用
```
users/
```
、
```
products/
```
等子目录
版本控制映射文件：将映射文件存入git以实现可复现的测试
测试所有错误场景：401、403、404、429、500、超时

测试运行间重置：执行

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

使用描述性文件名：例如

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

确保端口8080可用，或映射到其他端口
运行多个容器时配置Docker网络
启用
```
--global-response-templating
```
以支持动态响应
WireMock会在容器重启时重置

References

参考资料

See

references/

for complete examples:

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

查看

references/

目录获取完整示例：

```
docker-compose.yml
```
- 完整的Docker Compose配置
```
wiremock/mappings/
```
- 所有场景的完整存根示例