UiAutomatorTestScope  |  API reference  |  Android Developers (original) (raw)

open class UiAutomatorTestScope

Known direct subclasses

MacrobenchmarkScope Provides access to common operations in app automation, such as killing the app, or navigating home.

A UiAutomator scope that allows to easily access UiAutomator api and utils class.

Summary

Public functions
AccessibilityNodeInfo activeWindowRoot() Returns the active window root node.
Unit clearAppData() Clears the instrumentation test target app data.
UiObject2 onElement(timeoutMs: Long, pollIntervalMs: Long, block: AccessibilityNodeInfo.() -> Boolean) 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.
UiObject2? onElementOrNull(timeoutMs: Long, pollIntervalMs: Long, block: AccessibilityNodeInfo.() -> Boolean) 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.
List<UiObject2> onElements(timeoutMs: Long, pollIntervalMs: Long, block: AccessibilityNodeInfo.() -> Boolean) 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.
Boolean pressBack() Press the back key.
Unit pressDelete(count: Int) Similar to type but presses the delete key for the given count times.
Boolean pressEnter() Press the enter key.
Boolean pressHome() Press the home key.
Unit startActivity(clazz: Class<*>, intentFlags: List<Int>) Starts an activity with the given class.
Unit startActivity( packageName: String, activityName: String, intentFlags: List<Int>) Starts an activity with the given packageName and activityName.
Unit startActivityIntent(intent: Intent) Starts the given intent for an activity.
Unit startApp(packageName: String, intentFlags: List<Int>) Starts the app with the given packageName.
Unit type(text: String) Types the given text string simulating key press through Instrumentation.sendKeySync.
Unit unregisterWatchers() Unregisters all the watchers previously registered with watchFor.
Boolean waitForAppToBeVisible(appPackageName: String, timeoutMs: Long) Waits for an application to become visible.
StableResult waitForStableInActiveWindow( stableTimeoutMs: Long, stableIntervalMs: Long, stablePollIntervalMs: Long, requireStableScreenshot: Boolean) Waits for the root node of the active window to become stable.
WatcherRegistration <T : Any?> watchFor(watcher: ScopedUiWatcher, block: T.() -> Unit) Registers a watcher for this androidx.test.uiautomator.UiAutomatorTestScope to handle unexpected UI elements.
List<AccessibilityNodeInfo> windowRoots() Returns all the window roots on all the displays.
List<AccessibilityWindowInfo> windows() Returns all the windows on all the displays.

Protected constructors

Public functions

clearAppData

fun clearAppData(): Unit

Clears the instrumentation test target app data.

onElement

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](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement%28kotlin.Long,kotlin.Long,kotlin.Function1%29). The node is returned as an [UiObject2](/reference/kotlin/androidx/test/uiautomator/UiObject2) that allows interacting with it. Internally it works searching periodically every [pollIntervalMs](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement%28kotlin.Long,kotlin.Long,kotlin.Function1%29).

Example:

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

Parameters
timeoutMs: Long = 10000 a timeout to find the element that satisfies the given condition.
pollIntervalMs: Long = 100 an interval to wait before rechecking the accessibility tree for updates.
block: AccessibilityNodeInfo.() -> Boolean a block that specifies a condition on the node to find.

onElementOrNull

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](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull%28kotlin.Long,kotlin.Long,kotlin.Function1%29). The node is returned as an [UiObject2](/reference/kotlin/androidx/test/uiautomator/UiObject2) that allows interacting with it. Internally it works searching periodically every [pollIntervalMs](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull%28kotlin.Long,kotlin.Long,kotlin.Function1%29).

Example:

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

Parameters
timeoutMs: Long = 10000 a timeout to find the element that satisfies the given condition.
pollIntervalMs: Long = 100 an interval to wait before rechecking the accessibility tree for updates.
block: AccessibilityNodeInfo.() -> Boolean a block that specifies a condition on the node to find.

onElements

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](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements%28kotlin.Long,kotlin.Long,kotlin.Function1%29). The node is returned as an [UiObject2](/reference/kotlin/androidx/test/uiautomator/UiObject2) that allows interacting with it. Internally it works searching periodically every [pollIntervalMs](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements%28kotlin.Long,kotlin.Long,kotlin.Function1%29).

Example:

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

Parameters
timeoutMs: Long = 10000 a timeout to find the element that satisfies the given condition.
pollIntervalMs: Long = 100 an interval to wait before rechecking the accessibility tree for updates.
block: AccessibilityNodeInfo.() -> Boolean a block that specifies a condition on the node to find.

pressDelete

fun pressDelete(count: Int): Unit

Similar to [type](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type%28kotlin.String%29) but presses the delete key for the given [count](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete%28kotlin.Int%29) times.

Parameters
count: Int how many times the press delete key should be pressed.

startActivity

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.

Parameters
clazz: Class<*> the class of the activity to start.
intentFlags: List<Int> = listOf() a list of flags to add to the intent before launching it.
Returns
Unit whether an accessibility a new window was detected before the given timeout.

startActivity

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

Starts an activity with the given [packageName](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity%28kotlin.String,kotlin.String,kotlin.collections.List%29) and [activityName](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity%28kotlin.String,kotlin.String,kotlin.collections.List%29). This method is blocking and awaits for a new window to be displayed.

Parameters
packageName: String the app package name of the activity to start.
activityName: String the name of the activity to start.
intentFlags: List<Int> = listOf() a list of flags to add to the intent before launching it.
Returns
Unit whether an accessibility a new window was detected before the given timeout.

startActivityIntent

fun startActivityIntent(intent: Intent): Unit

Starts the given [intent](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent%28android.content.Intent%29) for an activity. This method is blocking and awaits for a new window to be displayed.

Parameters
intent: Intent an intent to start
Returns
Unit whether an accessibility a new window was detected before the given timeout.

startApp

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

Starts the app with the given [packageName](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startApp%28kotlin.String,kotlin.collections.List%29). This method is blocking and awaits for a view with the given package name to be visible.

Parameters
packageName: String the package name of the app to start
intentFlags: List<Int> = listOf() a list of flags to add to the intent before launching it, see Intent.addFlags.
Returns
Unit whether an accessibility node with the given package name was found before the given timeout.

waitForAppToBeVisible

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](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#waitForAppToBeVisible%28kotlin.String,kotlin.Long%29) exists in the accessibility tree.

Parameters
appPackageName: String the package name of the app to wait for.
timeoutMs: Long = 10000 a timeout for the app to become visible.
Returns
Boolean whether the app became visible in the given timeout.

waitForStableInActiveWindow

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.

Parameters
stableTimeoutMs: Long = 3000 a timeout for the wait operation, to ensure not waiting forever for stability.
stableIntervalMs: Long = 500 the interval during which the node should not be changing, in order to be considered stable.
stablePollIntervalMs: Long = 50 specifies how often the ui should be checked for changes.
requireStableScreenshot: Boolean = true specifies if also the bitmap of the node should not change over the specified stableIntervalMs. Note that this won't work with elements that change constantly, like a video player.
Returns
StableResult a StableResult containing the latest acquired element hierarchy and screenshot, and a flag indicating if the node was stable before timeout. The flag StableResult.isTimeout is set to false if the node was stable before the timeout expired, true otherwise.

watchFor

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

Registers a watcher for this [androidx.test.uiautomator.UiAutomatorTestScope](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope) to handle unexpected UI elements. Internally this method uses the existing [UiDevice.registerWatcher](/reference/kotlin/androidx/test/uiautomator/UiDevice#registerWatcher%28kotlin.String,androidx.test.uiautomator.UiWatcher%29) api. When the given [ScopedUiWatcher.isVisible](/reference/kotlin/androidx/test/uiautomator/watcher/ScopedUiWatcher#isVisible%28%29) condition is satisfied, then the given [block](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#watchFor%28androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1%29) is executed. scope. This method returns a handler with the [WatcherRegistration](/reference/kotlin/androidx/test/uiautomator/watcher/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](/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement%28kotlin.Long,kotlin.Long,kotlin.Function1%29) 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()

}

Parameters
watcher: ScopedUiWatcher the dialog to watch for.
block: T.() -> Unit a block to handle.

Protected functions

startIntentAndWait

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.

Public properties