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 5 milliseconds per step, so for a 100 steps, the swipe will take around 0.5 seconds to complete.

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 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 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 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): Boolean

Presses one or more 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, metaState: Int): Boolean

Presses one or more 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 5ms per step. So for a 100 steps, the swipe will take about 1/2 second to complete.

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 5ms per step. So for a 100 steps, the swipe will take about 1/2 second to complete.

fun takeScreenshot(storePath: File): Boolean

Take a screenshot of current window 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 current window 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. Default wait timeout is 10 seconds

fun waitForIdle(timeout: Long): Unit

Waits for the current application to idle.

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.