UiDevice

public void clearLastTraversedText()

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

public boolean click(int x, int y)

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

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

public void dumpWindowHierarchy(@NonNull File dest)

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

public void dumpWindowHierarchy(@NonNull String fileName)

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

public void dumpWindowHierarchy(@NonNull OutputStream out)

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

public UiObject2 findObject(@NonNull BySelector selector)

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

public @NonNull UiObject findObject(@NonNull UiSelector selector)

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

public @NonNull List<UiObject2> findObjects(@NonNull BySelector selector)

Returns all objects that match the selector criteria.

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.

public @NonNull List<UiWindow> 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.

public void freezeRotation()

Freezes the default display rotation at its current state.

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

public String getCurrentActivityName()

Retrieves the last activity to report accessibility events.

public String getCurrentPackageName()

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

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.

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.

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

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.

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.

public static @NonNull UiDevice getInstance()

Retrieves a singleton instance of UiDevice

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.

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.

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:

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

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.

public @NonNull List<AccessibilityNodeInfo> getWindowRoots()

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.

public boolean hasAnyWatcherTriggered()

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

public boolean hasObject(@NonNull BySelector selector)

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

public boolean hasWatcherTriggered(@Nullable String watcherName)

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.

public boolean hasWindow(@NonNull ByWindowSelector selector)

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

public boolean isScreenOn()

Checks the power manager if the default display is ON.

public boolean openNotification()

Opens the notification shade.

public boolean openQuickSettings()

Opens the Quick Settings shade.

public U <U> performActionAndWait(
    @NonNull Runnable action,
    @NonNull EventCondition<U> condition,
    long timeout
)

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

public boolean pressBack()

Simulates a short press on the BACK button.

public boolean pressDPadCenter()

Simulates a short press on the CENTER button.

public boolean pressDPadDown()

Simulates a short press on the DOWN button.

public boolean pressDPadLeft()

Simulates a short press on the LEFT button.

public boolean pressDPadRight()

Simulates a short press on the RIGHT button.

public boolean pressDPadUp()

Simulates a short press on the UP button.

public boolean pressDelete()

Simulates a short press on the DELETE key.

public boolean pressEnter()

Simulates a short press on the ENTER key.

public boolean pressHome()

Simulates a short press on the HOME button.

public boolean pressKeyCode(int keyCode)

Simulates a short press using a key code. See KeyEvent

public boolean pressKeyCode(int keyCode, int metaState)

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

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

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

public boolean pressMenu()

Simulates a short press on the MENU button.

public boolean pressRecentApps()

Simulates a short press on the Recent Apps button.

public boolean pressSearch()

Simulates a short press on the SEARCH button.

public void registerWatcher(@Nullable String name, @Nullable UiWatcher watcher)

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

public void removeWatcher(@Nullable String name)

Removes a previously registered UiWatcher. See registerWatcher

public void resetWatcherTriggers()

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

public void runWatchers()

This method forces all registered watchers to run. See registerWatcher

public void setCompressedLayoutHeirarchy(boolean compressed)

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.

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.

public void setOrientationLandscape()

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

@RequiresApi(value = 30)
public void setOrientationLandscape(int displayId)

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.

public void setOrientationLeft()

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)
public void setOrientationLeft(int displayId)

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.

public void setOrientationNatural()

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)
public void setOrientationNatural(int displayId)

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.

public void setOrientationPortrait()

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

@RequiresApi(value = 30)
public void setOrientationPortrait(int displayId)

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.

public void setOrientationRight()

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)
public void setOrientationRight(int displayId)

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.

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.

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

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

public @Nullable Bitmap takeScreenshot()

Take a screenshot of the default display.

The screenshot is adjusted per screen rotation.

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

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

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.

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

public U <U> wait(@NonNull Condition<UiDevice, U> condition, long timeout)

Waits for given the condition to be met.

public U <U> wait(@NonNull SearchCondition<U> condition, long timeout)

Waits for given the condition to be met.

public void waitForIdle()

Waits for the current application to idle. Default wait timeout is 10 seconds

public void waitForIdle(long timeout)

Waits for the current application to idle.

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.

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.

public final @NonNull AccessibilityWindowInfo UiDeviceExt.activeWindow(@NonNull UiDevice receiver)

Returns the active window.

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

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

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

public final void UiDeviceExt.pressDelete(@NonNull UiDevice receiver, int count)

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

public final void UiDeviceExt.type(@NonNull UiDevice receiver, @NonNull String text)

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 programmaticaly sets the given text in the target node.

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 appPackageName exists in the accessibility tree.

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.

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.

public final @NonNull List<@NonNull AccessibilityWindowInfo> UiDeviceExt.windows(@NonNull UiDevice receiver)

Returns all the windows on all the displays.