UiDevice

fun clearLastTraversedText(): Unit

Clears the text from the last UI traversal event. See getLastTraversedText.

fun click(x: Int, y: Int): Boolean

Perform a click at arbitrary coordinates on the default display specified by the user.

fun drag(startX: Int, startY: Int, endX: Int, endY: Int, steps: Int): Boolean

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).

fun dumpWindowHierarchy(dest: File): Unit

Dumps every window's layout hierarchy to a java.io.File in XML format.

fun dumpWindowHierarchy(fileName: String): Unit

Dumps every window's layout hierarchy to a file in XML format.

fun dumpWindowHierarchy(out: OutputStream): Unit

Dumps every window's layout hierarchy to an java.io.OutputStream in XML format.

@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.")
fun executeShellCommand(cmd: String): String

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.

fun findObject(selector: BySelector): UiObject2!

Returns the first object to match the selector criteria, or null if no matching objects are found.

fun findObject(selector: UiSelector): UiObject

Returns a UiObject which represents a view that matches the specified selector criteria.

fun findObjects(selector: BySelector): (Mutable)List<UiObject2!>

Returns all objects that match the selector criteria.

fun findWindow(selector: ByWindowSelector): UiWindow?

Returns the first top-level window that matches the selector criteria, or null if no matching windows are found.

fun findWindows(selector: ByWindowSelector): (Mutable)List<UiWindow!>

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.

fun freezeRotation(): Unit

Freezes the default display rotation at its current state.

@RequiresApi(value = 30)
fun freezeRotation(displayId: Int): Unit

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.

fun getCurrentActivityName(): String!

Retrieves the last activity to report accessibility events.

fun getCurrentPackageName(): String!

Retrieves the name of the last package to report accessibility events.

fun getDisplayHeight(): @Px Int

Gets the height of the default display, in pixels. The size is adjusted based on the current orientation of the display.

fun getDisplayHeight(displayId: Int): @Px Int

Gets the height of the display with displayId, in pixels. The size is adjusted based on the current orientation of the display.

fun getDisplaySizeDp(): Point

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).

fun getDisplayWidth(): @Px Int

Gets the width of the default display, in pixels. The size is adjusted based on the current orientation of the display.

fun getDisplayWidth(displayId: Int): @Px Int

Gets the width of the display with displayId, in pixels. The size is adjusted based on the current orientation of the display.

java-static fun getInstance(): UiDevice

Retrieves a singleton instance of UiDevice

java-static fun getInstance(instrumentation: Instrumentation): UiDevice

Retrieves a singleton instance of UiDevice. A new instance will be created if instrumentation is also new.

fun getLastTraversedText(): String!

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.

fun getLauncherPackageName(): String!

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:

<queries>
  <intent>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.HOME"/>
  </intent>
</queries>

fun getProductName(): String

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.

fun getWindowRoots(): (Mutable)List<AccessibilityNodeInfo!>

Returns a list containing the root AccessibilityNodeInfos 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.

fun hasAnyWatcherTriggered(): Boolean

Checks if any registered UiWatcher have triggered. See registerWatcher See hasWatcherTriggered

fun hasObject(selector: BySelector): Boolean

Returns whether there is a match for the given selector criteria.

fun hasWatcherTriggered(watcherName: String?): Boolean

Checks if a specific registered UiWatcher has triggered. See registerWatcher. If a UiWatcher runs and its 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.

fun hasWindow(selector: ByWindowSelector): Boolean

Returns whether there is a window match for the given selector criteria.

fun isScreenOn(): Boolean

Checks the power manager if the default display is ON.

fun openNotification(): Boolean

Opens the notification shade.

fun openQuickSettings(): Boolean

Opens the Quick Settings shade.

fun <U> performActionAndWait(
    action: Runnable,
    condition: EventCondition<U!>,
    timeout: Long
): U!

Performs the provided action and waits for the condition to be met.

fun pressBack(): Boolean

Simulates a short press on the BACK button.

fun pressDPadCenter(): Boolean

Simulates a short press on the CENTER button.

fun pressDPadDown(): Boolean

Simulates a short press on the DOWN button.

fun pressDPadLeft(): Boolean

Simulates a short press on the LEFT button.

fun pressDPadRight(): Boolean

Simulates a short press on the RIGHT button.

fun pressDPadUp(): Boolean

Simulates a short press on the UP button.

fun pressDelete(): Boolean

Simulates a short press on the DELETE key.

fun pressEnter(): Boolean

Simulates a short press on the ENTER key.

fun pressHome(): Boolean

Simulates a short press on the HOME button.

fun pressKeyCode(keyCode: Int): Boolean

Simulates a short press using a key code. See KeyEvent

fun pressKeyCode(keyCode: Int, metaState: Int): Boolean

Simulates a short press using a key code. See KeyEvent.

fun pressKeyCodes(keyCodes: IntArray<Int>): Boolean

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})

fun pressKeyCodes(keyCodes: IntArray<Int>, metaState: Int): Boolean

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})

fun pressMenu(): Boolean

Simulates a short press on the MENU button.

fun pressRecentApps(): Boolean

Simulates a short press on the Recent Apps button.

fun pressSearch(): Boolean

Simulates a short press on the SEARCH button.

fun registerWatcher(name: String?, watcher: UiWatcher?): Unit

Registers a UiWatcher to run automatically when the testing framework is unable to find a match using a UiSelector. See runWatchers

fun removeWatcher(name: String?): Unit

Removes a previously registered UiWatcher. See registerWatcher

fun resetWatcherTriggers(): Unit

Resets a UiWatcher that has been triggered. If a UiWatcher runs and its checkForCondition call returned true, then the UiWatcher is considered triggered. See registerWatcher

fun runWatchers(): Unit

This method forces all registered watchers to run. See registerWatcher

fun setCompressedLayoutHeirarchy(compressed: Boolean): Unit

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.

fun setCompressedLayoutHierarchy(compressed: Boolean): Unit

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.

fun setOrientationLandscape(): Unit

Orients the default display to its landscape orientation (width >= height) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

@RequiresApi(value = 30)
fun setOrientationLandscape(displayId: Int): Unit

Orients the display with displayId to its landscape orientation (width >= height) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

fun setOrientationLeft(): Unit

Orients the default display to the left and freezes rotation. Use 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 setOrientationPortrait and setOrientationLandscape.

@RequiresApi(value = 30)
fun setOrientationLeft(displayId: Int): Unit

Orients the display with displayId to the left and freezes rotation. Use 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 setOrientationPortrait and setOrientationLandscape.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

fun setOrientationNatural(): Unit

Orients the default display to its natural orientation and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: The natural orientation depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

@RequiresApi(value = 30)
fun setOrientationNatural(displayId: Int): Unit

Orients the display with displayId to its natural orientation and freezes rotation . Use unfreezeRotation to un-freeze the rotation.

Note: The natural orientation depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

fun setOrientationPortrait(): Unit

Orients the default display to its portrait orientation (height >= width) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

@RequiresApi(value = 30)
fun setOrientationPortrait(displayId: Int): Unit

Orients the display with displayId to its portrait orientation (height >= width) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

fun setOrientationRight(): Unit

Orients the default display to the right and freezes rotation. Use 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 setOrientationPortrait and setOrientationLandscape.

@RequiresApi(value = 30)
fun setOrientationRight(displayId: Int): Unit

Orients the display with displayId to the right and freezes rotation. Use 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 setOrientationPortrait and setOrientationLandscape.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

fun sleep(): Unit

This method simply presses the power button if the default display is ON, else it does nothing if the default display is already OFF.

fun swipe(segments: Array<Point!>, segmentSteps: Int): Boolean

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).

fun swipe(startX: Int, startY: Int, endX: Int, endY: Int, steps: Int): Boolean

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).

fun takeScreenshot(): Bitmap?

Take a screenshot of the default display.

The screenshot is adjusted per screen rotation.

fun takeScreenshot(storePath: File): Boolean

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

fun takeScreenshot(storePath: File, scale: Float, quality: Int): Boolean

Take a screenshot of the default display and store it as PNG The screenshot is adjusted per screen rotation

fun unfreezeRotation(): Unit

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.

@RequiresApi(value = 30)
fun unfreezeRotation(displayId: Int): Unit

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.

fun <U> wait(condition: Condition<UiDevice!, U!>, timeout: Long): U!

Waits for given the condition to be met.

fun <U> wait(condition: SearchCondition<U!>, timeout: Long): U!

Waits for given the condition to be met.

fun waitForIdle(): Unit

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

fun waitForIdle(timeout: Long): Unit

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.

fun waitForWindowUpdate(packageName: String?, timeout: Long): Boolean

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.

fun wakeUp(): Unit

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.

fun UiDevice.activeWindow(): AccessibilityWindowInfo

Returns the active window.

fun UiDevice.onElement(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, a ElementNotFoundException is thrown. Internally it works searching periodically every pollIntervalMs.

Example:

uiDevice.onElement { textAsString == "Search" }.click()

fun UiDevice.onElementOrNull(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2?

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, null is returned. Internally it works searching periodically every pollIntervalMs.

Example:

uiDevice.onElement { textAsString == "Search" }.click()

fun UiDevice.onElements(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): List<UiObject2>

Performs a DFS on the accessibility tree starting from this node and returns all the nodes matching the given block. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are UiObject2 that allow interacting with them. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElements { className == Button::class.java.name }

If multiple nodes are expected but they appear at different times, it's recommended to call androidx.test.uiautomator.waitForStable before, to ensure any operation is complete.

fun UiDevice.pressDelete(count: Int): Unit

Similar to type but presses the delete key for the given count times.

fun UiDevice.type(text: String): Unit

Types the given text string simulating key press through Instrumentation.sendKeySync. This is similar to tapping the keys on a virtual keyboard and will trigger the same listeners in the target app, as opposed to AccessibilityNodeInfo.setText that programmatically sets the given text in the target node.

fun UiDevice.waitForAppToBeVisible(
    appPackageName: String,
    timeoutMs: Long = 10000
): Boolean

Waits for an application to become visible. Note that internally it checks if an accessibility node with the given appPackageName exists in the accessibility tree.

fun UiDevice.waitForRootInActiveWindow(
    timeoutMs: Long = 10000,
    sleepIntervalMs: Long = 100,
    clearCache: Boolean = true
): AccessibilityNodeInfo

Waits for the root node to become available in this window.

fun UiDevice.waitForStableInActiveWindow(
    stableTimeoutMs: Long = 3000,
    stableIntervalMs: Long = 500,
    stablePollIntervalMs: Long = 50,
    requireStableScreenshot: Boolean = true
): StableResult

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.

fun UiDevice.windows(): List<AccessibilityWindowInfo>

Returns all the windows on all the displays.