meticulous-test

若要使用 Meticulous 測試前端變更，請依照下列工作流程逐步操作，並使用所述的 CLI 指令。

開始前，請執行 meticulous-cli-update 技能以確保 Meticulous CLI 為最新版本 — 除非此對話中已執行過，則可跳過。

如果已經有測試執行 ID，請直接跳到步驟 4。

步驟 1 — 建置前端

1. 查看 .github/workflows/ 中的以下步驟，以了解 Meticulous 預期的建置產物：
   • uses: alwaysmeticulous/report-diffs-action/upload-assets@v1 — 建置靜態資源
   • uses: alwaysmeticulous/report-diffs-action/upload-container@v1 — Docker 映像檔
2. 依照 GitHub 工作流程中使用的相同指示建置前端。

步驟 2 — 上傳建置

使用 agent upload-build 將建置註冊為可重複使用的部署。這會上傳產物並將 deploymentId 輸出到 stdout — 不會立即觸發執行。

# 靜態資源
meticulous agent upload-build --appDirectory <建置目錄路徑>

# 容器
meticulous agent upload-build --localImageTag <映像檔標籤>

MCP 工具：無 1:1 對應 — 請呼叫 request_asset_upload（或 request_container_upload），自行上傳 zip/映像檔，然後使用回傳的 uploadId 呼叫 register_asset_build（或 register_container_build）以取得 deploymentId。

• --appDirectory 指向建置輸出目錄（例如 dist/ 子資料夾）；--localImageTag 是本地 Docker 映像檔標籤。建置模式會自動偵測。
• 建置的提交預設為本地 git HEAD。如果工作目錄有未提交的變更，則會以臨時提交（輸出為 commitSha (local, ephemeral due to dirty working tree): …）的形式捕捉 — 請參閱下方的未提交變更說明。
• 未追蹤的檔案會被拒絕（無法捕捉）— 請先執行 git add。
• 從 stdout 取得 deploymentId（傳入 --verbose 可在 stderr 上看到進度）。

步驟 3 — 觸發測試執行

為部署觸發執行，並與基準進行比較。從儲存庫目錄執行，以自動推斷基準（與 origin 預設分支的合併基礎）和 git diff：

meticulous agent trigger-test-run --deploymentId <deploymentId>

MCP 工具：trigger_test_run（永遠不會推斷 baseSha/gitDiffOutput — 請明確傳入 — 且總是立即回傳，不會等待執行完成）。

• 必須指定基準。會從當前目錄自動推斷，或傳入 --baseSha <sha>（以及選擇性的 --gitDiffOutput）來明確設定。
• 省略 --deploymentId 則改用已為本地 HEAD 提交上傳的最新部署 — 這需要乾淨的工作目錄（無未提交變更）。
• 指令預設會阻塞直到執行完成，並將 testRunId 輸出到 stdout；當偵測到視覺差異時，最終狀態為 Failure（這是正常的完成判定，並非錯誤）。傳入 --dontWaitForTestRunToComplete 可在觸發執行後立即回傳。
• 一個建置，多個基準： 同一個 deploymentId 可以針對不同基準重新觸發 — 只需使用不同的 --baseSha 再次執行 agent trigger-test-run。無需重新建置或重新上傳。

請記下輸出中的 testRunId。

步驟 4 — 審查視覺變更

依照 meticulous-review 技能操作，傳入步驟 3 的 testRunId。它會擷取差異摘要、檢查代表性截圖 / DOM 差異 / 時間軸，並產出最終報告，將每個視覺變更分類為預期或非預期。

未提交的變更： 如果您在骯髒的工作目錄下建置/測試，執行會記錄到一個臨時提交，該提交不是您的 HEAD（也不會被推送）。從本地簽出解析執行的指令 — 如未指定 --testRunId 的 meticulous-review / agent test-run-diffs — 將無法透過提交找到該執行，因此在這種情況下請務必傳入明確的 --testRunId 給審查步驟。