# UiAutomatorTestScope
Artifact: [androidx.test.uiautomator:uiautomator](https://developer.android.com/jetpack/androidx/releases/test-uiautomator) [View Source](https://cs.android.com/search?q=file:androidx/test/uiautomator/UiAutomatorTestScope.kt+class:androidx.test.uiautomator.UiAutomatorTestScope) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
*** ** * ** ***
```
open class UiAutomatorTestScope
```
Known direct subclasses [MacrobenchmarkScope](https://developer.android.com/reference/kotlin/androidx/benchmark/macro/MacrobenchmarkScope)
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/benchmark/macro/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
| ### Protected constructors |
|---|
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#UiAutomatorTestScope()()` |
| ### Public functions |
|---|---|
| `https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#activeWindowRoot()()` Returns the active window root node. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#clearAppData()()` Clears the instrumentation test target app data. |
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2?` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)(timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html)` Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressBack()()` Press the back key. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)(count: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html)` Similar to `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)` times. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressEnter()()` Press the enter key. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressHome()()` Press the home key. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(java.lang.Class,kotlin.collections.List)(clazz: https://developer.android.com/reference/java/lang/Class.html<*>, intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html)` Starts an activity with the given class. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)( packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, activityName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html )` Starts an activity with the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)` and `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)(intent: https://developer.android.com/reference/android/content/Intent.html)` Starts the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)` for an activity. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)(packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html)` Starts the app with the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)(text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html)` Types the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` string simulating key press through `https://developer.android.com/reference/android/app/Instrumentation.html#sendKeySync(android.view.KeyEvent)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#unregisterWatchers()()` Unregisters all the watchers previously registered with `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)`. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#waitForAppToBeVisible(kotlin.String,kotlin.Long)(appPackageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html, timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html)` Waits for an application to become visible. |
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/StableResult` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)( stableTimeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, stableIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, stablePollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html, requireStableScreenshot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html )` Waits for the root node of the active window to become stable. |
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/watcher/WatcherRegistration` | ` https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)(watcher: https://developer.android.com/reference/kotlin/androidx/test/uiautomator/watcher/ScopedUiWatcher, block: T.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html)` Registers a watcher for this `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope` to handle unexpected UI elements. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#windowRoots()()` Returns all the window roots on all the displays. |
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#windows()()` Returns all the windows on all the displays. |
| ### Protected functions |
|---|---|
| `open https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startIntentAndWait(android.content.Intent)(intent: https://developer.android.com/reference/android/content/Intent.html)` Default implementation of synchronous activity launch. |
| ### Public properties |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiDevice` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#device()` |
| `https://developer.android.com/reference/android/app/Instrumentation.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#instrumentation()` |
| `https://developer.android.com/reference/android/app/UiAutomation.html` | `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#uiAutomation()` |
## Protected constructors
### UiAutomatorTestScope
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
protected UiAutomatorTestScope()
```
## Public functions
### activeWindowRoot
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun activeWindowRoot(): AccessibilityNodeInfo
```
Returns the active window root node.
### clearAppData
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun clearAppData(): Unit
```
Clears the instrumentation test target app data.
### onElement
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
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 `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` that allows interacting with it. Internally it works searching periodically every `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`.
Example:
```kotlin
onElement { textAsString == "Search" }.click()
```
| Parameters |
|---|---|
| `timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 10000` | a timeout to find the element that satisfies the given condition. |
| `pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 100` | an interval to wait before rechecking the accessibility tree for updates. |
| `block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | a block that specifies a condition on the node to find. |
| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` | a `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` from a node that matches the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |
### onElementOrNull
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
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 `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` that allows interacting with it. Internally it works searching periodically every `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`.
Example:
```kotlin
onElement { textAsString == "Search" }.click()
```
| Parameters |
|---|---|
| `timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 10000` | a timeout to find the element that satisfies the given condition. |
| `pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 100` | an interval to wait before rechecking the accessibility tree for updates. |
| `block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | a block that specifies a condition on the node to find. |
| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2?` | a `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` from a node that matches the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)` condition or null. |
### onElements
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun onElements(
timeoutMs: Long = 10000,
pollIntervalMs: Long = 100,
block: AccessibilityNodeInfo.() -> Boolean
): List
```
Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` that allows interacting with it. Internally it works searching periodically every `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`.
Example:
```kotlin
node.onElements { isClass(Button::class.java) }
```
| Parameters |
|---|---|
| `timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 10000` | a timeout to find the element that satisfies the given condition. |
| `pollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 100` | an interval to wait before rechecking the accessibility tree for updates. |
| `block: https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | a block that specifies a condition on the node to find. |
| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html` | a list of `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiObject2` from nodes that matches the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |
### pressBack
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun pressBack(): Boolean
```
Press the back key.
### pressDelete
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun pressDelete(count: Int): Unit
```
Similar to `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)` times.
| Parameters |
|---|---|
| `count: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-int/index.html` | how many times the press delete key should be pressed. |
### pressEnter
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun pressEnter(): Boolean
```
Press the enter key.
### pressHome
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun pressHome(): Boolean
```
Press the home key.
### startActivity
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun startActivity(clazz: Class<*>, intentFlags: List = listOf()): Unit
```
Starts an activity with the given class. This method is blocking and awaits for a new window to be displayed.
| Parameters |
|---|---|
| `clazz: https://developer.android.com/reference/java/lang/Class.html<*>` | the class of the activity to start. |
| `intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html = listOf()` | a list of flags to add to the intent before launching it. |
| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | whether an accessibility a new window was detected before the given timeout. |
### startActivity
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun startActivity(
packageName: String,
activityName: String,
intentFlags: List = listOf()
): Unit
```
Starts an activity with the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)` and `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)`. This method is blocking and awaits for a new window to be displayed.
| Parameters |
|---|---|
| `packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the app package name of the activity to start. |
| `activityName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the name of the activity to start. |
| `intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html = listOf()` | a list of flags to add to the intent before launching it. |
| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | whether an accessibility a new window was detected before the given timeout. |
### startActivityIntent
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun startActivityIntent(intent: Intent): Unit
```
Starts the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)` for an activity. This method is blocking and awaits for a new window to be displayed.
| Parameters |
|---|---|
| `intent: https://developer.android.com/reference/android/content/Intent.html` | an intent to start |
| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | whether an accessibility a new window was detected before the given timeout. |
### startApp
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun startApp(packageName: String, intentFlags: List = listOf()): Unit
```
Starts the app with the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)`. This method is blocking and awaits for a view with the given package name to be visible.
| Parameters |
|---|---|
| `packageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the package name of the app to start |
| `intentFlags: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin.collections/-list/index.html = listOf()` | a list of flags to add to the intent before launching it, see `https://developer.android.com/reference/android/content/Intent.html#addFlags(int)`. |
| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | whether an accessibility node with the given package name was found before the given timeout. |
### type
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun type(text: String): Unit
```
Types the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` string simulating key press through `https://developer.android.com/reference/android/app/Instrumentation.html#sendKeySync(android.view.KeyEvent)`. This is similar to tapping the keys on a virtual keyboard and will trigger the same listeners in the target app, as opposed to `https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html#setText(java.lang.CharSequence)` that programmatically sets the given text in the target node.
| Parameters |
|---|---|
| `text: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the text to type. |
### unregisterWatchers
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun unregisterWatchers(): Unit
```
Unregisters all the watchers previously registered with `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)`.
### waitForAppToBeVisible
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
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 `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#waitForAppToBeVisible(kotlin.String,kotlin.Long)` exists in the accessibility tree.
| Parameters |
|---|---|
| `appPackageName: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-string/index.html` | the package name of the app to wait for. |
| `timeoutMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 10000` | a timeout for the app to become visible. |
| Returns |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html` | whether the app became visible in the given timeout. |
### waitForStableInActiveWindow
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
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: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 3000` | a timeout for the wait operation, to ensure not waiting forever for stability. |
| `stableIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 500` | the interval during which the node should not be changing, in order to be considered stable. |
| `stablePollIntervalMs: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-long/index.html = 50` | specifies how often the ui should be checked for changes. |
| `requireStableScreenshot: https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-boolean/index.html = true` | specifies if also the bitmap of the node should not change over the specified `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)`. Note that this won't work with elements that change constantly, like a video player. |
| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/StableResult` | a `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/StableResult` containing the latest acquired element hierarchy and screenshot, and a flag indicating if the node was stable before timeout. The flag `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/StableResult#isTimeout()` is set to false if the node was stable before the timeout expired, true otherwise. |
### watchFor
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun watchFor(watcher: ScopedUiWatcher, block: T.() -> Unit): WatcherRegistration
```
Registers a watcher for this `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope` to handle unexpected UI elements. Internally this method uses the existing `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)` api. When the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/watcher/ScopedUiWatcher#isVisible()` condition is satisfied, then the given `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)` is executed. scope. This method returns a handler with the `https://developer.android.com/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 `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)` api should be used.
Usage:
```kotlin
@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: https://developer.android.com/reference/kotlin/androidx/test/uiautomator/watcher/ScopedUiWatcher` | the dialog to watch for. |
| `block: T.() -> https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html` | a block to handle. |
| Returns |
|---|---|
| `https://developer.android.com/reference/kotlin/androidx/test/uiautomator/watcher/WatcherRegistration` | the dialog registration. |
### windowRoots
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun windowRoots(): List
```
Returns all the window roots on all the displays.
### windows
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
fun windows(): List
```
Returns all the windows on all the displays.
## Protected functions
### startIntentAndWait
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
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
### device
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
val device: UiDevice
```
### instrumentation
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
val instrumentation: Instrumentation
```
### uiAutomation
Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)
```
val uiAutomation: UiAutomation
```