momentic-mobile-test

Momentic Mobile 背景

執行模型

Momentic Mobile 驅動真實的 Android 模擬器與 iOS 模擬器。測試是結構化的行動步驟有序列表。

• 互動步驟（如點擊、輸入、滑動、滾動）使用 AI 將自然語言目標解析為具體的裝置動作。
• 斷言可評估可見螢幕狀態、原生層級結構以及 WebView 狀態（若可用）。
• 基於目標的 AI 動作可執行較廣泛的任務，但原生行動步驟更穩定，應優先使用。

快取與記憶體

Momentic 會快取解析後的行動步驟元資料（如原生選擇器、XML 節點、可見文字、WebView 狀態與座標），因此大多數執行可避免重複的 AI 呼叫。這對速度至關重要，但過時的快取是實際的除錯可能性：步驟可能點擊到錯誤的元素。AI 檢查也可能使用過去結果的記憶體以保持跨執行的一致性；不良的記憶體可能導致重複的邊界失敗。

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

強制重新行為的方法：

• 當意圖改變時，修改步驟描述/斷言；這會變更用於快取匹配的步驟識別碼。在 v1 中，拼接已變更的步驟也會產生全新的內部 UUID。
• 對應每次執行都應重新解析的動態目標（如今天的日期或下一個可用時段）使用 --disable-cache。
• 透過 --cache-id <CacheId> 將良好的預覽快取帶入拼接中。
• 當先前的 AI 記憶體現在會誤導時，修改斷言用詞並加入消歧義。

時機

Momentic 在目標步驟前使用智慧等待。它會等待最多設定的智慧等待超時時間（預設 5 秒），讓裝置狀態穩定或目標出現。在此時間內，請勿加入手動等待。對於較慢或語意上的就緒狀態，請使用有針對性的元素/螢幕檢查、AI 檢查，或僅在測試確實需要固定時間時才使用原生等待。

設定優先順序

momentic.config.yaml 設定專案預設值，但許多行動設定可在測試層級覆寫：平台、預設應用程式資產頻道/標籤、模擬器提供者、本機裝置/應用程式覆寫、語言環境/時區、地理位置、超時、標頭與環境。在假設專案預設值適用之前，務必檢查測試自身的元資料。

對於受管理的行動資產，請將 momentic_get_artifacts() 中的 channels 視為唯一真相來源。settings.defaultChannel 必須是測試平台的實際頻道。settings.defaultTag 為選用；省略則使用該頻道上最近上傳的標籤。除非該文字標籤確實存在，否則不要假設 "latest" 是特殊的。

測試上下文

每次執行都有一個測試範圍的 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 步驟在行動執行沙箱中執行。將它們用於簡短的單次資料準備、API 檢查、斷言或原生行動步驟無法表達的上下文寫入。

沙箱通常提供 env、setVariable、axios、assert 以及其他 Momentic 提供的輔助函式。如果確切的 JS 支援很重要，請查閱 momentic_session_start 中的 JavaScript 命令文件或步驟撰寫指南。

將簡短的單次 JavaScript 保持內聯。在 v2 YAML 中，可重複使用的工具與長腳本可放在專案腳本檔案中，遵循現有專案慣例。當專案已有 scripts/ 模式時，偏好使用 $MOMENTIC_PROJECT_ROOT/scripts/mobile-utilities/setup.js 等位置。先閱讀附近的腳本，並比對它們的模組風格、輔助函式命名、env 使用方式與錯誤風格。

磁碟上的專案狀態

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

有兩種主要的行動檔案格式：

• fileType: momentic/mobile-test/v2 或 fileType: momentic/mobile-module/v2 -> 行動端 v2。當不需要即時裝置探索時，對於高度確信的局部變更，偏好直接編輯 YAML。
• 缺少 fileType，或任何其他值 -> v1。絕不直接編輯 v1 YAML；僅透過 momentic_test_splice_steps 保留變更。

行動端 v2 測試包含必要的 platform 值：ANDROID 或 IOS。平台特定的命令可用性很重要。不要將僅限 Android 的命令加入 iOS 測試。

momentic.config.yaml 是專案根目錄設定。它儲存代理程式、AI 功能、模擬器設定、檔案 glob、環境、行動資產、快取行為與進階設定的專案預設值。

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

• 模組調用：module: ./modules/login.module.yaml
• JavaScript 步驟：javascript: ./scripts/setup.js
• 檔案注入：命令特定的本機檔案路徑

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

v1 YAML 仍應僅透過 MCP 編輯。不要在 v1 YAML 或 MCP CLI 步驟字串中使用檔案支援的 JavaScript；v1 JavaScript 步驟應在 code / --code 中包含可執行程式碼。僅在行動端 v2 YAML 中使用 JavaScript 檔案引用。

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

編輯前

僅收集您需要的資訊：

• 測試目標與使用者可見的行動成功標準。
• 平台：Android 或 iOS。
• 應用程式來源：受管理的頻道/標籤、本機 APK/.app，或已安裝的應用程式。
• 提供者：預設為遠端；僅在使用者明確要求本機模擬器/模擬器時才使用本機。
• 驗證需求與必要的環境變數。
• 不得執行兩次的高風險動作：提交、購買、刪除、發送、建立。

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

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

選擇工作流程

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

當檔案為 v1 或未知、必須探索即時 UI 狀態、目標時機不穩定、流程為多步驟且不明確、變更依賴平台行為，或使用者要求互動式建置/驗證時，使用 MCP 裝置驗證工作流程。

使用 momentic_test_create 建立新的行動測試；如果工具不可見，請搜尋它。它需要 name、platform 與有效的行動設定。僅在要求時才傳遞資料夾/路徑欄位。

momentic_session_start 需要現有的 testId；它不會建立測試。

通用撰寫規則

• 偏好自然語言元素描述。僅在 AI 無法看到的情況下（如畫布式表面、非語意自訂檢視、地圖、遊戲或使用者要求的座標目標）才將座標目標作為最後手段。
• 偏好原生行動步驟而非 JavaScript。僅在沒有原生步驟能表達行為時才使用 JS。
• 不要在開頭加入啟動/開啟應用程式步驟，除非測試確實需要切換應用程式或恢復應用程式狀態。
• 保持斷言簡潔且由使用者驅動。僅在需要使下一個依賴動作可靠時才加入就緒檢查。
• 在應實質改變螢幕狀態的動作之後，在依賴動作之前加入立即驗證。對於確定性文字/狀態，偏好 ELEMENT_CHECK 或 SCREEN_CHECK；對於語意視覺狀態，偏好 AI_CHECK。
• AI_CHECK 預設為多模態（螢幕截圖 + 無障礙/XML 層級結構）。對於僅螢幕截圖的檢查，使用其純視覺形式（YAML 中的 assertVisually 鍵）。當層級結構不可用或不可靠時（例如包含多個頁面的 WebView），或當條件純粹是視覺時，使用它。條件必須完全可從當前視口驗證，因為沒有層級結構且無法取得螢幕外資訊。
• 除非使用者要求或現有測試已使用，否則不要使用 AI 動作。
• 除非需要正確性，否則不要加入選用/預設欄位。
• 保持差異小。保留不相關的參數、請求主體、環境變數鍵、字面值、引號、註解、順序與步驟風格。
• 不要繞過真實的應用程式失敗。如果應用程式損壞、資料遺失、權限被封鎖、應用程式資產錯誤或後端故障，請回報失敗而不是削弱測試。
• 除非測試意圖需要，否則不要重新組織 before / steps / after 或設定 / 主要 / 拆卸。

使用行動端 V2 YAML

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

直接編輯循環：

1. 確認 fileType 與 platform。
2. 檢查附近的測試/模組以了解本機命令風格。
3. 編輯最小的 YAML 範圍。
4. 當語法或行為不確定時，執行 lint 或 MCP 驗證。

常見錯誤：

• 在 iOS 測試中使用僅限 Android 的命令。
• 在 v2 YAML 中使用 0..100 之外的百分比座標，或在 MCP CLI 風格步驟字串中使用 0..1 之外的百分比座標。
• 混淆滑動方向與滾動意圖。SCROLL_TO --direction down 搜尋下方內容；SWIPE --direction up 將手指向上移動並顯示下方內容。
• 將步驟 ID、命令 ID、快取 blob 或執行工件加入 YAML。
• 對命令使用錯誤的詳細目標欄位名稱。

npx momentic-mobile lint 驗證行動端 v2 架構與檔案引用。當您在編輯後或移動/重新命名引用的檔案後不確定語法時，執行它。

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

• 活躍的 MCP 工作階段：如果可用，使用重新載入；否則重新啟動工作階段並執行編輯的範圍。
• 沒有活躍的 MCP 工作階段：準備驗證時啟動新的工作階段。
• momentic_test_get 檢查持久化狀態；它不會在磁碟編輯後重新整理活躍的工作階段。

MCP 裝置驗證工作流程

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

探索

• momentic_get_artifacts()：專案上下文、設定路徑、cwd、測試、模組、環境、可用的 AVD、可用的 iOS 模擬器以及受管理的行動資產頻道。僅讀取您需要的內容。
• 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 工具並行。
• 平台從測試推斷。偏好測試的預設模擬器設定。除非使用者明確要求，否則省略提供者/裝置/應用程式覆寫。如果必須選擇提供者，偏好 remote；僅在要求時使用 local。
• 工作階段啟動選項包括 provider、envName、localDeviceId 與 localAppPath。
• 在建構 CLI 風格的行動步驟之前，請先閱讀步驟撰寫指南。
• momentic_run_step({ sessionId, fromStep, toStep?, targetSection?, resetSession? })：執行現有的活躍工作階段步驟。使用來自測試內容或拼接回應的步驟 ID，絕不使用原始 YAML。對頂層步驟使用 parentStepIdChain: []。
• 如果狀態偏移，使用 momentic_run_step 並在相同的 sessionId 上設定 resetSession: true 重新啟動；不要在每次微編輯之間重設。
• momentic_session_terminate({ sessionId })：完成時終止。

測試撰寫循環

以檢查點大小的區塊撰寫 MCP 步驟。向前預覽直到邏輯區塊運作正常，然後拼接該檢查點。好的檢查點是自然的行動流程邊界，例如登入完成、權限處理、表單提交、項目建立或確認可見。除非每個步驟都不確定、有風險或影響共用模組結構，否則避免一次拼接一個步驟。

• momentic_preview_step({ sessionId, step })：執行一個行動步驟而不持久化。它是有狀態的。如果它回傳 CacheId，則在拼接該步驟時包含 --cache-id <CacheId>。回應螢幕截圖顯示步驟後的裝置狀態。
• 如果預覽螢幕截圖不足以定位目標，請呼叫 momentic_get_session_state 並設定 returnBrowserState: true，然後檢查模擬器狀態文字或工件以取得可存取的名稱、可見文字、XML 節點、WebView 結構、螢幕邊界與附近結構。
• 當接下來的幾個步驟明顯且低風險時（例如填寫已知欄位），將它們拼接在一起並執行該儲存的範圍，而不是逐個預覽每個欄位。
• momentic_test_splice_steps({ sessionId, startIndex, deleteCount, steps, targetSection?, parentStepIdChain?, returnTest? })：插入、取代或刪除步驟並持久化。
• 拼接後，立即讀取回應；它是插入/刪除的引用與活躍工作階段步驟 ID 的唯一真相來源。
• 如果 returnTest: true，在繼續之前驗證回傳的結構。
• 如果下游步驟仍然存在，執行緊接的下一個步驟或小範圍以確認流程仍然連接。
• 對於非冪等動作（如提交、購買、刪除、發送或建立），避免重複預覽。預覽設定步驟，在高風險動作之前拼接檢查點，然後僅在驗證需要時執行一次高風險的儲存步驟。
• 對於明顯相鄰的低風險步驟，批次處理它們；除非目標或裝置狀態不確定，否則不要在每個欄位後都設定檢查點。
• 當要求的編輯完成時，詢問是否要透過使用 momentic_run_step 執行相關的儲存範圍來從頭驗證。

讀取工具輸出

工作階段是即時的模擬器/模擬器程序。螢幕截圖與 UI 快照是暫時的。如果螢幕截圖在動作後未顯示預期狀態，請再呼叫一次 momentic_get_session_state；應用程式可能仍在載入。

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

• 模擬器狀態文字：優化定位目標或除錯原生/WebView 結構。
• 螢幕截圖：通常已作為影像內聯回傳。
• 環境檔案：驗證 envKey、JavaScript/API 輸出或相依的環境值。
• 已安裝應用程式報告：當應用程式啟動或安裝行為不明確時，驗證套件/套件狀態。
• momentic_get_session_state 僅在 returnBrowserState: true 時回傳序列化的模擬器狀態；螢幕截圖預設回傳。

CLI 風格步驟字串

preview_step 與 splice_steps 使用 CLI 風格字串：--step-type <TYPE> [options]。由 momentic_session_start 回傳的平台特定步驟撰寫指南是權威的。

常見範例：

• 點擊：--step-type TAP --description "the Continue button"
• 輸入：--step-type TYPE --description "Email field" --value "user@example.com" --clear-content
• AI 檢查：--step-type AI_CHECK --assertion "the confirmation message is visible" --timeout-seconds 10
• 滾動到：--step-type SCROLL_TO --description "Settings" --direction down
• 按鍵：--step-type PRESS --key HOME
• 模組：--step-type MODULE --module-id <id> --inputs email=env.USER_EMAIL

拼接範例：

{
  "sessionId": "SESSION_ID",
  "startIndex": 0,
  "deleteCount": 0,
  "steps": [
    "--step-type TAP --description \"the Continue button\" --cache-id UUID_FROM_PREVIEW",
    "--step-type AI_CHECK --assertion \"the next screen is visible\" --timeout-seconds 10"
  ],
  "targetSection": "main"
}

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

模組

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

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

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

模組 inputs 值是作為字串的 JavaScript 片段。引用字串字面值，將環境變數引用為 env.X，並嚴格遵守列舉約束。

驗證策略

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

疑難排解

裝置狀態與時機

• 錯誤的螢幕/UI：讀取最新的模擬器狀態或呼叫 momentic_get_session_state。
• 螢幕截圖未更新：再呼叫一次 momentic_get_session_state。
• 時機不穩定：偏好 AI_CHECK、SCREEN_CHECK、ELEMENT_CHECK 或針對性的 SCROLL_TO，而非通用的 WAIT。
• 長時間的後端作業/匯入/上傳：使用斷言或螢幕/元素等待並設定適當的超時，而不是使用 sleep。
• 權限對話框或系統表單：在繼續之前明確處理它。
• 奇怪的工作階段狀態：使用 momentic_run_step 並設定 resetSession: true。

定位與快取

• 找不到元素：檢查螢幕截圖/模擬器狀態。如果可見，使用可見文字、角色/名稱與附近上下文改善描述；如果不存在，除錯前置步驟或滾動狀態。
• 快速點擊到錯誤元素或完全沒有 AI：懷疑快取過時，尤其是當螢幕結構與先前的執行相似時。
• 動態目標：將描述改為穩定的，或對該步驟停用快取。
• 座標：僅在語意定位不可用時使用 --x-fraction / --y-fraction。在 MCP CLI 字串中，分數範圍為 0..1。
• 滾動方向：使用 SCROLL_TO --direction down 取得下方內容，使用 SCROLL_TO --direction up 取得上方內容。當沒有特定目標或 SCROLL_TO 不適用時，使用手動 SWIPE。
• 引號文字：描述中的引號子字串會被 Momentic AI 視為字面值。僅當該確切文字必須出現在螢幕上或元素名稱中時才使用引號；對於語意匹配，省略引號。

AI 檢查效能

• 模糊的斷言：使預期的視覺/文字條件具體化。包含相關的螢幕區域、物件、計數或狀態。
• 字面文字不匹配：引號字串被視為必須出現在螢幕上的文字。當意圖是語意匹配時，移除引號。
• 螢幕外：視覺條件（如顏色或形狀）僅在元素可見時才能評估。使用滾動/手勢設定。
• 重複的錯誤判定：改寫斷言，使預期條件更清晰，且舊的記憶體不再適用。
• 暫時條件：AI 檢查會在設定的超時時間內重試，但每次嘗試都是即時快照。偏好穩定的最終狀態斷言；如有必要，使用確定性的元素/螢幕檢查。

格式與資料

• 環境變數值遺失：確認產生步驟使用了 saveAs / --env-key 或 setVariable，且消費語法是 env.X 與 {{ env.X }}。
• 模組輸入錯誤：輸入是作為字串的 JavaScript 片段；引用字串字面值並嚴格遵守列舉約束。
• 應用程式啟動/安裝問題：檢查測試設定、受管理的頻道/標籤、已安裝應用程式工件，以及工作階段是遠端還是本機。
• 平台不匹配：檢查測試 platform 與步驟撰寫指南中平台特定的命令可用性。

完成檢查清單

• 識別 v1 與行動端 v2，並選擇 MCP 或直接編輯。
• 對於 MCP 變更：向前預覽到檢查點，使用快取 ID 拼接，讀取拼接引用，並執行下一個儲存的步驟/範圍。
• 對於 v2 直接編輯：當語法/行為不確定時，執行 lint 或驗證。
• 除非使用者已要求，否則在完整的從頭到尾驗證前先詢問。
• 結束您啟動的任何 MCP 工作階段。