cli-anything-wiremock

概述

cli-anything-wiremock 是一个封装 WireMock Admin REST API（/__admin/）的命令行界面。它让 Agent 和开发者能够管理 HTTP stub 映射、检查已服务的请求、控制有状态场景，以及录制真实后端流量——这一切都可以在终端中或通过 Agent 工具调用完成。

WireMock 常用于集成测试环境，用可控的模拟响应替代真实的 HTTP 后端。

命令组

stub — 管理 HTTP stub 映射

命令	描述
stub list	列出所有已注册的 stub
stub get <id>	根据 UUID 获取特定 stub 的详细信息
stub create <json>	从 JSON 字符串创建 stub
stub quick M URL S	快速创建 stub：METHOD URL STATUS_CODE
stub delete <id>	根据 UUID 删除 stub
stub reset	将所有 stub 重置为磁盘上的默认值
stub save	将内存中的 stub 持久化到磁盘
stub import <file>	从 JSON 文件导入 stub

request — 检查已服务的请求

命令	描述
request list	列出最近的已服务请求
request find <pattern>	查找匹配 JSON 模式的请求
request count <pattern>	统计匹配 JSON 模式的请求数量
request unmatched	列出未匹配任何 stub 的请求（404）
request reset	清空请求日志

scenario — 有状态场景管理

命令	描述
scenario list	列出所有场景及当前状态
scenario set N S	将场景 NAME 设置为 STATE
scenario reset	将所有场景重置为初始状态

record — 录制来自真实后端的流量

命令	描述
record start <url>	开始代理并录制到 TARGET_URL
record stop	停止录制，返回捕获的 stub
record status	检查当前是否正在录制
record snapshot	将内存中的请求快照为 stub

settings — 全局服务器设置

命令	描述
settings get	获取当前全局 WireMock 设置
settings version	显示 WireMock 服务器版本

顶层命令

命令	描述
status	检查 WireMock 是否正在运行
reset	完全重置：stub + 请求 + 场景
shutdown	优雅关闭 WireMock 服务器

关键示例

# Check connectivity
cli-anything-wiremock status

# Create a stub using quick form
cli-anything-wiremock stub quick GET /api/users 200 --body '[{"id":1}]'

# Create a stub using full JSON
cli-anything-wiremock stub create '{
  "request": {"method": "POST", "url": "/api/orders"},
  "response": {"status": 201, "body": "{\"id\":99}"}
}'

# Verify a POST was made exactly once
cli-anything-wiremock --json request count '{"method":"POST","url":"/api/orders"}'
# → {"count": 1}

# Scenario: advance state
cli-anything-wiremock scenario set "cart-flow" "item-added"

# Record a real backend
cli-anything-wiremock record start https://api.example.com
# ... make requests ...
cli-anything-wiremock record stop

Agent 指南

在 Agent 场景中始终使用 --json

在脚本或 Agent 工具调用中的所有调用都应使用 --json。JSON 输出因命令类型而异（这些是不同的响应类型，而不是包装所有响应的信封）：

# Data commands return raw WireMock API JSON directly:
cli-anything-wiremock --json stub quick GET /api/hello 200 --body '{"hello":"world"}'
# → {"id": "abc-123", "request": {...}, "response": {...}, ...}

cli-anything-wiremock --json stub list
# → {"mappings": [...], "total": N}

# Void commands (delete, reset, save) return:
# → {"status": "ok"}

# Errors return:
# → {"status": "error", "message": "Connection refused"}

通过环境变量连接

在调用任何命令之前，通过环境变量设置连接参数：

export WIREMOCK_HOST=localhost
export WIREMOCK_PORT=8080

测试验证的工作流模式

1. 在运行被测系统之前设置桩：

   cli-anything-wiremock --json stub quick POST /api/payment 200 --body '{"success":true}'
   

2. 运行被测系统。
3. 验证交互：

   cli-anything-wiremock --json request count '{"method":"POST","url":"/api/payment"}'
   

4. 清理：

   cli-anything-wiremock reset
   

错误处理

所有错误均返回非零退出码。在 --json 模式下，错误返回 {"status": "error", "message": "..."}。成功则返回原始的 WireMock API 响应。