cli-anything-wiremock 实战指南：用 Python CLI 驱动 WireMock 管理桩、校验请求与录制真实流量

cli-anything-wiremock 实战指南用 Python CLI 驱动 WireMock 管理桩、校验请求与录制真实流量【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anythingcli-anything-wiremock是 CLI-Anything 项目为 WireMock HTTP Mock Server 提供的命令行封装它以 WireMock Admin REST API/__admin/为底层把桩映射管理、请求日志校验、状态化场景控制和真实后端流量录制全部收敛为终端子命令既适合开发者在集成测试中快速搭建可控的 HTTP 后端替身也适合 Agent 通过工具调用完成建桩 → 跑被测系统 → 断言请求 → 清理的完整闭环。读完本文你将掌握从安装启动、连接配置到六组核心命令的全部用法并能理解每个命令背后对应的 WireMock Admin API 端点从而把这条 CLI 无缝嵌入你的测试流水线与 Agent 工作流。一、WireMock 与 CLI Harness 的定位WireMock 是一款灵活的 HTTP Mock Server核心用途是在集成测试环境中以可控的 Mock 响应替换真实 HTTP 后端。它对外暴露一套位于/__admin/的 REST Admin API用于管理桩stub、查看已服务的请求、控制基于状态机的场景scenario以及录制来自真实后端的流量。如果直接手写这些 HTTP 调用既繁琐又容易出错于是本项目提供了cli-anything-wiremock一个用 Click 构建的 Python CLI将所有管理端点包装成直觉化的子命令让开发者和 Agent 都能在终端或脚本中完成 WireMock 管理。从源码结构看该模块按职责清晰分层见 wiremock_cli.pyutils/WireMockClientHTTP 客户端封装与输出工具core/StubsManager、RequestsLog、ScenariosManager、RecordingManager、SettingsManager、Session六个核心管理器cli层将上述管理器暴露为stub、request、scenario、record、settings命令组。二、安装与启动 WireMock 服务2.1 安装 CLI在agent-harness目录下以可编辑模式安装即可cd /path/to/agent-harness pip install -e . cli-anything-wiremock --help仓库中的安装定义见 setup.py。2.2 启动 WireMock 独立服务CLI 本身不内嵌 WireMock 服务器需要先启动一个独立的 WireMock 实例。以下是 WIREMOCK.md 提供的几种启动方式下载并启动默认端口 8080curl -fsSL https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/3.3.1/wiremock-standalone-3.3.1.jar \ -o wiremock-standalone.jar java -jar wiremock-standalone.jar --port 8080 --verbose带持久化映射目录启动stub 保存到./wiremock-datajava -jar wiremock-standalone.jar \ --port 8080 \ --root-dir ./wiremock-data \ --verbose以 HTTPS 启动java -jar wiremock-standalone.jar \ --port 8443 \ --https-port 8443 \ --verboseDocker 方式备选docker run -d --name wiremock \ -p 8080:8080 \ wiremock/wiremock:latest三、连接配置环境变量与 CLI 参数所有连接参数既可以通过环境变量设置也可以通过 CLI flag 覆盖。相关实现见 session.py 和 wiremock_cli.pyCLI 层先读取环境变量再允许--host等显式参数覆盖。环境变量CLI Flag默认值说明WIREMOCK_HOST--hostlocalhostWireMock 主机地址WIREMOCK_PORT--port8080WireMock 端口WIREMOCK_SCHEME--schemehttphttp或httpsWIREMOCK_USER--user无Basic Auth 用户名WIREMOCK_PASSWORD--password无Basic Auth 密码WIREMOCK_JSON--jsonfalseJSON 输出模式示例——连接远程 WireMock 实例export WIREMOCK_HOSTwiremock.internal export WIREMOCK_PORT9090 cli-anything-wiremock status从源码看Session.from_env() 负责解析环境变量端口解析失败时回退到 8080auth()方法仅当用户名和密码同时存在时返回 Basic Auth 元组而 WireMockClient 会把连接参数拼装为{scheme}://{host}:{port}/__admin作为所有请求的基址并内置 30 秒默认超时与auth透传。status命令实际是探测GET /__admin/health是否返回 200从而判断服务器存活状态。四、命令组全景CLI 共包含五个命令组加三个顶层命令。以下命令表来自 SKILL.md并在每组之后补充了对应的 Admin API 端点见各core/管理器实现方便你对照排查问题。4.1stub— 管理 HTTP 桩映射命令说明stub list列出所有已注册的桩stub get id按 UUID 获取某个桩的详情stub create json从 JSON 字符串创建桩stub quick M URL S快速建桩METHOD URL STATUS_CODEstub delete id按 UUID 删除桩stub reset将全部桩重置为磁盘默认映射stub save把内存中的桩持久化到磁盘stub import file从 JSON 文件导入桩底层实现对应关系见 stubs.pylist→GET /__admin/mappings支持--limit、--offset分页get→GET /__admin/mappings/{id}create→POST /__admin/mappings支持file前缀从文件读取 JSONquick→ 内部调用quick_stub()把METHOD URL STATUS构造成{request: {method: ..., url: ...}, response: {status: ...}}后再走create。传入--body时还会自动附带Content-Type响应头默认application/jsondelete→DELETE /__admin/mappings/{id}reset→POST /__admin/mappings/resetsave→POST /__admin/mappings/saveimport→POST /__admin/mappings/import。非 JSON 模式下stub list会把每个桩渲染为ID / Name / Method / URL / Status五列表格ID 截断为前 8 位便于阅读stub quick与stub create成功后都会回显新桩的完整 ID。4.2request— 检视已服务的请求命令说明request list列出最近被服务的请求request find pattern查找匹配某个 JSON 模式的请求request count pattern统计匹配某 JSON 模式的请求数量request unmatched列出未命中任何桩的请求即 404request reset清空请求日志底层端点见 requests_log.pylist→GET /__admin/requests支持--limit与since参数find→POST /__admin/requests/findpattern 是一个请求匹配描述对象如{method:GET,url:/api/users}count→POST /__admin/requests/countunmatched→GET /__admin/requests/unmatchedreset→DELETE /__admin/requests。request list的表格视图会展示每次服务事件serveEvent的 ID、方法、URL、响应状态码以及wasMatched标记非常便于快速判断哪个请求没有被桩接住。4.3scenario— 状态化场景管理命令说明scenario list列出所有场景及当前状态scenario set N S将名为 N 的场景设置到状态 Sscenario reset将所有场景重置回初始状态底层端点见 scenarios.pylist→GET /__admin/scenariosset→PUT /__admin/scenarios/{name}/state请求体为{state: ...}场景名会经过 URL 编码quote(name, safe)以防止特殊字符破坏路径reset→POST /__admin/scenarios/reset。scenario list的表格会显示每个场景的 Name、Current State 和 Possible States方便你确认状态机的推进是否符合预期。4.4record— 录制真实后端流量命令说明record start url开始代理并录制到目标 URLrecord stop停止录制并返回捕获到的桩record status检查当前是否在录制record snapshot把内存中的请求快照成桩底层端点见 recording.pystart→POST /__admin/recordings/start请求体{targetBaseUrl: target_url}可通过可重复的--match-header指定需要捕获的请求头内部会构造成captureHeaders映射且caseInsensitive: truestop→POST /__admin/recordings/stopstatus→GET /__admin/recordings/statussnapshot→POST /__admin/recordings/snapshot。record start的原理是让 WireMock 在自身端口上以录制代理模式把请求转发到真实后端同时记录交互停止后即可基于真实 API 的响应自动生成桩映射——这是从真实后端流量快速产出 Mock 数据的标准姿势。4.5settings— 全局设置命令说明settings get获取当前 WireMock 全局设置settings version显示 WireMock 服务器版本底层端点见 settings.pyget→GET /__admin/settingsversion→GET /__admin/version。注意settings get即使非 JSON 模式也直接以 JSON 打印因为设置项是嵌套结构表格难以表达。4.6 顶层命令命令说明status检查 WireMock 是否在运行reset完全重置桩 请求 场景shutdown优雅关闭 WireMock 服务器status探测GET /__admin/health输出✓/✗与运行状态reset调用POST /__admin/reset一次性清空所有状态shutdown调用POST /__admin/shutdown且带有 Click 确认提示。源码里对关闭时服务器主动断开连接导致的ConnectionError做了特殊处理服务端在成功关闭后会立刻断开因此连接异常被当作关闭信号已发送处理不会误报错误。五、关键实操示例以下示例综合 SKILL.md 与 WIREMOCK.md 的完整工作流# 检查连通性 cli-anything-wiremock status # 快速建桩 cli-anything-wiremock stub quick GET /api/users 200 --body [{id:1}] # 完整 JSON 建桩 cli-anything-wiremock stub create { request: {method: POST, url: /api/orders}, response: {status: 201, body: {\id\:99}} } # 校验某个 POST 恰好被调用一次 cli-anything-wiremock --json request count {method:POST,url:/api/orders} # → {count: 1} # 场景推进 cli-anything-wiremock scenario set cart-flow item-added # 录制真实后端 cli-anything-wiremock record start https://api.example.com # ... 向 http://localhost:8080 发请求会被代理并捕获 ... cli-anything-wiremock record stop5.1 桩的批量导入与持久化除了逐条创建CLI 还支持文件级操作非常适合把测试桩固化成仓库文件# 从文件导入文件内容为 {mappings: [...]} 结构 cli-anything-wiremock stub import ./my-stubs.json # 把内存中的桩持久化到磁盘配合 --root-dir 启动参数使用 cli-anything-wiremock stub save # 清空全部桩恢复为磁盘默认 cli-anything-wiremock stub reset5.2 请求校验三板斧request find {method:GET,url:/api/users}拿到所有匹配请求的完整详情request count {method:POST,urlPath:/api/orders}统计次数天然适合做恰好调用一次或零调用的断言request unmatched列出所有未命中桩的请求快速定位 404 来源是排查被测系统调用了错误 URL的首选命令。六、Agent 使用规范机器可读输出与调用约定SKILL 文档对 Agent 场景给出了明确的硬性约定直接关系到工具调用的稳定性6.1 在 Agent 上下文中始终使用--json脚本和 Agent 工具调用中所有命令都应带上--json。JSON 输出按命令类型分化为若干独立的响应类型并非把所有响应包在一个统一信封里# 数据类命令直接返回 WireMock API 原始 JSON 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} # 空操作类命令delete、reset、save返回 # → {status: ok} # 错误返回 # → {status: error, message: Connection refused}顶层status命令的 JSON 结构略有不同返回{status: running|stopped, host: ..., port: N}。这意味着 Agent 在解析结果时需要按命令类型匹配对应的 schema而不是假定统一包裹层。6.2 通过环境变量连接在调用任何命令前设置连接参数即可无需在每次调用中重复传 flagexport WIREMOCK_HOSTlocalhost export WIREMOCK_PORT80806.3 测试验证的标准工作流模式被测系统运行前先建桩cli-anything-wiremock --json stub quick POST /api/payment 200 --body {success:true}运行被测系统此时它的外部 HTTP 依赖会被 WireMock 拦截并返回上述 Mock 响应。校验交互cli-anything-wiremock --json request count {method:POST,url:/api/payment}清理cli-anything-wiremock reset6.4 错误处理约定所有错误都以非零退出码结束方便脚本set -e或 Agent 判断成败--json模式下错误统一返回{status: error, message: ...}成功时返回 WireMock API 原始响应数据类命令或{status: ok}空操作类命令。从 wiremock_cli.py 的实现看每个命令都遵循同一套异常收口逻辑业务异常被try/except捕获后交给error()JSON 模式输出错误对象、人类模式输出到 stderr从而保证 Agent 拿到的机器可读输出始终结构一致。七、从源码看调用链与扩展点如果你需要把这条 CLI 接入自己的测试框架有两点实现事实值得了解命令与端点的一一映射所有子命令都只是对WireMockClientutils/client.py的薄封装。WireMockClient提供get/post/put/delete/patch五类方法统一拼装/__admin前缀、注入auth与timeout任何自定义管理命令都可以直接复用它而不必关心 URL 细节。命令组内的隐藏能力虽然 SKILL 文档只列了公开命令但StubsManager还实现了updatePUT /mappings/{id}与find_by_metadataPOST /mappings/find-by-metadataRequestsLog实现了get与near_misses_unmatchedGET /requests/unmatched/near-missesSettingsManager实现了updatePUT /settings这些方法为在 Python 测试代码中直接驱动管理能力提供了现成入口。测试佐证模块自带的单元测试与端到端测试见 tests/ 下的 test_core.py 与 test_full_e2e.py详细说明见 TEST.md覆盖了核心管理器与完整的建桩 → 请求 → 校验 → 重置链路可以直接作为接入集成测试时的参考蓝本。八、注意事项与适用前提版本前提文档示例基于 WireMock Standalone 3.3.1Admin API 路径/__admin/与请求/响应 schema 以该版本为准不同大版本之间个别端点可能有差异。HTTPS 前提连接 HTTPS 的 WireMock 实例时需设置WIREMOCK_SCHEMEhttps否则 CLI 仍会按http发起请求导致握手失败。持久化前提stub save能否真正落盘取决于 WireMock 启动时是否指定了--root-dir或等价的文件系统后端无持久化目录时保存行为可能退化为内存态。认证前提只有当WIREMOCK_USER与WIREMOCK_PASSWORD同时提供时才会启用 Basic Auth 头单独设置其中一个不会生效。综上cli-anything-wiremock用一套简洁的命令语法把 WireMock 的完整管理面桩、请求、场景、录制、设置、生命周期收敛到了终端配合--json的机器可读约定与稳定的错误模型既降低了开发者在集成测试中手工拼 HTTP 调用的成本也让 Agent 能够以确定性输入 → 结构化输出的方式可靠地操控 Mock 服务器是让所有软件 Agent 原生可操作CLI-Anything 项目理念在测试基础设施上的一个典型落地示例。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考