cli-anything-wiremock

概述

cli-anything-wiremock 是一個指令列介面，用來包裝 WireMock 管理 REST API (/__admin/)。它允許代理程式與開發者從終端機或代理程式工具呼叫管理 HTTP 存根對應、檢查已處理的請求、控制有狀態的情境，以及錄製真實後端流量。

WireMock 常用於整合測試環境中，以可控的模擬回應取代真實的 HTTP 後端。

指令群組

stub — 管理 HTTP 存根對應

指令	描述
stub list	列出所有已註冊的存根
stub get <id>	根據 UUID 取得特定存根的詳細資訊
stub create <json>	透過 JSON 字串建立存根
stub quick M URL S	快速建立存根：方法 URL 狀態碼
stub delete <id>	根據 UUID 刪除存根
stub reset	將所有存根重設為磁碟上的預設值
stub save	將記憶體中的存根持久化到磁碟
stub import <file>	從 JSON 檔案匯入存根

request — 檢查已處理的請求

指令	描述
request list	列出最近處理的請求
request find <pattern>	尋找符合 JSON 模式的請求
request count <pattern>	計算符合 JSON 模式的請求數量
request unmatched	列出未匹配任何存根的請求（404）
request reset	清除請求日誌

scenario — 有狀態的情境管理

指令	描述
scenario list	列出所有情境與目前狀態
scenario set N S	將情境 NAME 設為 STATE
scenario reset	將所有情境重設為初始狀態

record — 從真實後端錄製流量

指令	描述
record start <url>	啟動代理 + 錄製至 TARGET_URL
record stop	停止錄製，回傳捕獲的存根
record status	檢查目前是否正在錄製
record snapshot	將記憶體中的請求快照為存根

settings — 全域伺服器設定

指令	描述
settings get	取得目前的 WireMock 全域設定
settings version	顯示 WireMock 伺服器版本

頂層指令

指令	描述
status	檢查 WireMock 是否正在執行
reset	完整重設：存根 + 請求 + 情境
shutdown	優雅地關閉 WireMock 伺服器

關鍵範例

# 檢查連線
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
# ... 發送請求 ...
cli-anything-wiremock record stop

代理程式指引

在代理程式環境中務必使用 --json

在腳本或代理程式工具呼叫中，請使用 --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}

# Void 指令（delete, reset, save）會回傳：
# → {"status": "ok"}

# 錯誤會回傳：
# → {"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 回應。