# UiDevice
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDevice.java+class:androidx.test.uiautomator.UiDevice) Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
*** ** * ** ***
```
public class UiDevice implements Searchable
```
*** ** * ** ***
UiDevice provides access to state information about the device. You can also use this class to simulate user actions on the device, such as pressing the d-pad or pressing the Home and Menu buttons.
## Summary
| ### Public methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#clearLastTraversedText()()` Clears the text from the last UI traversal event. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#click(int,int)(int x, int y)` Perform a click at arbitrary coordinates on the default display specified by the user. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#drag(int,int,int,int,int)(int startX, int startY, int endX, int endY, int steps)` Performs a swipe from one coordinate to another coordinate on the default display. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.io.File)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html dest)` Dumps every window's layout hierarchy to a `https://developer.android.com/reference/java/io/File.html` in XML format. |
| `void` | `[dumpWindowHierarchy](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.lang.String))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html fileName)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.io.File)` or `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.io.OutputStream)` instead.
|
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.io.OutputStream)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/OutputStream.html out)` Dumps every window's layout hierarchy to an `https://developer.android.com/reference/java/io/OutputStream.html` in XML format. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html` | `@https://developer.android.com/reference/androidx/annotation/Discouraged(message = "Can be useful for simple commands, but lacks support for proper error" + " handling, input data, or complex commands (quotes, pipes) that can be obtained " + "from UiAutomation#executeShellCommandRwe or similar utilities.") https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#executeShellCommand(java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html cmd)` Executes a shell command using shell user identity, and return the standard output in string. |
| `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#findObject(androidx.test.uiautomator.BySelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/BySelector selector)` Returns the first object to match the `selector` criteria, or null if no matching objects are found. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiObject` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#findObject(androidx.test.uiautomator.UiSelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiSelector selector)` Returns a UiObject which represents a view that matches the specified selector criteria. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#findObjects(androidx.test.uiautomator.BySelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/BySelector selector)` Returns all objects that match the `selector` criteria. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/test/uiautomator/UiWindow` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#findWindow(androidx.test.uiautomator.ByWindowSelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/ByWindowSelector selector)` Returns the first top-level window that matches the `selector` criteria, or null if no matching windows are found. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#findWindows(androidx.test.uiautomator.ByWindowSelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/ByWindowSelector selector)` Returns all windows that match the `selector` criteria. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#freezeRotation()()` Freezes the default display rotation at its current state. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 30) https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#freezeRotation(int)(int displayId)` Freezes the rotation of the display with `displayId` at its current state. |
| `https://developer.android.com/reference/java/lang/String.html` | `[getCurrentActivityName](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getCurrentActivityName())()` **This method is deprecated.** The results returned should be considered unreliable
|
| `https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getCurrentPackageName()()` Retrieves the name of the last package to report accessibility events. |
| `@https://developer.android.com/reference/androidx/annotation/Px int` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getDisplayHeight()()` Gets the height of the default display, in pixels. |
| `@https://developer.android.com/reference/androidx/annotation/Px int` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getDisplayHeight(int)(int displayId)` Gets the height of the display with `displayId`, in pixels. |
| `int` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getDisplayRotation()()` |
| `int` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getDisplayRotation(int)(int displayId)` |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Point.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getDisplaySizeDp()()` Returns the default display size in dp (device-independent pixel). |
| `@https://developer.android.com/reference/androidx/annotation/Px int` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getDisplayWidth()()` Gets the width of the default display, in pixels. |
| `@https://developer.android.com/reference/androidx/annotation/Px int` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getDisplayWidth(int)(int displayId)` Gets the width of the display with `displayId`, in pixels. |
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiDevice` | `[getInstance](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getInstance())()` **This method is deprecated.** Should use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getInstance(android.app.Instrumentation)` instead.
|
| `static @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiDevice` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getInstance(android.app.Instrumentation)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/app/Instrumentation.html instrumentation)` Retrieves a singleton instance of UiDevice. |
| `https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getLastTraversedText()()` Retrieves the text from the last UI traversal event received. |
| `https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getLauncherPackageName()()` Retrieves the default launcher package name. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getProductName()()` Retrieves the product name of the device. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getWindowRoots()()` Returns a list containing the root `https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html`s for each active window. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#hasAnyWatcherTriggered()()` Checks if any registered `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` have triggered. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#hasObject(androidx.test.uiautomator.BySelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/BySelector selector)` Returns whether there is a match for the given `selector` criteria. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#hasWatcherTriggered(java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html watcherName)` Checks if a specific registered `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` has triggered. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#hasWindow(androidx.test.uiautomator.ByWindowSelector)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/ByWindowSelector selector)` Returns whether there is a window match for the given `selector` criteria. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#isNaturalOrientation()()` |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#isScreenOn()()` Checks the power manager if the default display is ON. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#openNotification()()` Opens the notification shade. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#openQuickSettings()()` Opens the Quick Settings shade. |
| `U` | ` https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#performActionAndWait(java.lang.Runnable,androidx.test.uiautomator.EventCondition,long)( @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/Runnable.html action, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/EventCondition condition, long timeout )` Performs the provided `action` and waits for the `condition` to be met. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressBack()()` Simulates a short press on the BACK button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressDPadCenter()()` Simulates a short press on the CENTER button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressDPadDown()()` Simulates a short press on the DOWN button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressDPadLeft()()` Simulates a short press on the LEFT button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressDPadRight()()` Simulates a short press on the RIGHT button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressDPadUp()()` Simulates a short press on the UP button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressDelete()()` Simulates a short press on the DELETE key. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressEnter()()` Simulates a short press on the ENTER key. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressHome()()` Simulates a short press on the HOME button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressKeyCode(int)(int keyCode)` Simulates a short press using a key code. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressKeyCode(int,int)(int keyCode, int metaState)` Simulates a short press using a key code. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressKeyCodes(int[])(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html int[] keyCodes)` Presses one or more keys. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressKeyCodes(int[],int)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html int[] keyCodes, int metaState)` Presses one or more keys. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressMenu()()` Simulates a short press on the MENU button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressRecentApps()()` Simulates a short press on the Recent Apps button. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#pressSearch()()` Simulates a short press on the SEARCH button. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html name, @https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher watcher)` Registers a `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` to run automatically when the testing framework is unable to find a match using a `https://developer.android.com/reference/androidx/test/uiautomator/UiSelector`. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#removeWatcher(java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html name)` Removes a previously registered `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher`. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#resetWatcherTriggers()()` Resets a `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` that has been triggered. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#runWatchers()()` This method forces all registered watchers to run. |
| `void` | `[setCompressedLayoutHeirarchy](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setCompressedLayoutHeirarchy(boolean))(boolean compressed)` **This method is deprecated.** Typo in function name, should use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setCompressedLayoutHierarchy(boolean)` instead.
|
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setCompressedLayoutHierarchy(boolean)(boolean compressed)` Enables or disables layout hierarchy compression. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape()()` Orients the default display to its landscape orientation (width \>= height) and freezes rotation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 30) https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape(int)(int displayId)` Orients the display with `displayId` to its landscape orientation (width \>= height) and freezes rotation. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLeft()()` Orients the default display to the left and freezes rotation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 30) https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLeft(int)(int displayId)` Orients the display with `displayId` to the left and freezes rotation. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationNatural()()` Orients the default display to its natural orientation and freezes rotation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 30) https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationNatural(int)(int displayId)` Orients the display with `displayId` to its natural orientation and freezes rotation . |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait()()` Orients the default display to its portrait orientation (height \>= width) and freezes rotation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 30) https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait(int)(int displayId)` Orients the display with `displayId` to its portrait orientation (height \>= width) and freezes rotation. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationRight()()` Orients the default display to the right and freezes rotation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 30) https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationRight(int)(int displayId)` Orients the display with `displayId` to the right and freezes rotation. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#sleep()()` This method simply presses the power button if the default display is ON, else it does nothing if the default display is already OFF. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#swipe(android.graphics.Point[],int)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html Point[] segments, int segmentSteps)` Performs a swipe between points in the Point array on the default display. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#swipe(int,int,int,int,int)(int startX, int startY, int endX, int endY, int steps)` Performs a swipe from one coordinate to another on the default display using the number of steps to determine smoothness and speed. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/graphics/Bitmap.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#takeScreenshot()()` Take a screenshot of the default display. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#takeScreenshot(java.io.File)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html storePath)` Take a screenshot of the default display and store it as PNG Default scale of 1.0f (original size) and 90% quality is used The screenshot is adjusted per screen rotation |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#takeScreenshot(java.io.File,float,int)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html storePath, float scale, int quality)` Take a screenshot of the default display and store it as PNG The screenshot is adjusted per screen rotation |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()()` Un-freezes the default display rotation allowing its contents to rotate with its physical rotation. |
| `void` | `@https://developer.android.com/reference/androidx/annotation/RequiresApi(value = 30) https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation(int)(int displayId)` Un-freezes the rotation of the display with `displayId` allowing its contents to rotate with its physical rotation. |
| `U` | ` https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#wait(androidx.test.uiautomator.Condition,long)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/Condition condition, long timeout)` Waits for given the `condition` to be met. |
| `U` | ` https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#wait(androidx.test.uiautomator.SearchCondition,long)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/SearchCondition condition, long timeout)` Waits for given the `condition` to be met. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#waitForIdle()()` Waits for the current application to idle. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#waitForIdle(long)(long timeout)` Waits for the current application to idle. |
| `boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#waitForWindowUpdate(java.lang.String,long)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html packageName, long timeout)` Waits for a window content update event to occur. |
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#wakeUp()()` This method simulates pressing the power button if the default display is OFF, else it does nothing if the default display is already ON. |
| ### Extension functions |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityWindowInfo.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).activeWindow()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver)` Returns the active window. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, long timeoutMs, long pollIntervalMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block )` Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `final https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, long timeoutMs, long pollIntervalMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block )` Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2>` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, long timeoutMs, long pollIntervalMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block )` Performs a DFS on the accessibility tree starting from this node and returns all the nodes matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).pressDelete(kotlin.Int)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, int count)` Similar to `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).pressDelete(kotlin.Int)` times. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).type(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html text)` Types the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).type(kotlin.String)` string simulating key press through `https://developer.android.com/reference/android/app/Instrumentation.html#sendKeySync(android.view.KeyEvent)`. |
| `final boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).waitForAppToBeVisible(kotlin.String,kotlin.Long)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html appPackageName, long timeoutMs )` Waits for an application to become visible. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).waitForRootInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, long timeoutMs, long sleepIntervalMs, boolean clearCache )` Waits for the root node to become available in this window. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/StableResult` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, long stableTimeoutMs, long stableIntervalMs, long stablePollIntervalMs, boolean requireStableScreenshot )` Waits for the root node of the active window to become stable. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityWindowInfo.html>` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt.https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#(androidx.test.uiautomator.UiDevice).windows()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver)` Returns all the windows on all the displays. |
## Public methods
### clearLastTraversedText
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void clearLastTraversedText()
```
Clears the text from the last UI traversal event. See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getLastTraversedText()`.
### click
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean click(int x, int y)
```
Perform a click at arbitrary coordinates on the default display specified by the user.
| Parameters |
|---|---|
| `int x` | coordinate |
| `int y` | coordinate |
| Returns |
|---|---|
| `boolean` | true if the click succeeded else false |
### drag
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean drag(int startX, int startY, int endX, int endY, int steps)
```
Performs a swipe from one coordinate to another coordinate on the default display. You can control the smoothness and speed of the swipe by specifying the number of steps. Each step execution is throttled to the length of a frame per step (throttled by VSync).
| Parameters |
|---|---|
| `int startX` | X-axis value for the starting coordinate |
| `int startY` | Y-axis value for the starting coordinate |
| `int endX` | X-axis value for the ending coordinate |
| `int endY` | Y-axis value for the ending coordinate |
| `int steps` | is the number of steps for the swipe action |
| Returns |
|---|---|
| `boolean` | true if swipe is performed, false if the operation fails or the coordinates are invalid |
### dumpWindowHierarchy
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void dumpWindowHierarchy(@NonNull File dest)
```
Dumps every window's layout hierarchy to a `https://developer.android.com/reference/java/io/File.html` in XML format.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html dest` | The file in which to store the window hierarchy information. |
| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` | if an I/O error occurs |
### dumpWindowHierarchy
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0) Deprecated in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void [dumpWindowHierarchy](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.lang.String))(@NonNull String fileName)
```
> [!CAUTION]
> **This method is deprecated.**
>
> Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.io.File)` or `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#dumpWindowHierarchy(java.io.OutputStream)` instead.
Dumps every window's layout hierarchy to a file in XML format.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html fileName` | The file path in which to store the window hierarchy information. Relative file paths are stored the application's internal private storage location. |
### dumpWindowHierarchy
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void dumpWindowHierarchy(@NonNull OutputStream out)
```
Dumps every window's layout hierarchy to an `https://developer.android.com/reference/java/io/OutputStream.html` in XML format.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/OutputStream.html out` | The output stream that the window hierarchy information is written to. |
| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` | if an I/O error occurs |
### executeShellCommand
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@Discouraged(message = "Can be useful for simple commands, but lacks support for proper error"
+ " handling, input data, or complex commands (quotes, pipes) that can be obtained "
+ "from UiAutomation#executeShellCommandRwe or similar utilities.")
public @NonNull String executeShellCommand(@NonNull String cmd)
```
Executes a shell command using shell user identity, and return the standard output in string.
Calling function with large amount of output will have memory impacts, and the function call will block if the command executed is blocking.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html cmd` | the command to run |
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html` | the standard output of the command |
| Throws |
|---|---|
| `https://developer.android.com/reference/java/io/IOException.html` | if an I/O error occurs while reading output |
### findObject
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public UiObject2 findObject(@NonNull BySelector selector)
```
Returns the first object to match the `selector` criteria, or null if no matching objects are found.
### findObject
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public @NonNull UiObject findObject(@NonNull UiSelector selector)
```
Returns a UiObject which represents a view that matches the specified selector criteria.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiSelector selector` | |
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiObject` | UiObject object |
### findObjects
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public @NonNull List findObjects(@NonNull BySelector selector)
```
Returns all objects that match the `selector` criteria.
### findWindow
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
public @Nullable UiWindow findWindow(@NonNull ByWindowSelector selector)
```
Returns the first top-level window that matches the `selector` criteria, or null if no matching windows are found.
### findWindows
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
public @NonNull List findWindows(@NonNull ByWindowSelector selector)
```
Returns all windows that match the `selector` criteria. For convenience the returned list is sorted in descending layer Z-order, ensuring the root of the topmost interactable window is reported first.
### freezeRotation
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void freezeRotation()
```
Freezes the default display rotation at its current state.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### freezeRotation
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@RequiresApi(value = 30)
public void freezeRotation(int displayId)
```
Freezes the rotation of the display with `displayId` at its current state.
Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
### getCurrentActivityName
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0) Deprecated in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public String [getCurrentActivityName](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getCurrentActivityName())()
```
> [!CAUTION]
> **This method is deprecated.**
>
> The results returned should be considered unreliable
Retrieves the last activity to report accessibility events.
| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html` | String name of activity |
### getCurrentPackageName
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public String getCurrentPackageName()
```
Retrieves the name of the last package to report accessibility events.
| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html` | String name of package |
### getDisplayHeight
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public @Px int getDisplayHeight()
```
Gets the height of the default display, in pixels. The size is adjusted based on the current orientation of the display.
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Px int` | height in pixels |
### getDisplayHeight
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public @Px int getDisplayHeight(int displayId)
```
Gets the height of the display with `displayId`, in pixels. The size is adjusted based on the current orientation of the display.
| Parameters |
|---|---|
| `int displayId` | the display ID. Use `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` to get the ID. |
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Px int` | height in pixels |
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
### getDisplayRotation
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public int getDisplayRotation()
```
| Returns |
|---|---|
| `int` | the current rotation of the default display |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getRotation()` | |
### getDisplayRotation
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public int getDisplayRotation(int displayId)
```
| Returns |
|---|---|
| `int` | the current rotation of the display with `displayId` |
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
| `https://developer.android.com/reference/android/view/Display.html#getRotation()` | |
### getDisplaySizeDp
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public @NonNull Point getDisplaySizeDp()
```
Returns the default display size in dp (device-independent pixel).
The returned display size is adjusted per screen rotation. Also this will return the actual size of the screen, rather than adjusted per system decorations (like status bar).
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/android/graphics/Point.html` | a Point containing the display size in dp |
| See also |
|---|---|
| `https://developer.android.com/reference/android/util/DisplayMetrics.html#density` | |
### getDisplayWidth
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public @Px int getDisplayWidth()
```
Gets the width of the default display, in pixels. The size is adjusted based on the current orientation of the display.
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Px int` | width in pixels |
### getDisplayWidth
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public @Px int getDisplayWidth(int displayId)
```
Gets the width of the display with `displayId`, in pixels. The size is adjusted based on the current orientation of the display.
| Parameters |
|---|---|
| `int displayId` | the display ID. Use `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` to get the ID. |
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/Px int` | width in pixels |
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
### getInstance
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0) Deprecated in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public static @NonNull UiDevice [getInstance](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getInstance())()
```
> [!CAUTION]
> **This method is deprecated.**
>
> Should use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#getInstance(android.app.Instrumentation)` instead. This version hides UiDevice's dependency on having an Instrumentation reference and is prone to misuse.
Retrieves a singleton instance of UiDevice
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiDevice` | UiDevice instance |
### getInstance
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public static @NonNull UiDevice getInstance(@NonNull Instrumentation instrumentation)
```
Retrieves a singleton instance of UiDevice. A new instance will be created if instrumentation is also new.
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/UiDevice` | UiDevice instance |
### getLastTraversedText
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public String getLastTraversedText()
```
Retrieves the text from the last UI traversal event received. You can use this method to read the contents in a WebView container because the accessibility framework fires events as each text is highlighted. You can write a test to perform directional arrow presses to focus on different elements inside a WebView, and call this method to get the text from each traversed element. If you are testing a view container that can return a reference to a Document Object Model (DOM) object, your test should use the view's DOM instead.
| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html` | text of the last traversal event, else return an empty string |
### getLauncherPackageName
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public String getLauncherPackageName()
```
Retrieves the default launcher package name.
As of Android 11 (API level 30), apps must declare the packages and intents they intend to query. To use this method, an app will need to include the following in its manifest:
```
```
| Returns |
|---|---|
| `https://developer.android.com/reference/java/lang/String.html` | package name of the default launcher |
### getProductName
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public @NonNull String getProductName()
```
Retrieves the product name of the device. This method provides information on what type of device the test is running on. This value is the same as returned by invoking #adb shell getprop ro.product.name.
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html` | product name of the device |
### getWindowRoots
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
public @NonNull List getWindowRoots()
```
Returns a list containing the root `https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html`s for each active window. For convenience the returned list is sorted in descending window order, ensuring the root of the topmost visible window is reported first.
### hasAnyWatcherTriggered
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean hasAnyWatcherTriggered()
```
Checks if any registered `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` have triggered. See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)` See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#hasWatcherTriggered(java.lang.String)`
### hasObject
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean hasObject(@NonNull BySelector selector)
```
Returns whether there is a match for the given `selector` criteria.
### hasWatcherTriggered
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean hasWatcherTriggered(@Nullable String watcherName)
```
Checks if a specific registered `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` has triggered. See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)`. If a UiWatcher runs and its `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher#checkForCondition()` call returned `true`, then the UiWatcher is considered triggered. This is helpful if a watcher is detecting errors from ANR or crash dialogs and the test needs to know if a UiWatcher has been triggered.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html watcherName` | |
| Returns |
|---|---|
| `boolean` | true if triggered else false |
### hasWindow
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
public boolean hasWindow(@NonNull ByWindowSelector selector)
```
Returns whether there is a window match for the given `selector` criteria.
### isNaturalOrientation
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean isNaturalOrientation()
```
| Returns |
|---|---|
| `boolean` | true if default display is in its natural or flipped (180 degrees) orientation |
### isScreenOn
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean isScreenOn()
```
Checks the power manager if the default display is ON.
| Returns |
|---|---|
| `boolean` | true if the screen is ON else false |
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | |
### openNotification
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean openNotification()
```
Opens the notification shade.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### openQuickSettings
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean openQuickSettings()
```
Opens the Quick Settings shade.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### performActionAndWait
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public U performActionAndWait(
@NonNull Runnable action,
@NonNull EventCondition condition,
long timeout
)
```
Performs the provided `action` and waits for the `condition` to be met.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/Runnable.html action` | The `https://developer.android.com/reference/java/lang/Runnable.html` action to perform. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/EventCondition condition` | The `https://developer.android.com/reference/androidx/test/uiautomator/EventCondition` to evaluate. |
| `long timeout` | Maximum amount of time to wait in milliseconds. |
| Returns |
|---|---|
| `U` | The final result returned by the condition. |
### pressBack
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressBack()
```
Simulates a short press on the BACK button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressDPadCenter
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressDPadCenter()
```
Simulates a short press on the CENTER button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressDPadDown
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressDPadDown()
```
Simulates a short press on the DOWN button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressDPadLeft
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressDPadLeft()
```
Simulates a short press on the LEFT button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressDPadRight
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressDPadRight()
```
Simulates a short press on the RIGHT button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressDPadUp
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressDPadUp()
```
Simulates a short press on the UP button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressDelete
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressDelete()
```
Simulates a short press on the DELETE key.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressEnter
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressEnter()
```
Simulates a short press on the ENTER key.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressHome
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressHome()
```
Simulates a short press on the HOME button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressKeyCode
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressKeyCode(int keyCode)
```
Simulates a short press using a key code. See `https://developer.android.com/reference/android/view/KeyEvent.html`
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressKeyCode
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressKeyCode(int keyCode, int metaState)
```
Simulates a short press using a key code. See `https://developer.android.com/reference/android/view/KeyEvent.html`.
| Parameters |
|---|---|
| `int keyCode` | the key code of the event. |
| `int metaState` | an integer in which each bit set to 1 represents a pressed meta key |
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressKeyCodes
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public boolean pressKeyCodes(@NonNull int[] keyCodes)
```
Presses one or more keys. Keys that change meta state are supported, and will apply their meta state to following keys. For example, you can simulate taking a screenshot on the device by pressing both the power and volume down keys.
```
pressKeyCodes(new int[]{KeyEvent.KEYCODE_POWER, KeyEvent.KEYCODE_VOLUME_DOWN})
```
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html int[] keyCodes` | array of key codes. |
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/KeyEvent.html` | |
### pressKeyCodes
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public boolean pressKeyCodes(@NonNull int[] keyCodes, int metaState)
```
Presses one or more keys. Keys that change meta state are supported, and will apply their meta state to following keys. For example, you can simulate taking a screenshot on the device by pressing both the power and volume down keys.
```
pressKeyCodes(new int[]{KeyEvent.KEYCODE_POWER, KeyEvent.KEYCODE_VOLUME_DOWN})
```
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html int[] keyCodes` | array of key codes. |
| `int metaState` | an integer in which each bit set to 1 represents a pressed meta key |
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/KeyEvent.html` | |
### pressMenu
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressMenu()
```
Simulates a short press on the MENU button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### pressRecentApps
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressRecentApps()
```
Simulates a short press on the Recent Apps button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### pressSearch
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean pressSearch()
```
Simulates a short press on the SEARCH button.
| Returns |
|---|---|
| `boolean` | true if successful, else return false |
### registerWatcher
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void registerWatcher(@Nullable String name, @Nullable UiWatcher watcher)
```
Registers a `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` to run automatically when the testing framework is unable to find a match using a `https://developer.android.com/reference/androidx/test/uiautomator/UiSelector`. See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#runWatchers()`
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html name` | to register the UiWatcher |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher watcher` | `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` |
### removeWatcher
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void removeWatcher(@Nullable String name)
```
Removes a previously registered `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher`. See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)`
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html name` | used to register the UiWatcher |
### resetWatcherTriggers
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void resetWatcherTriggers()
```
Resets a `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher` that has been triggered. If a UiWatcher runs and its `https://developer.android.com/reference/androidx/test/uiautomator/UiWatcher#checkForCondition()` call returned `true`, then the UiWatcher is considered triggered. See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)`
### runWatchers
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void runWatchers()
```
This method forces all registered watchers to run. See `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)`
### setCompressedLayoutHeirarchy
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0) Deprecated in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public void [setCompressedLayoutHeirarchy](https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setCompressedLayoutHeirarchy(boolean))(boolean compressed)
```
> [!CAUTION]
> **This method is deprecated.**
>
> Typo in function name, should use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setCompressedLayoutHierarchy(boolean)` instead.
Enables or disables layout hierarchy compression. If compression is enabled, the layout hierarchy derived from the Acessibility framework will only contain nodes that are important for uiautomator testing. Any unnecessary surrounding layout nodes that make viewing and searching the hierarchy inefficient are removed.
| Parameters |
|---|---|
| `boolean compressed` | true to enable compression; else, false to disable |
### setCompressedLayoutHierarchy
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public void setCompressedLayoutHierarchy(boolean compressed)
```
Enables or disables layout hierarchy compression. If compression is enabled, the layout hierarchy derived from the Accessibility framework will only contain nodes that are important for uiautomator testing. Any unnecessary surrounding layout nodes that make viewing and searching the hierarchy inefficient are removed.
| Parameters |
|---|---|
| `boolean compressed` | true to enable compression; else, false to disable |
### setOrientationLandscape
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public void setOrientationLandscape()
```
Orients the default display to its landscape orientation (width \>= height) and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### setOrientationLandscape
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@RequiresApi(value = 30)
public void setOrientationLandscape(int displayId)
```
Orients the display with `displayId` to its landscape orientation (width \>= height) and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
### setOrientationLeft
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void setOrientationLeft()
```
Orients the default display to the left and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait()` and `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape()`.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### setOrientationLeft
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@RequiresApi(value = 30)
public void setOrientationLeft(int displayId)
```
Orients the display with `displayId` to the left and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait()` and `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape()`.
Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
### setOrientationNatural
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void setOrientationNatural()
```
Orients the default display to its natural orientation and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: The natural orientation depends on the device type (e.g. phone vs. tablet). Consider using `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait()` and `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape()`.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### setOrientationNatural
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@RequiresApi(value = 30)
public void setOrientationNatural(int displayId)
```
Orients the display with `displayId` to its natural orientation and freezes rotation . Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: The natural orientation depends on the device type (e.g. phone vs. tablet). Consider using `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait()` and `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape()`.
Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
### setOrientationPortrait
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public void setOrientationPortrait()
```
Orients the default display to its portrait orientation (height \>= width) and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### setOrientationPortrait
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@RequiresApi(value = 30)
public void setOrientationPortrait(int displayId)
```
Orients the display with `displayId` to its portrait orientation (height \>= width) and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
### setOrientationRight
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void setOrientationRight()
```
Orients the default display to the right and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait()` and `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape()`.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### setOrientationRight
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@RequiresApi(value = 30)
public void setOrientationRight(int displayId)
```
Orients the display with `displayId` to the right and freezes rotation. Use `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#unfreezeRotation()` to un-freeze the rotation.
Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationPortrait()` and `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#setOrientationLandscape()`.
Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.
| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | when the display with `displayId` is not accessible. |
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
### sleep
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void sleep()
```
This method simply presses the power button if the default display is ON, else it does nothing if the default display is already OFF.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | |
### swipe
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean swipe(@NonNull Point[] segments, int segmentSteps)
```
Performs a swipe between points in the Point array on the default display. Each step execution is throttled to the length of a frame per step (throttled by VSync).
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html Point[] segments` | is Point array containing at least one Point object |
| `int segmentSteps` | steps to inject between two Points |
| Returns |
|---|---|
| `boolean` | true on success |
### swipe
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean swipe(int startX, int startY, int endX, int endY, int steps)
```
Performs a swipe from one coordinate to another on the default display using the number of steps to determine smoothness and speed. Each step execution is throttled to the length of a frame per step (throttled by VSync).
| Parameters |
|---|---|
| `int startX` | X-axis value for the starting coordinate |
| `int startY` | Y-axis value for the starting coordinate |
| `int endX` | X-axis value for the ending coordinate |
| `int endY` | Y-axis value for the ending coordinate |
| `int steps` | is the number of move steps sent to the system |
| Returns |
|---|---|
| `boolean` | false if the operation fails or the coordinates are invalid |
### takeScreenshot
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
public @Nullable Bitmap takeScreenshot()
```
Take a screenshot of the default display.
The screenshot is adjusted per screen rotation.
| Returns |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/android/graphics/Bitmap.html` | The screenshot bitmap on success, `null` otherwise |
| See also |
|---|---|
| `https://developer.android.com/reference/android/app/UiAutomation.html#takeScreenshot()` | |
### takeScreenshot
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean takeScreenshot(@NonNull File storePath)
```
Take a screenshot of the default display and store it as PNG Default scale of 1.0f (original size) and 90% quality is used The screenshot is adjusted per screen rotation
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html storePath` | where the PNG should be written to |
| Returns |
|---|---|
| `boolean` | true if screen shot is created successfully, false otherwise |
### takeScreenshot
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean takeScreenshot(@NonNull File storePath, float scale, int quality)
```
Take a screenshot of the default display and store it as PNG The screenshot is adjusted per screen rotation
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/io/File.html storePath` | where the PNG should be written to |
| `float scale` | scale the screenshot down if needed; 1.0f for original size |
| `int quality` | quality of the PNG compression; range: 0-100 |
| Returns |
|---|---|
| `boolean` | true if screen shot is created successfully, false otherwise |
### unfreezeRotation
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void unfreezeRotation()
```
Un-freezes the default display rotation allowing its contents to rotate with its physical rotation. During testing, it is best to keep the default display frozen in a specific orientation.
Note: Need to wait a short period for the rotation animation to complete before performing another operation.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | never |
### unfreezeRotation
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
@RequiresApi(value = 30)
public void unfreezeRotation(int displayId)
```
Un-freezes the rotation of the display with `displayId` allowing its contents to rotate with its physical rotation. During testing, it is best to keep the display frozen in a specific orientation.
Note: Need to wait a short period for the rotation animation to complete before performing another operation.
Note: Some secondary displays don't have rotation sensors and therefore won't respond to this method.
Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.
| See also |
|---|---|
| `https://developer.android.com/reference/android/view/Display.html#getDisplayId()` | |
### wait
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public U wait(@NonNull Condition condition, long timeout)
```
Waits for given the `condition` to be met.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/Condition condition` | The `https://developer.android.com/reference/androidx/test/uiautomator/Condition` to evaluate. |
| `long timeout` | Maximum amount of time to wait in milliseconds. |
| Returns |
|---|---|
| `U` | The final result returned by the `condition`, or null if the `condition` was not met before the `timeout`. |
### wait
Added in [2.3.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.3.0)
```
public U wait(@NonNull SearchCondition condition, long timeout)
```
Waits for given the `condition` to be met.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/test/uiautomator/SearchCondition condition` | The `https://developer.android.com/reference/androidx/test/uiautomator/SearchCondition` to evaluate. |
| `long timeout` | Maximum amount of time to wait in milliseconds. |
| Returns |
|---|---|
| `U` | The final result returned by the `condition`, or null if the `condition` was not met before the `timeout`. |
### waitForIdle
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void waitForIdle()
```
Waits for the current application to idle.
**Note:** Usage of this API in tests will result in non-deterministic tests. So this API should only be used as a last resort and **only** when there are no other alternatives available.
Default wait timeout is 10 seconds
### waitForIdle
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void waitForIdle(long timeout)
```
Waits for the current application to idle.
**Note:** Usage of this API in tests will result in non-deterministic tests. So this API should only be used as a last resort and **only** when there are no other alternatives available.
| Parameters |
|---|---|
| `long timeout` | in milliseconds |
### waitForWindowUpdate
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public boolean waitForWindowUpdate(@Nullable String packageName, long timeout)
```
Waits for a window content update event to occur. If a package name for the window is specified, but the current window does not have the same package name, the function returns immediately.
| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/String.html packageName` | the specified window package name (can be `null`). If `null`, a window update from any front-end window will end the wait |
| `long timeout` | the timeout for the wait |
| Returns |
|---|---|
| `boolean` | true if a window update occurred, false if timeout has elapsed or if the current window does not have the specified package name |
### wakeUp
Added in [2.2.0](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.2.0)
```
public void wakeUp()
```
This method simulates pressing the power button if the default display is OFF, else it does nothing if the default display is already ON.
If the default display was OFF and it just got turned ON, this method will insert a 500ms delay for the device to wake up and accept input.
| Throws |
|---|---|
| `https://developer.android.com/reference/android/os/RemoteException.html` | |
## Extension functions
### UiDeviceExt.activeWindow
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:activeWindow)
```
public final @NonNull AccessibilityWindowInfo UiDeviceExt.activeWindow(@NonNull UiDevice receiver)
```
Returns the active window.
### UiDeviceExt.onElement
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:onElement)
```
public final @NonNull UiObject2 UiDeviceExt.onElement(
@NonNull UiDevice receiver,
long timeoutMs,
long pollIntervalMs,
@NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```
Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` that allows interacting with it. If the requested node doesn't exist, a `https://developer.android.com/reference/androidx/test/uiautomator/ElementNotFoundException` is thrown. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`.
Example:
```
uiDevice.onElement { textAsString == "Search" }.click()
```
| Parameters |
|---|---|
| `long timeoutMs` | a timeout to find the element that satisfies the given condition. |
| `long pollIntervalMs` | an interval to wait before rechecking the accessibility tree for updates. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block` | a block that specifies a condition on the node to find. |
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | a `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` from a node that matches the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |
### UiDeviceExt.onElementOrNull
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:onElementOrNull)
```
public final UiObject2 UiDeviceExt.onElementOrNull(
@NonNull UiDevice receiver,
long timeoutMs,
long pollIntervalMs,
@NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```
Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` that allows interacting with it. If the requested node doesn't exist, null is returned. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`.
Example:
```
uiDevice.onElement { textAsString == "Search" }.click()
```
| Parameters |
|---|---|
| `long timeoutMs` | a timeout to find the element that satisfies the given condition. |
| `long pollIntervalMs` | an interval to wait before rechecking the accessibility tree for updates. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block` | a block that specifies a condition on the node to find. |
| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | a `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` from a node that matches the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)` condition or null. |
### UiDeviceExt.onElements
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:onElements)
```
public final @NonNull List<@NonNull UiObject2> UiDeviceExt.onElements(
@NonNull UiDevice receiver,
long timeoutMs,
long pollIntervalMs,
@NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```
Performs a DFS on the accessibility tree starting from this node and returns all the nodes matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` that allow interacting with them. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`.
Example:
```
node.onElements { className == Button::class.java.name }
```
If multiple nodes are expected but they appear at different times, it's recommended to call `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(android.view.accessibility.AccessibilityNodeInfo).waitForStable(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)` before, to ensure any operation is complete.
| Parameters |
|---|---|
| `long timeoutMs` | a timeout to find the element that satisfies the given condition. |
| `long pollIntervalMs` | an interval to wait before rechecking the accessibility tree for updates. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block` | a block that specifies a condition on the node to find. |
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2>` | a list of `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` from nodes that matches the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |
### UiDeviceExt.pressDelete
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:pressDelete)
```
public final void UiDeviceExt.pressDelete(@NonNull UiDevice receiver, int count)
```
Similar to `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).pressDelete(kotlin.Int)` times.
| Parameters |
|---|---|
| `int count` | how many times the press delete key should be pressed. |
### UiDeviceExt.type
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:type)
```
public final void UiDeviceExt.type(@NonNull UiDevice receiver, @NonNull String text)
```
Types the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).type(kotlin.String)` string simulating key press through `https://developer.android.com/reference/android/app/Instrumentation.html#sendKeySync(android.view.KeyEvent)`. This is similar to tapping the keys on a virtual keyboard and will trigger the same listeners in the target app, as opposed to `https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html#setText(java.lang.CharSequence)` that programmatically sets the given text in the target node.
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html text` | the text to type. |
### UiDeviceExt.waitForAppToBeVisible
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:waitForAppToBeVisible)
```
public final boolean UiDeviceExt.waitForAppToBeVisible(
@NonNull UiDevice receiver,
@NonNull String appPackageName,
long timeoutMs
)
```
Waits for an application to become visible. Note that internally it checks if an accessibility node with the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).waitForAppToBeVisible(kotlin.String,kotlin.Long)` exists in the accessibility tree.
| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html appPackageName` | the package name of the app to wait for. By default is the target app package name. |
| `long timeoutMs` | a timeout for the app to become visible. |
| Returns |
|---|---|
| `boolean` | whether the app became visible in the given timeout. |
### UiDeviceExt.waitForRootInActiveWindow
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:waitForRootInActiveWindow)
```
public final @NonNull AccessibilityNodeInfo UiDeviceExt.waitForRootInActiveWindow(
@NonNull UiDevice receiver,
long timeoutMs,
long sleepIntervalMs,
boolean clearCache
)
```
Waits for the root node to become available in this window.
| Parameters |
|---|---|
| `long timeoutMs` | a timeout for the root node to become available. |
| `long sleepIntervalMs` | a interval to wait before retrying checking if the node is available. |
| `boolean clearCache` | whether the accessibility nodes cache should be cleared when checking. |
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html` | the root node for this window. |
| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the root node in the active window cannot be acquired before the give timeout `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).waitForRootInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Boolean)`. |
### UiDeviceExt.waitForStableInActiveWindow
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:waitForStableInActiveWindow)
```
public final @NonNull StableResult UiDeviceExt.waitForStableInActiveWindow(
@NonNull UiDevice receiver,
long stableTimeoutMs,
long stableIntervalMs,
long stablePollIntervalMs,
boolean requireStableScreenshot
)
```
Waits for the root node of the active window to become stable.
A node is considered stable when it and its descendants have not changed over an interval of time. Optionally also the node image can be checked. Internally it works checking periodically that the internal properties of the node have not changed.
**Note** : Usage of this API in tests will result in non-deterministic tests. So, this API should only be used as a last resort and **only** when there are no other alternatives available.
| Parameters |
|---|---|
| `long stableTimeoutMs` | a timeout for the wait operation, to ensure not waiting forever for stability. |
| `long stableIntervalMs` | the interval during which the node should not be changing, in order to be considered stable. |
| `long stablePollIntervalMs` | specifies how often the ui should be checked for changes. |
| `boolean requireStableScreenshot` | specifies if also the bitmap of the node should not change over the specified `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)`. Note that this won't work with elements that change constantly, like a video player. |
| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/StableResult` | a `https://developer.android.com/reference/androidx/test/uiautomator/StableResult` containing the latest acquired element hierarchy and screenshot, and a flag indicating if the node was stable before timeout. The flag `https://developer.android.com/reference/androidx/test/uiautomator/StableResult#isTimeout()` is set to false if the node was stable before the timeout expired, true otherwise. |
### UiDeviceExt.windows
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiDeviceExt.kt+function:windows)
```
public final @NonNull List<@NonNull AccessibilityWindowInfo> UiDeviceExt.windows(@NonNull UiDevice receiver)
```
Returns all the windows on all the displays.