--- read_when: - 執行或修正測試 summary: 如何在本機執行測試（vitest），以及何時使用強制／覆蓋率模式 title: 測試 x-i18n: generated_at: "2026-07-14T14:10:14Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 25 provider: openai source_hash: 391185703e853bb523e1396eb22da4693d10d47b1644d3b2a51707d329f67dae source_path: reference/test.md workflow: 16 --- - 完整測試套件（測試套件、即時測試、Docker）：[測試](/zh-TW/help/testing) - 更新與外掛套件驗證：[測試更新與外掛](/zh-TW/help/testing-updates-plugins) ## Agent 預設行為 只有在來源可信任且現有相依套件已安裝妥當時，Agent 工作階段才會在本機執行一個或少數幾個聚焦測試及低成本靜態檢查。絕不在本機執行不受信任的儲存庫工具。較大型的測試套件、會展開型別檢查／程式碼檢查的變更閘門、建置、Docker、套件流程、E2E、即時證明及跨平台驗證，皆透過 Crabbox 遠端執行。受信任維護者的高負載證明預設使用 Blacksmith Testbox。已設定的 Testbox 工作流程會載入認證資訊，因此不受信任的貢獻者或分支程式碼必須改用不含祕密資訊的分支 CI，或經過清理的直接 AWS Crabbox。 不要為預期中的工作預先暖機。等第一個高負載命令準備就緒時，再延遲取得後端；後續高負載命令重複使用傳回的 `tbx_...` ID；每次執行時同步目前的簽出內容，並在交接前停止後端。 首次成功重複使用後，包裝程式會將租用環境的基底、相依套件及 Testbox 工作流程指紋記錄於 `.crabbox/testbox-leases/`。僅修改原始碼時，會繼續重複使用已暖機的環境。若合併基底、鎖定檔、套件管理器輸入、包裝程式或 Testbox 工作流程有所變更，系統會採取失敗關閉策略，並要求全新的租用環境。每次執行仍會同步目前的簽出內容。 `OPENCLAW_TESTBOX_ALLOW_STALE=1` 僅供刻意進行診斷時使用，不可作為發行證明。 下方的本機測試命令適用於人工工作流程與範圍受限的 Agent 證明。若遠端供應者無法使用，必須回報；這不代表可以默默改在本機執行廣泛閘門。 對於不受信任的高負載證明，請使用 `--provider aws` 延遲暖機。每次執行都必須設定 `CRABBOX_ENV_ALLOW=CI`、傳入 `--provider aws --no-hydrate`，並在安裝相依套件或執行測試前使用全新的暫時遠端 `HOME`。使用專供該不受信任來源、全新暖機的租用環境；絕不重複使用受信任或先前已載入認證資訊的租用環境。從乾淨且受信任的 `main` 簽出內容啟動已安裝且受信任的 Crabbox 二進位檔，並只使用 `--fresh-pr` 擷取遠端 PR；絕不在本機執行不受信任簽出內容中的包裝程式或設定。取消設定 `CRABBOX_AWS_INSTANCE_PROFILE`，且除非解析後的 `aws.instanceProfile` 為空，否則採取失敗關閉策略。進行任何安裝／測試之前，請使用受信任的絕對路徑工具要求 IMDSv2 權杖、證明 IAM 認證資訊端點傳回 404，並驗證遠端 `git rev-parse HEAD` 等於完整且已審查的 PR 頭部 SHA。將租用環境綁定至該 SHA，並在頭部變更時停止及重新暖機。將乾淨 `main` 中受信任的 `scripts/crabbox-untrusted-bootstrap.sh` 與 `--fresh-pr` 一併上傳；它會安裝固定版本的 Node/pnpm、驗證 SHA 與套件管理器版本固定設定、隔離 `HOME`、安裝相依套件，然後執行要求的測試。若代理程式無法證明不存在角色或遠端 PR，請使用不含祕密資訊的分支 CI。不要使用 `hydrate-github`、`--no-sync` 或會載入認證資訊的 Testbox 工作流程。 取消設定所有 `CRABBOX_TAILSCALE*` 覆寫、強制使用 `--network public --tailscale=false`、清除出口節點／LAN 旗標，並要求 `crabbox inspect` 在上傳任何指令碼之前，回報未包含任何 Tailscale 狀態的公用網路連線。 ## 例行本機順序 1. `pnpm test:changed` 用於變更範圍的 Vitest 證明。 2. `pnpm test ` 用於單一檔案、目錄或明確目標。 3. 只有在刻意需要完整本機 Vitest 測試套件時，才使用 `pnpm test`。 在 Codex 工作樹或連結／稀疏簽出中，Agent 應避免直接在本機使用 `pnpm test*`／`pnpm check*`／`pnpm crabbox:run`： - 相依套件已就緒時的範圍受限聚焦證明： `node scripts/run-vitest.mjs `。 - 先分類再進行的變更檢查：`node scripts/check-changed.mjs`；僅文件、無變更及小型中繼資料方案會在相依套件已就緒時保留於本機執行，而高負載或缺少相依套件的方案則委派給 Testbox。 - 明確保留租用環境的廣泛證明：`node scripts/crabbox-wrapper.mjs run --provider blacksmith-testbox ... -- env OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 OPENCLAW_CHANGED_LANES_RAW_SYNC=1 corepack pnpm check:changed`，使 pnpm 在 Testbox 內執行。 - 包裝程式最後的 `exitCode` 與計時 JSON 即為命令結果。委派的 Blacksmith GitHub Actions 執行在 SSH 命令成功後可能顯示 `cancelled`，因為 Testbox 是從保活動作外部停止；將其視為失敗前，請先檢查包裝程式摘要與命令輸出。 - `OPENCLAW_HEAVY_CHECK_LOCK_SCOPE=worktree `：對於 `pnpm check:changed` 及指定目標的 `pnpm test ...` 等命令，會將高負載檢查的序列化保留在目前工作樹內，而不是 Git 共用目錄中。只有在高容量本機主機上刻意跨連結工作樹執行獨立檢查時，才使用此功能。 ## 核心命令 測試包裝程式執行結束時會顯示簡短的 `[test] passed|failed|skipped ... in ...` 摘要；Vitest 本身的持續時間行則保留為各分片的詳細資訊。 | 命令 | 功能 | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `pnpm test` | 明確的檔案／目錄目標會透過具範圍的 Vitest 流程路由。未指定目標的執行屬於完整測試套件證明：固定分片群組會展開為葉節點設定，以便在本機平行執行，並在開始前列印預期的分片展開數量。擴充功能群組一律展開為各擴充功能專屬的分片設定，而非單一龐大的根專案程序。 | | `pnpm test:changed` | 低成本智慧變更測試執行：根據直接測試編輯、同層 `*.test.ts` 檔案、明確的原始碼對應關係及本機匯入圖產生精確目標。除非廣泛／設定／套件變更能對應至精確測試，否則會略過。 | | `OPENCLAW_TEST_CHANGED_BROAD=1 pnpm test:changed` | 明確的廣泛變更測試執行；當測試框架／設定／套件編輯應改用 Vitest 較廣泛的變更測試行為時使用。 | | `pnpm test:force` | 釋放已設定的 OpenClaw 閘道連接埠（預設 `18789`），然後使用隔離的閘道連接埠執行完整測試套件，避免伺服器測試與正在執行的執行個體發生衝突。 | | `pnpm test:coverage` | 針對預設單元測試流程（`vitest.unit.config.ts`）輸出資訊用途的 V8 覆蓋率報告；不強制套用覆蓋率門檻。 | | `pnpm test:coverage:changed` | 僅針對自 `origin/main` 起變更的檔案產生單元測試覆蓋率。 | | `pnpm changed:lanes` | 顯示相對於 `origin/main` 的差異所觸發的架構流程。 | | `pnpm check:changed` | 選擇執行方式前先對變更流程進行分類。僅文件、無變更及小型中繼資料方案會在相依套件已就緒時保留於本機執行；包含型別檢查／程式碼檢查展開、其他高負載流程或缺少本機相依套件的方案，則會在 CI 外委派給 Crabbox／Testbox。不會執行 Vitest；測試證明請使用 `pnpm test:changed` 或 `pnpm test `。 | ## 共用測試狀態與程序輔助工具 - `src/test-utils/openclaw-test-state.ts`：當測試需要隔離的 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、設定固定資料、工作區、Agent 目錄或驗證設定檔儲存區時，請從 Vitest 使用。 - `pnpm test:env-mutations:report`：以非阻斷方式回報直接修改 `HOME`、`OPENCLAW_STATE_DIR`、`OPENCLAW_CONFIG_PATH`、`OPENCLAW_WORKSPACE_DIR` 或相關環境變數鍵的測試／測試框架。使用此功能尋找適合遷移至共用測試狀態輔助工具的候選項目。 - `test/helpers/openclaw-test-instance.ts`：將需要執行中閘道、命令列介面環境、日誌擷取及清理作業的程序層級 E2E 測試集中處理。 - 載入 `scripts/lib/docker-e2e-image.sh` 的 Docker／Bash E2E 流程可將 `docker_e2e_test_state_shell_b64