UiAutomatorTestScope

public final @NonNull AccessibilityNodeInfo activeWindowRoot()

Returns the active window root node. Note that calling this method after startApp, startActivity or startIntent without waiting for the app to be visible, will return the active window root at the time of starting the app, i.e. the root of the launcher if starting from there.

public final void clearAppData()

Clears the instrumentation test target app data.

public final @NonNull UiObject2 onElement(
    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. Internally it works searching periodically every pollIntervalMs.

Example:

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

public final UiObject2 onElementOrNull(
    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. Internally it works searching periodically every pollIntervalMs.

Example:

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

public final @NonNull List<@NonNull UiObject2> onElements(
    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. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElements { isClass(Button::class.java) }

public final boolean pressBack()

Press the back key.

public final void pressDelete(int count)

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

public final boolean pressEnter()

Press the enter key.

public final boolean pressHome()

Press the home key.

public final void startActivity(@NonNull Class<@NonNull ?> clazz)

Starts an activity with the given class.

public final void startActivity(@NonNull String packageName, @NonNull String activityName)

Starts an activity with the given packageName and activityName.

public final void startApp()

Starts the instrumentation test target app using the target app package name.

public final void startApp(@NonNull String packageName)

Starts the app with the given packageName.

public final void startIntent(@NonNull Intent intent)

Starts the given intent.

public final void type(@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 void unregisterWatchers()

Unregisters all the watchers previously registered with watchFor.

public final boolean waitForAppToBeVisible(@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 StableResult waitForStableInActiveWindow(
    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 WatcherRegistration <T extends Object> watchFor(
    @NonNull ScopedUiWatcher<@NonNull T> watcher,
    @NonNull Function1<@NonNull T, Unit> block
)

Registers a watcher for this androidx.test.uiautomator.UiAutomatorTestScope to handle unexpected UI elements. Internally this method uses the existing UiDevice.registerWatcher api. When the given ScopedUiWatcher.isVisible condition is satisfied, then the given block is executed. scope. This method returns a handler with the WatcherRegistration to unregister it before the block is complete. Note that this api helps with unexpected ui elements, such as system dialogs, and that for expected dialogs the onElement api should be used.

Usage:

@Test fun myTest() = uiAutomator {

    // Registers a watcher for a permission dialog.
    watchFor(PermissionDialog) { clickAllow() }

    // Registers a watcher for a custom dialog and unregisters it.
    val registration = watchFor(MyDialog) { clickSomething() }
    // Do something...
    registration.unregister()
}

public final @NonNull List<@NonNull AccessibilityNodeInfo> windowRoots()

Returns all the window roots on all the displays.

public final @NonNull List<@NonNull AccessibilityWindowInfo> windows()

Returns all the windows on all the displays.