momentic-test

Momentic 背景

執行模型

Momentic 是一個端到端測試框架。測試是結構化步驟的有序列表，透過 Playwright 與 CDP 執行。

• 互動步驟（如點擊與輸入）使用 AI 將自然語言目標解析為具體的瀏覽器動作。
• 斷言步驟可以使用多模態模型來評估頁面狀態。
• 基於目標的 AI 動作可以執行更廣泛的任務，例如「使用信用卡結帳」。

快取與記憶

Momentic 會快取已解析的步驟元資料，例如選擇器、XPath、可見文字與座標，因此大多數執行可避免重複的 AI 呼叫。這對速度至關重要，但過時的快取是實際的除錯可能性：步驟可能點擊到錯誤的元素。
AI 斷言也可能使用過去的結果記憶來保持跨執行的一致性；不良的記憶可能解釋重複的邊際失敗。

快取範圍由 git 元資料（包括分支）決定。在受保護的分支（包括設定的主分支）上會跳過快取寫入，除非使用 --save-cache 強制儲存快取，或設定了 CI 環境變數。在受保護的分支上仍可讀取快取。使用 --disable-cache 可完全繞過快取。

強制重新行為的方法：

• 當意圖改變時，修改步驟描述/斷言；這會變更用於快取比對的步驟識別。在 v1 中，拼接已變更的步驟也會建立新的內部 UUID。
• 對應在每次執行都應重新解析的動態目標（例如「今天日期的日曆儲存格」）使用 --disable-cache。
• 透過 --cache-id <CacheId> 將良好的預覽快取攜帶到拼接中。
• 當先前的 AI 記憶現在具有誤導性時，修改斷言措辭並加入消歧義。

時機

Momentic 在目標步驟前使用「智慧等待」。它會等待設定的智慧等待超時時間（預設為 5 秒），讓頁面狀態穩定或所需元素出現。在此時間內，請勿加入手動睡眠或等待。對於較慢或更語義的準備狀態，請使用 waitForUrl、文字/元素檢查或 AI 斷言。

設定優先順序

momentic.config.yaml 設定專案預設值，但許多設定可在測試層級覆寫：瀏覽器類型、視窗大小、語言/時區、地理位置、頁面載入超時、智慧等待超時、代理、標頭、驗證、擴充功能等。在假設套用專案預設值之前，請務必檢查測試自身的元資料。

測試上下文

每次執行都有一個測試範圍的 env 上下文，該上下文會跨步驟（包括模組）持續存在。後續步驟可以讀取先前步驟寫入的值。

• v2：在具有回傳值的步驟上使用 saveAs。
• v1/MCP CLI 字串：使用 --env-key。
• JavaScript：偏好使用 return 加上 saveAs / --env-key；在設定多個變數時使用 setVariable(name, value)。
• 在 JavaScript 與模組輸入表達式中使用 env.NAME。
• 在字串欄位中使用 {{ env.NAME }}。{{ ... }} 可以評估 JavaScript，但請勿在 JavaScript 步驟原始碼中使用，因為 env 已在該作用域中。

模組輸入是作為字串的 JavaScript 片段。對字串字面量加上引號，並對變數使用 env.X；它們不是 {{ }} 模板。

JavaScript 上下文

JavaScript 步驟可以在 NODE 或 BROWSER 中執行。

• NODE：適用於 API 呼叫、資料準備、OTP/電子郵件/SMS、資料庫查詢與變數寫入。它具有 Momentic 全域變數與預載入的函式庫。env、setVariable、email、sms、axios、assert、faker、moment、pg、OTPAuth、child_process 等。請參閱 JavaScript 命令文件或步驟編寫指南以取得更多詳細資訊。
• BROWSER：在頁面中執行，可使用 window / document 與頁面全域變數。它沒有僅限 Node 的 Momentic 輔助工具。

將簡短的一次性 JavaScript 保持內聯。在 v2 YAML 中，可重複使用的工具程式與長腳本可以放在專案腳本檔案中，遵循現有專案慣例。偏好使用如 ./scripts/page-utilities/auth-loader.js 的位置。先閱讀附近的腳本，並比對它們的模組風格、輔助工具命名、env 使用方式與錯誤風格。

磁碟上的專案狀態

測試是 *.test.yaml 檔案。模組是可重複使用的步驟集合，儲存為 *.module.yaml 檔案。測試 ID 是權威性的，位於測試檔案的 id 欄位。

有兩種主要檔案格式：

• fileType: momentic/test/v2 或 fileType: momentic/module/v2 -> v2。
  對於高信心的變更，偏好直接編輯 YAML，因為速度更快。
• 缺少 fileType 或任何其他值 -> v1。切勿直接編輯 v1 YAML；僅透過 momentic_test_splice_steps 保留變更。

momentic.config.yaml 是專案根目錄設定檔。它儲存代理、AI 功能、瀏覽器選項、錄製、超時、瀏覽器類型、檔案 glob 與環境的專案預設值。請參閱 https://momentic.ai/docs/configuration/momentic-config.md。

v2 步驟可以透過相對路徑引用本機檔案：

• 模組呼叫：path: ./modules/login.module.yaml
• JavaScript 步驟：javascript: ./scripts/setup.js
• 驗證狀態：authLoad: ./auth-state.json、authSave: ./auth-state.json

相對路徑從包含該步驟的 YAML 檔案解析，而不是從專案根目錄或匯入測試。使用 ./... 或 ../...；請勿使用絕對路徑或 ~。如果您移動、重新命名或刪除被引用的檔案，請搜尋舊路徑並更新每個引用。

v1 YAML 仍應僅透過 MCP 編輯。請勿在 v1 YAML 或 MCP CLI 步驟字串中使用 codeFile；v1 JavaScript 步驟應在 code / --code 中攜帶可執行程式碼。僅在 v2 YAML 中使用 JavaScript 檔案引用。

請勿將內部或自動產生的欄位加入 v2 YAML。

編輯前

僅收集您需要的資訊：

• 測試目標與使用者可見的成功標準。
• 起點：baseUrl 或命名環境。
• 驗證需求與所需的環境變數。
• 不得執行兩次的高風險動作：提交、購買、刪除、發送、建立。

對於長時間任務，在編寫前檢查附近的測試與模組。重複使用現有模組通常比內聯重建常見流程更好。

在長時間執行的檢查、從頭開始、破壞性動作或編輯共用模組之前，請先詢問。

選擇工作流程

如果使用者要求特定工作流程，除非不安全或不可能，否則請尊重它。否則，當檔案為 v2、變更為局部、步驟順序已知且不需要即時 UI 探索時，使用直接 v2 YAML 編輯。好的範例：從附近模式建立樣板、重新措辭斷言、調整目標、更新 env 鍵、修正檔案引用或插入一個小的已知步驟。

當檔案為 v1 或未知、必須探索 UI 狀態、定位器時機不穩定、流程為多步驟且不明確，或使用者要求以互動方式建立/驗證（「有頭模式」）時，使用 MCP 瀏覽器驗證工作流程。

對於新測試，使用 momentic_test_create；如果工具未顯示，請搜尋它。它需要 name 以及 baseUrl 或 environment。僅在要求時傳遞目標欄位，例如 pathSegments。
momentic_session_start 需要現有的 testId；它不會建立測試。

通用編寫規則

• 偏好自然語言元素描述。僅在 AI 無法看到的情況下（例如 SVG 內部、畫布或使用者要求的選擇器層級目標）才使用選擇器或座標作為最後手段。
• 偏好原生的 Momentic 步驟而非 JavaScript。僅在沒有原生步驟能表達行為時使用 JS。JS 步驟可以在瀏覽器（客戶端）或 Node（伺服器端）中執行。
• 請勿在開頭加入導航。工作階段從測試的基礎 URL 開始。
• 保持斷言簡潔且由使用者驅動。僅在需要使下一個依賴動作可靠時加入準備狀態檢查。
• 在應導航或實質改變狀態的點擊/動作之後，在依賴動作之前加入立即驗證。對於 URL 合約偏好 waitForUrl，對於穩定的文字或元素偏好 checkPageContains / checkElement...，對於語義視覺狀態偏好 assert。
• 除非使用者要求或現有測試已使用，否則請勿使用 AI 動作（act、AI_ACTION、AI_ACTION_DYNAMIC）。
• 除非需要正確性，否則請勿加入選用/預設欄位。
• 保持變更小。保留不相關的參數、請求主體、env 鍵、字面值、引號、註解、順序與步驟風格。
• 請勿繞過真實的應用程式失敗。如果應用程式損壞、資料遺失或後端關閉，請回報失敗，而不是削弱測試。
• 除非測試意圖需要，否則請勿重新組織 before / steps / after 或 setup / main / teardown。

使用 v2 YAML

v2 是人類可編輯的格式。步驟簡潔：每個步驟有一個頂層命令鍵，例如 click: Submit，或該鍵下的詳細對應。測試使用 before / steps / after；模組使用 steps。持續時間始終為毫秒。沒有可見的步驟/命令 ID。

直接編輯循環：

1. 對於新測試，使用 momentic_test_create 建立，然後一次批次編輯 YAML，而不是透過 MCP 逐一加入已知步驟。
2. 進行最小的 YAML 編輯。保留風格。如果您不確定語法，請從 https://static.momentic.ai/v2-format-reference.md 取得並閱讀所需內容。
3. 僅在使用者要求、風險需要或變更需要即時確認時才進行驗證。

常見錯誤：

• 將選項放在命令旁邊，而不是巢狀在命令下。
• 對命令使用錯誤的目標欄位名稱。

npx momentic lint 驗證 v2 架構與檔案引用。Lint 會在 momentic app 與 momentic run 之前自動執行；如果您在編輯後或移動/重新命名被引用檔案後不確定語法，請手動執行。

磁碟編輯後的狀態重新整理：

• 沒有活躍的 MCP 工作階段：準備驗證時啟動新的工作階段。
• 有活躍的工作階段加上 momentic_test_reload：在 momentic_run_step 之前重新載入。
• 有活躍的工作階段但沒有重新載入工具：終止並重新啟動工作階段。
• momentic_test_get 檢查持久化狀態；除非工具明確說明，否則它不會重新整理活躍的工作階段。

MCP 瀏覽器驗證工作流程

對每個 v1 編輯以及需要即時探索的 v2 工作使用此流程。工具表面是共用的；持久化方式不同：v1 使用拼接，而 v2 可以使用拼接或直接 YAML 編輯加上重新載入。

探索

• momentic_get_artifacts()：專案上下文、設定檔路徑、cwd 以及測試、模組、環境等的工件檔案。僅讀取您需要的內容。
• momentic_test_get({ testId | testPath })：檢查持久化的測試狀態。在工作階段前，這很有用。在拼接後的活躍工作階段期間，偏好使用拼接回應或 returnTest: true。
• momentic_module_recommend({ userRequest })：尋找可重複使用的流程。
• momentic_module_get({ selector })：檢查模組參數、預設值、列舉與步驟。選擇器正好是 { id }、{ name } 或 { path } 之一。

工作階段

• momentic_session_start({ testId, ... })：啟動瀏覽器工作階段。它會回傳元資料、步驟編寫指南工件以及具有活躍工作階段步驟 ID 的測試內容。必要：testId。單獨呼叫它，不要與其他 MCP 工具並行。選項包括 env/設定/專案覆寫、有頭模式與影片。
• 在建立 CLI 風格的步驟之前，請先閱讀步驟編寫指南。
• momentic_run_step({ sessionId, fromStep, toStep?, targetSection?, resetSession? })：執行現有的活躍工作階段步驟。使用測試內容或拼接回應中的步驟 ID，絕不使用原始 YAML。對頂層步驟使用 parentStepIdChain: []。絕不要透過此 MCP 工具執行包含 AI 動作的範圍。 MCP 工具呼叫上限為 60 秒，而 AI 動作通常會遠遠超過此時間並在執行中被取消——執行會被終止，其工作會遺失。始終在您的終端機中使用 momentic run-step CLI 執行此類範圍（請參閱「執行長時間執行的 AI 動作步驟」），該 CLI 沒有此上限。
• 如果狀態偏移，請使用 momentic_run_step 並在同一 sessionId 上設定 resetSession: true 重新啟動；不要在每次微編輯之間重設。
• momentic_session_terminate({ sessionId })：完成時終止。如果以 video: true 啟動，回應會包含影片目錄。

測試編寫循環

以檢查點大小的區塊編寫 MCP 步驟。預覽前進，直到邏輯區塊運作正常，然後拼接該檢查點。好的檢查點是自然流程邊界，例如登入完成、表單提交、頁面刪除等。避免一次拼接一個步驟，除非風險極高且非冪等。

• momentic_preview_step({ sessionId, step })：在瀏覽器中執行一個步驟而不持久化。如果它回傳 CacheId，請在拼接該步驟時包含 --cache-id <CacheId>。回應螢幕截圖顯示步驟後的頁面狀態。絕不要透過此 MCP 工具預覽 AI 動作——它會在 60 秒工具呼叫上限時被取消，且其工作會遺失。始終在您的終端機中使用 momentic preview-step CLI 預覽 AI 動作（請參閱「執行長時間執行的 AI 動作步驟」）。
• 如果預覽螢幕截圖不足以定位目標，請呼叫 momentic_get_session_state 並設定 returnBrowserState: true，然後檢查工件以取得穩定的名稱、角色、可見文字與顯著結構，以協助建立可靠描述。請謹慎使用，因為瀏覽器狀態很大。
• 當接下來的幾個步驟明顯且低風險時（例如填寫已知的表單欄位），將它們拼接在一起並執行該儲存的範圍，而不是逐一預覽每個欄位。
• momentic_test_splice_steps({ sessionId, startIndex, deleteCount, steps, targetSection?, parentStepIdChain?, returnTest? })：插入、取代或刪除步驟並持久化。
• 拼接後，立即讀取回應；它是插入/刪除引用與活躍工作階段步驟 ID 的真實來源。
• 如果 returnTest: true，請在繼續前驗證回傳的結構。
• 如果後續步驟仍然存在，請執行緊接的下一個步驟以確認流程仍然連接。
• 對於非冪等動作（如提交、購買、刪除、發送等），避免重複預覽。預覽設定步驟，在高風險動作之前拼接檢查點，然後僅在驗證需要時執行一次高風險的儲存步驟。
• 對於明顯相鄰的低風險步驟，批次處理它們；除非定位器或頁面狀態不確定，否則不要在每個欄位後設定檢查點。
• 當要求的編輯完成時，詢問是否要透過執行相關儲存範圍與 momentic_run_step 從頭開始驗證。

讀取工具輸出

工作階段是即時的瀏覽器程序。螢幕截圖與瀏覽器狀態是即時快照。如果螢幕截圖在動作後未顯示預期狀態，請再呼叫一次 momentic_get_session_state；頁面可能仍在載入。

MCP 工具可能回傳 .momentic-mcp/... 下的工件連結。僅在需要時讀取連結的檔案：

• UI 狀態文字：精煉定位目標或除錯結構。
• 螢幕截圖：通常已內聯回傳為圖片。
• 環境檔案：驗證 envKey、JavaScript/API 輸出或依賴的 env 值。
• momentic_get_session_state 僅在 returnBrowserState: true 時回傳序列化的 UI 狀態；螢幕截圖預設會回傳。

CLI 風格的步驟字串

preview_step 與 splice_steps 使用 CLI 風格的字串：
--step-type <TYPE> [options]，例如 CLICK、TYPE、NAVIGATE、
AI_ASSERTION、MODULE、WAIT_FOR_URL。

範例：

• 導航：--step-type NAVIGATE --url "https://example.com"
• 點擊：--step-type CLICK --description "the Sign in button"
• 輸入：
  --step-type TYPE --description "Search input" --value "hello" --press-enter
• AI 斷言：
  --step-type AI_ASSERTION --assertion "the page shows a Sign in button" --timeout-seconds 10
• 模組：
  --step-type MODULE --module-id <id> --inputs email=env.USER_EMAIL --inputs password=env.USER_PASSWORD

拼接範例：

{
  "sessionId": "SESSION_ID",
  "startIndex": 0,
  "deleteCount": 0,
  "steps": [
    "--step-type NAVIGATE --url \"https://example.com\"",
    "--step-type AI_ASSERTION --assertion \"the page shows a Sign in button\" --timeout-seconds 10 --cache-id UUID_FROM_PREVIEW"
  ],
  "targetSection": "main"
}

對於條件式，使用 --assertion-type 與相符的斷言欄位建立 CONDITIONAL 步驟，然後使用 parentStepIdChain: [conditionalStepId] 拼接巢狀步驟。

執行長時間執行的 AI 動作步驟 (CLI)

這是強制性的，不是建議。 AI 動作 (AI_ACTION_DYNAMIC) 在執行時規劃並執行許多子步驟，通常會超過 60 秒。MCP 工具呼叫上限為 60 秒，無論進度如何都會被取消，因此透過 momentic_preview_step / momentic_run_step 執行 AI 動作會使其在執行中被終止，您會遺失工作。終端機沒有此上限。始終在您的終端機中使用 momentic CLI 執行任何包含 AI 動作的步驟範圍——絕不要透過 MCP 執行/預覽工具。

CLI 命令與 MCP 工具一一對應，並針對相同的長時間執行守護程序執行。當 MCP 伺服器以 --daemon 啟動時，MCP 工作階段與 CLI 呼叫共用相同的即時瀏覽器（以專案設定檔路徑為鍵）：透過 MCP 編寫，然後使用相同的 sessionId 透過 CLI 執行 AI 動作。如果伺服器不在 --daemon 模式，或者您不確定，請透過 CLI 驅動整個流程：session-start，然後預覽/拼接/執行，然後 session-terminate。

在任何命令上傳遞 --json 以取得原始工具結果而非文字。螢幕截圖與其他工件會寫入 .momentic/mcp-cli-artifacts/ 下。

CLI 命令參考

所有命令也接受 --api-key、--server、--config 與 --filter。

• momentic session-start <testId> [--env <name>] [--headful-browser] [--video]
  — 啟動工作階段（對應 momentic_session_start）。列印 sessionId 與步驟編寫指南。僅在不重複使用 MCP 工作階段時使用。
• momentic session-terminate --session <id> — 終止工作階段（對應 momentic_session_terminate）。
• momentic session-state --session <id> — 目前工作階段狀態（對應 momentic_get_session_state）。
• momentic session-env --session <id> — 工作階段可用的環境變數（對應 momentic_get_environment_variables）。
• momentic preview-step --session <id> --step "<cli-style step>" — 執行一個步驟而不持久化（對應 momentic_preview_step）。--step 接受與 MCP 相同的 CLI 風格步驟字串；傳遞 --step "--step-type CLICK --help" 以取得步驟編寫說明。
• momentic run-step --session <id> --from-step <stepId> [--from-parent <ids...>] [--to-step <stepId>] [--to-parent <ids...>] [--section main] [--reset]
  — 執行儲存的步驟範圍（對應 momentic_run_step）。這是用於 AI 動作的命令。--from-parent / --to-parent 是 parentStepIdChain（從根到直接父層；對頂層省略）。--reset 會先重設瀏覽器。
• momentic splice-steps --session <id> --start <index> --delete <count> [--step "<cli-style step>" ...] [--section main] [--parent <ids...>] [--return-test]
  — 插入/取代/刪除步驟並持久化（對應 momentic_test_splice_steps）。重複 --step 以拼接多個步驟。--delete 0 插入，1 取代一個，N 刪除 N 個。--parent 是在拼接進巢狀步驟時的 parentStepIdChain。

透過 MCP 編寫，然後使用共用工作階段透過 CLI 執行 AI 動作（stepId 值來自拼接回應/測試內容）：

momentic run-step --session "$SESSION_ID" --from-step "$AI_ACTION_STEP_ID"

完全自包含的 CLI 流程：

momentic session-start my-test-id            # 列印 SESSION_ID
momentic splice-steps --session "$SESSION_ID" --start 0 --delete 0 \
  --step "--step-type NAVIGATE --url https://example.com" \
  --step "--step-type AI_ACTION_DYNAMIC --text \"complete checkout with the saved test card\""
momentic run-step --session "$SESSION_ID" --from-step "$FIRST_STEP_ID"
momentic session-terminate --session "$SESSION_ID"

模組

對於 4 個步驟以上的邏輯流程（如登入、導航、設定或結帳），預設優先使用模組。呼叫 momentic_module_recommend，使用 momentic_module_get 檢查強烈候選者，然後決定使用模組或內聯。

模組不能包含模組。在模組內拼接 MODULE 步驟會失敗。

編輯共用模組需要使用者確認。若要透過 MCP 修改模組，請將模組步驟取代為攜帶所需元資料旗標的 MODULE 步驟：--parameters、--parameter-enum、--default-parameter、--module-display-name、--module-description、--module-enabled。defaultParameters 與 parameterEnums 中的鍵必須存在於 parameters 中。

模組 inputs 值是作為字串的 JavaScript 片段。對字串字面量加上引號，將 env 引用為 env.X，並嚴格遵守列舉約束。

驗證策略

• 直接 v2 編輯且未要求即時驗證：總結變更並詢問是否要執行。
• 直接 v2 編輯且有活躍工作階段：如果可用則重新載入，否則重新啟動工作階段，然後執行編輯的範圍。
• MCP 編寫的編輯：預覽前進，在邏輯檢查點拼接，然後執行下一個下游儲存步驟或範圍。
• 長時間的完整測試執行與高風險動作需要確認。
• 完成時終止 MCP 工作階段。

疑難排解

頁面狀態與時機

• 錯誤的頁面/UI：讀取最新的 UI 狀態或呼叫 momentic_get_session_state。
• 螢幕截圖未更新：再呼叫一次 momentic_get_session_state。
• 不穩定的時機：偏好使用 AI_ASSERTION、checkPageContains、checkElement... 或 waitForUrl，而非通用的 WAIT。
• 長時間的後端作業/匯入/上傳：使用具有適當超時的斷言或 URL/文字/元素等待，而非睡眠。
• 奇怪的工作階段狀態：使用 momentic_run_step 並設定 resetSession: true。

定位目標與快取

• 找不到元素：檢查螢幕截圖/UI 狀態。如果可見，使用可見文字、角色與附近上下文改善描述；如果不存在，除錯先決條件步驟。
• 快速或無需 AI 就點擊到錯誤元素：懷疑快取過時，尤其是當頁面結構與先前的執行相似時。
• 動態目標：將描述改為穩定，或對該步驟停用快取。
• Playwright 穩定性失敗：可以找到目標，但仍因隱藏、分離、在視口外、被覆蓋或動畫中而無法操作。盡可能偏好修正頁面狀態。僅在可接受繞過可操作性時對該步驟使用 --force，或者如果基於座標的互動是正確的權衡，則啟用專案範圍的視覺動作。
• 視覺動作在專案瀏覽器設定中啟用，使用 visualActions: true。Momentic 透過 X/Y 座標互動，並盡力保留元素識別，而不是像 Playwright 可操作性檢查那樣硬性失敗。
• 引號文字：描述中的引號子字串會被 Momentic AI 視為字面處理。僅在該確切文字必須出現在螢幕上或元素的可存取名稱中時使用引號；對於語義比對，省略引號。

AI 斷言效能

• 模糊的斷言：使預期的視覺/文字條件具體化。包含相關的頁面區域、物件、計數或狀態。
• 字面文字不符：引號字串被視為必須出現在螢幕上的文字。當意圖是語義比對時，移除引號。盡可能描述元素的目的，而非特定文字或標籤。
• 在視口外：視覺條件（如顏色或形狀）僅能在元素位於視口內時評估。使用滾動/懸停設定。
• 視覺上微妙的條件：AI_ASSERTION 支援 VISION_ONLY 模式，具有更好的視覺推理能力。
• 重複的錯誤判定：重新措辭斷言，使預期條件更清晰，且舊記憶不再適用。
• 短暫條件：AI 檢查會在設定的超時時間內重試多次，但每次嘗試都是即時快照。因此，極快的變化（如 1 秒內出現並消失的提示）可能會被錯過。此外，無法評估隨時間的變化（「螢幕比以前暗」）。偏好為穩定的最終狀態建立斷言；必要時可以使用客戶端 JavaScript 觀察器。

格式與資料

• v2 載入/執行失敗：執行 npx momentic lint <path>；移動後常見的錯誤是損壞的相對檔案引用。
• 模組失敗：使用 momentic_module_get 重新檢查必要參數、預設值、列舉與 JS 片段輸入語法。
• 環境變數值遺失：確認產生步驟使用了 saveAs / --env-key 或 setVariable，且消費語法是 env.X 與 {{ env.X }}。
• JavaScript 失敗：確認環境。瀏覽器 JS 不能使用 Node 輔助工具；Node JS 不能讀取即時 DOM 全域變數。

在對同一問題嘗試約三次後，停止並詢問使用者方向。

決策速查表

• 已知的 v2 順序：直接 YAML 編輯。
• v1 或未知的 UI 狀態：MCP 預覽、拼接、驗證。
• 需要正確的步驟索引：使用測試內容、拼接引用或 returnTest；絕不使用原始 YAML 步驟 ID。
• 需要在步驟 N 處的瀏覽器：從開始/設定執行一次到 N-1，然後繼續使用相同的工作階段。
• 單一新步驟想法：momentic_preview_step。
• 持久化驗證過的 MCP 步驟：momentic_test_splice_steps。
• 乾淨重新啟動：使用 resetSession: true 的 momentic_run_step。
• 驗證直接 v2 編輯：如果活躍則使用 momentic_test_reload，否則使用新的工作階段。
• 步驟範圍包含 AI 動作：始終透過終端機中的 momentic run-step CLI 執行——絕不要使用 momentic_run_step，它會在 60 秒 MCP 工具呼叫上限時被取消。