測試

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 完整測試工具組（套件、live、Docker）：測試
• 更新與 Plugin 套件驗證：測試更新與 Plugin
• pnpm test:force: 終止任何仍占用預設控制埠的殘留 gateway 行程，然後使用隔離的 Gateway 埠執行完整 Vitest 套件，讓伺服器測試不會與正在執行的執行個體衝突。當先前的 Gateway 執行讓埠 18789 被占用時使用此指令。
• pnpm test:coverage: 使用 V8 覆蓋率（透過 vitest.unit.config.ts）執行單元套件。這是預設單元路徑的覆蓋率閘門，不是整個 repo 的全檔案覆蓋率。門檻為 70% 行/函式/陳述式，以及 55% 分支。由於 coverage.all 為 false，且預設路徑將覆蓋率 include 範圍限定在具有相鄰來源檔案的非快速單元測試，此閘門會衡量此路徑擁有的來源，而不是它碰巧載入的每個遞移匯入。
• pnpm test:coverage:changed: 只針對自 origin/main 以來已變更的檔案執行單元覆蓋率。
• pnpm test:changed: 低成本的智慧變更測試執行。它會從直接測試編輯、相鄰的 *.test.ts 檔案、明確來源對應，以及本機匯入圖執行精準目標。寬泛/設定/套件變更會被略過，除非它們能對應到精準測試。
• OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed: 明確的寬泛變更測試執行。當測試框架/設定/套件編輯應回退到 Vitest 較寬泛的變更測試行為時使用。
• pnpm changed:lanes: 顯示相對於 origin/main 的 diff 觸發的架構路徑。
• pnpm check:changed: 針對相對於 origin/main 的 diff 執行智慧變更檢查閘門。它會為受影響的架構路徑執行型別檢查、lint 和 guard 指令，但不會執行 Vitest 測試。請使用 pnpm test:changed 或明確的 pnpm test <target> 作為測試證明。
• pnpm test: 將明確的檔案/目錄目標路由到範圍化的 Vitest 路徑。未指定目標的執行會使用固定分片群組，並展開到 leaf 設定以供本機平行執行；Plugin 群組一律展開到個別 Plugin 的分片設定，而不是一個龐大的根專案行程。
• 測試包裝器執行結束時會有簡短的 [test] passed|failed|skipped ... in ... 摘要。Vitest 自己的耗時行仍保留為每個分片的詳細資訊。
• 共享 OpenClaw 測試狀態：當測試需要隔離的 HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH、設定 fixture、工作區、agent 目錄或 auth-profile store 時，請從 Vitest 使用 src/test-utils/openclaw-test-state.ts。
• 行程 E2E 輔助工具：當 Vitest 行程層級 E2E 測試需要執行中的 Gateway、CLI env、log 擷取，以及集中清理時，請使用 test/helpers/openclaw-test-instance.ts。
• Docker/Bash E2E 輔助工具：source scripts/lib/docker-e2e-image.sh 的路徑可以將 docker_e2e_test_state_shell_b64 <label> <scenario> 傳入容器，並用 scripts/lib/openclaw-e2e-instance.sh 解碼；多 home 腳本可以傳入 docker_e2e_test_state_function_b64，並在每個流程中呼叫 openclaw_test_state_create <label> <scenario>。較低階的呼叫者可以使用 scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name> 取得容器內 shell 片段，或使用 node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json 取得可 source 的主機 env 檔。create 前的 -- 可避免較新的 Node runtime 將 --env-file 視為 Node flag。會啟動 Gateway 的 Docker/Bash 路徑可以在容器內 source scripts/lib/openclaw-e2e-instance.sh，用於 entrypoint 解析、mock OpenAI 啟動、Gateway 前景/背景啟動、就緒探測、狀態 env 匯出、log dump，以及行程清理。
• 完整、Plugin，以及 include-pattern 分片執行會更新 .artifacts/vitest-shard-timings.json 中的本機時間資料；後續整個設定的執行會使用這些時間來平衡慢速與快速分片。Include-pattern CI 分片會將分片名稱附加到時間 key，這會讓篩選後的分片時間保持可見，而不取代整個設定的時間資料。設定 OPENCLAW_TEST_PROJECTS_TIMINGS=0 可忽略本機時間 artifact。
• 選定的 plugin-sdk 和 commands 測試檔案現在會路由到專用的輕量路徑，這些路徑只保留 test/setup.ts，並讓 runtime-heavy 案例留在既有路徑。
• 具有相鄰測試的來源檔案會先對應到該相鄰測試，再回退到較寬的目錄 glob。src/channels/plugins/contracts/test-helpers、src/plugin-sdk/test-helpers 和 src/plugins/contracts 下的輔助工具編輯，會使用本機匯入圖來執行匯入它們的測試，而不是在依賴路徑精準時寬泛執行每個分片。
• auto-reply 現在也拆分為三個專用設定（core、top-level、reply），因此 reply 測試框架不會主導較輕量的 top-level 狀態/token/輔助工具測試。
• 基礎 Vitest 設定現在預設為 pool: "threads" 和 isolate: false，並在整個 repo 設定中啟用共享的非隔離 runner。
• pnpm test:channels 會執行 vitest.channels.config.ts。
• pnpm test:extensions 和 pnpm test extensions 會執行所有 Plugin 分片。重型頻道 Plugin、瀏覽器 Plugin，以及 OpenAI 會作為專用分片執行；其他 Plugin 群組維持批次處理。使用 pnpm test extensions/<id> 執行單一內建 Plugin 路徑。
• pnpm test:perf:imports: 啟用 Vitest 匯入耗時 + 匯入明細報告，同時仍對明確檔案/目錄目標使用範圍化路徑路由。
• pnpm test:perf:imports:changed: 相同的匯入 profiling，但只針對自 origin/main 以來已變更的檔案。
• pnpm test:perf:changed:bench -- --ref <git-ref> 會針對相同已提交 git diff，將路由後的 changed-mode 路徑與原生根專案執行進行 benchmark。
• pnpm test:perf:changed:bench -- --worktree 會在不先提交的情況下，針對目前 worktree 變更集進行 benchmark。
• pnpm test:perf:profile:main: 為 Vitest 主執行緒寫入 CPU profile（.artifacts/vitest-main-profile）。
• pnpm test:perf:profile:runner: 為單元 runner 寫入 CPU + heap profile（.artifacts/vitest-runner-profile）。
• pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json: 逐一序列執行每個完整套件 Vitest leaf 設定，並寫入分組耗時資料以及每個設定的 JSON/log artifact。Test Performance Agent 會在嘗試修復慢速測試前，使用此作為基準。
• pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json: 在以效能為重點的變更後比較分組報告。
• Gateway 整合：透過 OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test 或 pnpm test:gateway 選擇性啟用。
• pnpm test:e2e: 執行 Gateway 端對端煙霧測試（多執行個體 WS/HTTP/node 配對）。預設在 vitest.e2e.config.ts 中使用 threads + isolate: false 搭配自適應 workers；可用 OPENCLAW_E2E_WORKERS=<n> 調整，並設定 OPENCLAW_E2E_VERBOSE=1 取得詳細 log。
• pnpm test:live: 執行 provider live tests（minimax/zai）。需要 API keys 和 LIVE=1（或 provider-specific *_LIVE_TEST=1）才能取消跳過。
• pnpm test:docker:all: 建置共享的 live-test 映像檔，將 OpenClaw 一次打包為 npm tarball，建置/重用一個裸 Node/Git runner 映像檔，以及一個會把該 tarball 安裝到 /app 的功能映像檔，然後透過加權 scheduler 以 OPENCLAW_SKIP_DOCKER_BUILD=1 執行 Docker 煙霧路徑。裸映像檔（OPENCLAW_DOCKER_E2E_BARE_IMAGE）用於 installer/update/plugin-dependency 路徑；這些路徑會掛載預先建置的 tarball，而不是使用複製的 repo 來源。功能映像檔（OPENCLAW_DOCKER_E2E_FUNCTIONAL_IMAGE）用於一般建置後 app 功能路徑。scripts/package-openclaw-for-docker.mjs 是唯一的本機/CI 套件 packer，並會在 Docker 使用前驗證 tarball 和 dist/postinstall-inventory.json。Docker 路徑定義位於 scripts/lib/docker-e2e-scenarios.mjs；planner 邏輯位於 scripts/lib/docker-e2e-plan.mjs；scripts/test-docker-all.mjs 會執行選定計畫。node scripts/test-docker-all.mjs --plan-json 會輸出由 scheduler 擁有的 CI 計畫，內容包含選定路徑、映像檔種類、套件/live-image 需求、狀態情境，以及憑證檢查，而不會建置或執行 Docker。OPENCLAW_DOCKER_ALL_PARALLELISM=<n> 控制行程 slot，預設為 10；OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=<n> 控制 provider-sensitive tail pool，預設為 10。重型路徑上限預設為 OPENCLAW_DOCKER_ALL_LIVE_LIMIT=9、OPENCLAW_DOCKER_ALL_NPM_LIMIT=10 和 OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7；provider 上限預設為每個 provider 一個重型路徑，透過 OPENCLAW_DOCKER_ALL_LIVE_CLAUDE_LIMIT=4、OPENCLAW_DOCKER_ALL_LIVE_CODEX_LIMIT=4 和 OPENCLAW_DOCKER_ALL_LIVE_GEMINI_LIMIT=4。較大的主機可使用 OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT 或 OPENCLAW_DOCKER_ALL_DOCKER_LIMIT。如果某個路徑在低平行度主機上超過有效權重或資源上限，它仍可從空 pool 啟動，並會單獨執行直到釋放容量。路徑啟動預設錯開 2 秒，以避免本機 Docker daemon 建立風暴；可用 OPENCLAW_DOCKER_ALL_START_STAGGER_MS=<ms> 覆寫。runner 預設會預檢 Docker、清理陳舊的 OpenClaw E2E 容器、每 30 秒輸出 active-lane 狀態、在相容路徑之間共享 provider CLI tool caches、預設重試一次暫時性 live-provider 失敗（OPENCLAW_DOCKER_ALL_LIVE_RETRIES=<n>），並將路徑時間儲存在 .artifacts/docker-tests/lane-timings.json，供後續執行依最長優先排序。使用 OPENCLAW_DOCKER_ALL_DRY_RUN=1 可在不執行 Docker 的情況下列印路徑 manifest，使用 OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=<ms> 可調整狀態輸出，或使用 OPENCLAW_DOCKER_ALL_TIMINGS=0 停用時間重用。使用 OPENCLAW_DOCKER_ALL_LIVE_MODE=skip 只執行確定性/本機路徑，或使用 OPENCLAW_DOCKER_ALL_LIVE_MODE=only 只執行 live-provider 路徑；套件別名為 pnpm test:docker:local:all 和 pnpm test:docker:live:all。Live-only 模式會將 main 和 tail live 路徑合併為一個最長優先 pool，讓 provider bucket 可以一起打包 Claude、Codex 和 Gemini 工作。除非設定 OPENCLAW_DOCKER_ALL_FAIL_FAST=0，runner 會在第一次失敗後停止排程新的 pooled 路徑，且每個路徑都有 120 分鐘 fallback timeout，可用 OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS 覆寫；選定的 live/tail 路徑使用更嚴格的每路徑上限。CLI backend Docker 設定指令有自己的 timeout，透過 OPENCLAW_LIVE_CLI_BACKEND_SETUP_TIMEOUT_SECONDS（預設 180）。每路徑 log、summary.json、failures.json 和階段時間會寫入 .artifacts/docker-tests/<run-id>/；使用 pnpm test:docker:timings <summary.json> 檢查慢速路徑，並使用 pnpm test:docker:rerun <run-id|summary.json|failures.json> 列印低成本的精準重新執行指令。
• pnpm test:docker:browser-cdp-snapshot: 建置以 Chromium 為後端的來源 E2E 容器，啟動原始 CDP 加上隔離 Gateway，執行 browser doctor --deep，並驗證 CDP role snapshots 包含 link URLs、cursor-promoted clickables、iframe refs 和 frame metadata。
• pnpm test:docker:skill-install: 在裸 Docker runner 中安裝打包後的 OpenClaw tarball，停用 skills.install.allowUploadedArchives，從即時 ClawHub 搜尋解析目前 skill slug，透過 openclaw skills install 安裝，並驗證 SKILL.md、.clawhub/origin.json、.clawhub/lock.json 和 skills info --json。
• CLI backend live Docker probes 可以作為聚焦路徑執行，例如 pnpm test:docker:live-cli-backend:codex、pnpm test:docker:live-cli-backend:codex:resume 或 pnpm test:docker:live-cli-backend:codex:mcp。Claude 和 Gemini 有對應的 :resume 和 :mcp 別名。
• pnpm test:docker:openwebui: 啟動 Dockerized OpenClaw + Open WebUI，透過 Open WebUI 登入，檢查 /api/models，然後透過 /api/chat/completions 執行真實的 proxied chat。需要可用的 live model key（例如 ~/.profile 中的 OpenAI），會拉取外部 Open WebUI 映像檔，且不預期像一般 unit/e2e 套件一樣具備 CI 穩定性。
• pnpm test:docker:mcp-channels：啟動已植入資料的 Gateway 容器，以及第二個會產生 openclaw mcp serve 的用戶端容器，接著驗證路由後的對話探索、逐字稿讀取、附件中繼資料、即時事件佇列行為、對外傳送路由，以及透過真實 stdio 橋接器傳送的 Claude 風格頻道與權限通知。Claude 通知斷言會直接讀取原始 stdio MCP 訊框，因此該煙霧測試反映橋接器實際發出的內容。
• pnpm test:docker:upgrade-survivor：將封裝好的 OpenClaw tarball 安裝到有髒資料的舊使用者 fixture 上，執行套件更新以及不含即時 provider 或頻道金鑰的非互動式 doctor，接著啟動 loopback Gateway，並檢查代理、頻道設定、Plugin 允許清單、工作區/工作階段檔案、過期的舊版 Plugin 相依狀態、啟動流程，以及 RPC 狀態是否都能保留下來。
• pnpm test:docker:published-upgrade-survivor：預設安裝 openclaw@latest，植入沒有即時 provider 或頻道金鑰的擬真既有使用者檔案，使用內建的 openclaw config set 指令配方設定該基準，將該已發佈安裝更新到封裝好的 OpenClaw tarball，執行非互動式 doctor，寫入 .artifacts/upgrade-survivor/summary.json，接著啟動 loopback Gateway，並檢查已設定的意圖、工作區/工作階段檔案、過期的 Plugin 設定與舊版相依狀態、啟動流程、/healthz、/readyz，以及 RPC 狀態是否能保留或乾淨地修復。可用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPEC 覆寫單一基準，用 OPENCLAW_UPGRADE_SURVIVOR_BASELINE_SPECS 展開精確的本機矩陣，例如 openclaw@2026.5.2 openclaw@2026.4.23 openclaw@2026.4.15，或用 OPENCLAW_UPGRADE_SURVIVOR_SCENARIOS=reported-issues 新增情境 fixture；reported-issues 集合包含 configured-plugin-installs，用來驗證升級期間會自動安裝已設定的外部 OpenClaw plugins，以及 stale-source-plugin-shadow，用來避免僅存在於原始碼的 Plugin shadow 破壞啟動。套件驗收會將這些公開為 published_upgrade_survivor_baseline、published_upgrade_survivor_baselines 和 published_upgrade_survivor_scenarios，並在把精確套件規格交給 Docker lanes 前，解析像 last-stable-4 或 all-since-2026.4.23 這類中繼基準 token。
• pnpm test:docker:update-migration：在清理工作繁重的 plugin-deps-cleanup 情境中執行已發佈升級 survivor harness，預設從 openclaw@2026.4.23 開始。獨立的 Update Migration workflow 會以 baselines=all-since-2026.4.23 展開此 lane，因此從 .23 起的每個穩定已發佈套件都會更新到候選版本，並在完整發行 CI 之外證明已設定 Plugin 的相依清理。
• pnpm test:docker:plugins：針對本機路徑、file:、具有 hoisted 相依項的 npm registry 套件、git 移動 ref、ClawHub fixture、marketplace 更新，以及 Claude-bundle 啟用/檢查，執行安裝/更新煙霧測試。

​

本機 PR 門檻

• pnpm check:changed
• pnpm check
• pnpm check:test-types
• pnpm build
• pnpm test
• pnpm check:docs

• OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test
• OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed

​

模型延遲基準測試（本機金鑰）

• source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10
• 選用 env：MINIMAX_API_KEY、MINIMAX_BASE_URL、MINIMAX_MODEL、ANTHROPIC_API_KEY
• 預設提示：“Reply with a single word: ok. No punctuation or extra text.”

• minimax 中位數 1279ms（最小 1114，最大 2431）
• opus 中位數 2454ms（最小 1224，最大 3170）

​

CLI 啟動基準測試

• pnpm test:startup:bench
• pnpm test:startup:bench:smoke
• pnpm test:startup:bench:save
• pnpm test:startup:bench:update
• pnpm test:startup:bench:check
• pnpm tsx scripts/bench-cli-startup.ts
• pnpm tsx scripts/bench-cli-startup.ts --runs 12
• pnpm tsx scripts/bench-cli-startup.ts --preset real
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case status --case gatewayStatus --runs 3
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case tasksJson --case tasksListJson --case tasksAuditJson --runs 3
• pnpm tsx scripts/bench-cli-startup.ts --entry openclaw.mjs --entry-secondary dist/entry.js --preset all
• pnpm tsx scripts/bench-cli-startup.ts --preset all --output .artifacts/cli-startup-bench-all.json
• pnpm tsx scripts/bench-cli-startup.ts --preset real --case gatewayStatusJson --output .artifacts/cli-startup-bench-smoke.json
• pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu
• pnpm tsx scripts/bench-cli-startup.ts --json

• startup: --version, --help, health, health --json, status --json, status
• real: health, status, status --json, sessions, sessions --json, tasks --json, tasks list --json, tasks audit --json, agents list --json, gateway status, gateway status --json, gateway health --json, config get gateway.port
• all: 兩個預設集

• pnpm test:startup:bench:smoke 會將目標 smoke artifact 寫入 .artifacts/cli-startup-bench-smoke.json
• pnpm test:startup:bench:save 會使用 runs=5 和 warmup=1，將完整套件 artifact 寫入 .artifacts/cli-startup-bench-all.json
• pnpm test:startup:bench:update 會使用 runs=5 和 warmup=1，重新整理已納入版控的基準 fixture：test/fixtures/cli-startup-bench.json

• test/fixtures/cli-startup-bench.json
• 使用 pnpm test:startup:bench:update 重新整理
• 使用 pnpm test:startup:bench:check 將目前結果與 fixture 比較

​

Onboarding E2E（Docker）

scripts/e2e/onboard-docker.sh

​

QR 匯入 smoke（Docker）

pnpm test:docker:qr

​

相關

• 測試
• 即時測試
• 測試更新與 plugins