測試 Uiautomator

宣告依附元件

如果要為測試新增依附元件，您必須將 Google Maven 存放區新增至專案。詳情請參閱「Google 的 Maven 存放區」一節。

在應用程式或模組的 build.gradle 檔案中，新增所需構件的依附元件：

dependencies {
    // Use to implement UIAutomator tests
    androidTestImplementation "androidx.test.uiautomator:uiautomator:2.4.0-alpha06"
}

dependencies {
    // Use to implement UIAutomator tests
    androidTestImplementation("androidx.test.uiautomator:uiautomator:2.4.0-alpha06")
}

如要進一步瞭解依附元件，請參閱「新增建構依附元件」一文。

意見回饋

您的意見可協助我們改善 Jetpack。如果您發現新問題，或是有改進這個程式庫的建議，請告訴我們。回報新問題前，請先查看這個程式庫的現有問題。只要按一下星號按鈕，即可投票給現有的問題。

建立新問題

詳情請參閱 Issue Tracker 說明文件。

Test Uiautomator Shell 1.0 版

1.0.0-alpha02 版

2025 年 8 月 13 日

發布 androidx.test.uiautomator:uiautomator-shell:1.0.0-alpha02。1.0.0-alpha02 版包含這些修訂項目。

1.0.0-alpha01 版

2025 年 6 月 18 日

發布 androidx.test.uiautomator:uiautomator-shell:1.0.0-alpha01。1.0.0-alpha01 版包含這些修訂項目。

新功能

• ui-automator shell 程式庫的第一個 Alpha 版，可做為殼層使用者執行殼層指令。這個程式庫可讓您讀取 stdout、stderr，並在殼層啟動的 sh 程序中寫入 stdin。事實上，這會回溯移植 API 34 中導入的 UiAutomation#executeShellCommandRwe。

2.4 版

2.4.0-alpha06 版本

2025 年 8 月 13 日

發布 androidx.test.uiautomator:uiautomator:2.4.0-alpha06。2.4.0-alpha06 版包含這些修訂項目。

新功能

• 新增以視窗為基礎的 API，可改善多視窗測試，也就是現在可根據 By.Window 工廠方法建立的 ByWindowSelector，尋找特定 UiWindow。UiDevice#findWindow(I359c4、I40528、I8c963)

2.4.0-alpha05 版本

2025 年 6 月 18 日

發布 androidx.test.uiautomator:uiautomator:2.4.0-alpha05。2.4.0-alpha05 版包含這些修訂項目。

API 變更

• 新增 UiObject2#waitForStable 做為 UiObject2#accessibilityNodeInfo#waitForStable() 的捷徑

2.4.0-alpha04 版本

2025 年 6 月 4 日

發布 androidx.test.uiautomator:uiautomator:2.4.0-alpha04。2.4.0-alpha04 版包含這些修訂項目。

API 變更

• 已將 onView 重新命名為 onElement，明確指出此項目適用於 Compose (I53a3b、b/419006806)

修正錯誤

• 修正 waitForStableInActiveWindow (290457f1、b/420349130)

2.4.0-alpha03 版

2025 年 5 月 20 日

發布 androidx.test.uiautomator:uiautomator:2.4.0-alpha03。2.4.0-alpha03 版包含這些修訂項目。

修正錯誤

• 修正 waitForStableInActiveWindow 在某些情況下會擲回 NPE 的問題 (Ibf50f、b/417046391)

2.4.0-alpha02 版

2025 年 5 月 7 日

發布 androidx.test.uiautomator:uiautomator:2.4.0-alpha02。2.4.0-alpha02 版包含這些修訂項目。

新功能

• 新 Uiautomator Api 的初始形狀。UiAutomatorTestScope 可透過工廠 uiAutomator 建立，並提供新 onView API 的存取權。
• 初始 Lint 規則，用於警告 AccessibilityNodeInfo#getText 的使用情形，並建議使用 textAsString。

API 變更

• 新增 Configurator#setDefaultDisplayId，可設定顯示 ID，將所有搜尋限制為 (Icdf17)。
• 為方便起見，已將 Searchable (UiDevice 和 UiObject2 共用的介面) 變更為公開 (I67f18)。

修正錯誤

• 修正 UiDevice#pressKeyCodes 中的 Meta 鍵處理方式。(I73f80)。
• 更新 UiDevice#getWindowRoots，一律會依 Z 順序傳回根目錄 (I87426)。
• 修正特定手勢不完整的問題 (I60dd3、If4edd)。
• 修正呼叫 UiDevice#scrollUntil 時發生的罕見無限迴圈問題 (I39989)。

2.4.0-alpha01 版

2024 年 6 月 26 日

發布 androidx.test.uiautomator:uiautomator:2.4.0-alpha01。2.4.0-alpha01 版包含這些修訂項目。

API 變更

• 由於系統現在一律直接插入文字，而非透過按鍵，因此已淘汰 Configurator#getKeyInjectionDelay 和 setKeyInjectionDelay 參數。(I3bcc5)。

修正錯誤

• 更新 UiObject2 動作事件之間的延遲，以因應動態刷新率 (即流暢顯示功能) (I43f12)。
• 定期使無障礙工具快取失效，減少特定 UI 上無障礙工具節點過時造成的錯誤 (I3be25)。
• 修正在過時的 UiObject2 上呼叫 toString 或 hashCode 時發生的 StaleObjectException。(I38ea1)。
• 略過不必要的 waitForIdle 呼叫，提升 UiWatcher 效能。(I8c65e)。
• 修正 Javadoc 錯誤，特別是釐清每個 Configurator 參數的使用時機。(Ie10b1、I71631)。

2.3.0 版本

2.3.0 版本

2024 年 2 月 21 日

發布 androidx.test.uiautomator:uiautomator:2.3.0。2.3.0 版包含此連結所列的修訂項目。

自 2.2.0 版以來的重要變更

• 支援多螢幕：新增支援功能，可尋找及操作跨螢幕的物件，並新增 UiDevice 方法來管理次要螢幕 (Ie6544、I912cd)。
• 新選取器：
  • 新增 By.displayId，可依顯示 ID 選取物件 (I1825b)。
  • 根據父項新增 By.hasParent 和 By.hasAncestor，以選取物件 (I93c36)。
  • 新增 By.hint 方法，可依提示文字選取物件 (Idd345)。
• 自訂條件：公開 Condition 介面以支援自訂等待條件，並新增對應的 UiDevice#wait、UiObject2#wait 和 UiObject2#scrollUntil 方法 (27c0ea、099d6e)。
• 修正錯誤並提升穩定性
  • 修正問題：系統以往偶有螢幕大小計算錯誤的情況，也可能會忽略螢幕的某些部分 (Ifc016)。您可能需要調整測試中使用的座標和位移。
  • 更新 MotionEvent 插入作業，提升準確度 (678ca3)，並更貼切模擬使用者手勢 (454450)。
  • 提升捲動 (I7b059)、旋轉 (c6cea0)、長按 (49572b) 和雙指撥動 (3c619a) 等操作的穩定性。

2.3.0-rc01 版

2024 年 2 月 7 日

androidx.test.uiautomator:uiautomator:2.3.0-rc01 發布，內容無變更。2.3.0-rc01 版包含此連結所列的修訂項目。

2.3.0-beta01 版本

2023 年 12 月 13 日

發布 androidx.test.uiautomator:uiautomator:2.3.0-beta01。2.3.0-beta01 版包含此連結所列的修訂項目。

API 變更

• 為求一致，已將以百分比為準的邊界方法 UiObject2 重新命名為 setGestureMarginPercentage 和 setGestureMarginsPercentage (I24435)

修正錯誤

• 改善找不到或無法存取次要螢幕時擲回的錯誤 (116b23)

2.3.0-alpha05 版本

2023 年 11 月 1 日

發布 androidx.test.uiautomator:uiautomator:2.3.0-alpha05。查看 2.3.0-alpha05 版的修訂項。

API 變更

• 新增 UiObject2#getDrawingOrder，公開繪圖順序 (z-index) 資訊。(I5dfa4)。
• 新增 UiDevice 方法，可取得、設定、凍結及取消凍結次要螢幕的旋轉。(I912cd)。

修正錯誤

• 如果無法偵測到捲動結束，則在 UiObject2#scrollUntil 中新增重試 (Ibac6f)。
• 修正問題：如果重新建立 UiDevice，會使用過時的 Instrumentation 執行個體 (I18cae)。
• 修正節點傾印時 (Icafcb)，如果無法判斷顯示 ID，可能會發生的 NPE。
• 在不可點選/捲動的物件上執行點擊/捲動時，新增警告 (I4a5d9)。
• 降低預設 UiObject2 捲動速度，以提升穩定性 (I5e071)。

2.3.0-alpha04 版本

2023 年 7 月 26 日

發布 androidx.test.uiautomator:uiautomator:2.3.0-alpha04。2.3.0-alpha04 版包含此連結所列的修訂項目。

API 變更

• 新增 By.hasParent 和 By.hasAncestor，支援根據父項尋找物件 (I93c36)。
• 新增 UiObject2#getHint 可擷取物件的提示文字，以及 By.hint 方法可根據提示文字選取物件 (Idd345)。
• 新增 By.displayId，支援根據物件所在的螢幕選取物件 (I1825b)。
• 新增 UiDevice#getDisplayHeight(int) 和 UiDevice#getDisplayWidth(int) 方法，可依 ID (Ie6544) 找出螢幕尺寸。
• 重新新增 wait(SearchCondition, long) 和 wait(UiObject2Condition, long) 方法，確保回溯相容性 (Iebfda)。
• 已將 UiDevice#executeShellCommand 變更為公開，但建議不要使用隱藏的 (Ic48a1)。

修正錯誤

• 更新 MotionEvent 插入功能，優先考量手勢準確度而非速度，以減少不穩定性 (678ca3)。
• 在耗用大量資源的方法中新增追蹤功能，找出效能瓶頸 (d17de3)。
• 新增啟動 UiAutomation 連線時的重試機制 (048caf)。
• 修正 UiDevice#dumpWindowHierarchy 中可能因空值節點而發生的 NPE (b725eb)。
• 修正查詢或操作私人螢幕時發生的非預期錯誤 (985db6、 7053d4)。

2.3.0-alpha03 版本

2023 年 4 月 19 日

發布 androidx.test.uiautomator:uiautomator:2.3.0-alpha03。查看 2.3.0-alpha03 版的修訂項。

API 變更

• 公開 Condition 介面，允許自訂等待條件，而不僅限於 Until 中的內建條件，並更新 UiDevice#wait 和 UiObject2#wait 方法來接受這個介面 (27c0ea)。
• 新增 UiObject2#scrollUntil，支援捲動至符合條件為止，並與 UiScrollable 達到同等程度 (099d6e)。
• 新增 UiDevice#setOrientationPortrait 和 setOrientationLandscape，方便在不同裝置類型之間旋轉 (e13cb7)。
• 新增 UiObject2#setGestureMarginPercent，支援設定與物件大小相關的外邊距。(Ib8c77)

修正錯誤

• 修正 UiScrollable 方法偶爾會在 SDK 18 至 22 上使用無效座標的問題 (b53ece)。
• 修正 UiObject2#setText 和 clearText 無法在 SDK 18 和 19 上修改文字的問題 (77e41d)。
• 修正 UiWatcher 未以正確順序執行的問題 (c85f92)。
• 修正裝置方向變更後，裝置旋轉可能尚未完成的問題 (c6cea0)。UiDevice
• 提升長按、拖曳和雙指撥動的穩定性 (49572b、3c619a)。

2.3.0-alpha02 版

2023 年 1 月 11 日

發布 androidx.test.uiautomator:uiautomator:2.3.0-alpha02。2.3.0-alpha02 版包含此連結所列的修訂項目。

API 變更

• 重新調整整個程式庫的記錄功能，提供更多資訊、針對潛在問題發出警告，並改善一致性。
• 新增 UiDevice#pressKeyCodes，支援同時按下多個按鍵，例如按下 POWER 鍵和 VOLUME_DOWN 鍵來擷取螢幕截圖 (22e525)。
• 新增 UiDevice#setCompressedLayoutHierarchy 並淘汰 UiDevice#setCompressedLayoutHeirarchy，修正方法名稱中的錯字 (4e2f65)。
• 由於 UiAutomatorInstrumentationTestRunner 會處理已淘汰的 UiAutomatorTestCase，因不再需要而標示為已淘汰 (be6c85)。
• 將 UiObject2 MotionEvent 之間的延遲時間更新為螢幕刷新率的兩倍，更加貼切模擬使用者手勢 (454450)。
• 新增對多行文字和說明比對的功能支援 (1625e6、b/255787130)。

修正錯誤

• 修正在查詢或等待物件時，有時會擲回 StaleObjectException 的問題 (4cbcc0)。
• 修正 UiScrollable#scrollToBeginning、scrollToEnd、flingToBeginning 和 flingToEnd 的傳回值不會指出是否已到達開端/尾端的問題 (d33e06)。
• 修正 UiScrollable#scrollForward 和 scrollBackward 方法忽略所設逾時的問題 (29e4f3)。
• 修正 BySelector 複製建構函式無法處理深度選取器的問題 (6c7b91)。
• 修正 UiObject#pinchIn 和 pinchOut 中無效百分比值的處理方式 (01b973)。
• 修正在極罕見情況下，重設基礎 UiAutomation 連線後發生無法支援多視窗模式的問題 (1bb956)。

2.3.0-alpha01 版本

2022 年 9 月 7 日

發布 androidx.test.uiautomator:uiautomator:2.3.0-alpha01。2.3.0-alpha01 版本包含這些修訂項目。

API 變更

• 為所有公開方法的空值加註。
• 加上短暫延遲將 MotionEvent 插入變成非同步狀態，讓 UiObject2 手勢更順暢。
• 減少輪詢間隔，同時將等待時間從 1000 毫秒縮短成 100 毫秒。
• 更新 UiDevice#wakeUp 和 UiDevice#sleep，現在使用 KEYCODE_WAKEUP 和 KEYCODE_SLEEP 支援會覆寫電源鍵功能的裝置。
• 新增 UiObject2#getDisplayId 並支援尋找及管理跨螢幕的物件。
• 新增 UiObject#click 和 UiObject2#clickAndWait 方法，現在可以使用座標點選一個點。

修正錯誤

• 修正問題：系統以往偶有螢幕大小計算錯誤的情況，也可能會忽略螢幕的某些部分 (尤其是在多視窗模式下)，這些問題現在已經修正 (Ifc016c)。
• 修正 UiDevice#takeScreenshot 中的螢幕截圖資源調度 (Id80ad6)。
• 提升 Until.scrollFinished 和 UiObject2#scroll 的穩定性 (I7b0595)。
• 修正嚴格模式 IncorrectContextUseViolation 警告 (Iffa6a0)。