UiAutomatorTestScope

fun activeWindowRoot(): AccessibilityNodeInfo

Returns the active window root node.

fun clearAppData(): Unit

Clears the instrumentation test target app data.

fun 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. Internally it works searching periodically every pollIntervalMs.

Example:

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

fun 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. Internally it works searching periodically every pollIntervalMs.

Example:

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

fun onElements(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): List<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. Internally it works searching periodically every pollIntervalMs.

Example:

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

fun pressBack(): Boolean

Press the back key.

fun pressDelete(count: Int): Unit

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

fun pressEnter(): Boolean

Press the enter key.

fun pressHome(): Boolean

Press the home key.

fun startActivity(clazz: Class<*>, intentFlags: List<Int> = listOf()): Unit

Starts an activity with the given class. This method is blocking and awaits for a new window to be displayed.

fun startActivity(
    packageName: String,
    activityName: String,
    intentFlags: List<Int> = listOf()
): Unit

Starts an activity with the given packageName and activityName. This method is blocking and awaits for a new window to be displayed.

fun startActivityIntent(intent: Intent): Unit

Starts the given intent for an activity. This method is blocking and awaits for a new window to be displayed.

fun startApp(packageName: String, intentFlags: List<Int> = listOf()): Unit

Starts the app with the given packageName. This method is blocking and awaits for a view with the given package name to be visible.

fun 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 unregisterWatchers(): Unit

Unregisters all the watchers previously registered with watchFor.

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

fun <T : Any?> watchFor(watcher: ScopedUiWatcher<T>, block: T.() -> Unit): WatcherRegistration

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

fun windowRoots(): List<AccessibilityNodeInfo>

Returns all the window roots on all the displays.

fun windows(): List<AccessibilityWindowInfo>

Returns all the windows on all the displays.

protected open fun startIntentAndWait(intent: Intent): Unit

Default implementation of synchronous activity launch.

This isn't exposed to callers, just to subclasses for overriding to enable e.g. Macrobenchmark to verify synchronous launches more aggressively.