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

*** ** * ** ***


```
public class UiAutomatorTestScope
```

<br />

Known direct subclasses [MacrobenchmarkScope](https://developer.android.com/reference/androidx/benchmark/macro/MacrobenchmarkScope)

|---|---|
| `https://developer.android.com/reference/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/androidx/test/uiautomator/UiAutomatorTestScope#UiAutomatorTestScope()()` |

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#activeWindowRoot()()` Returns the active window root node. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#clearAppData()()` Clears the instrumentation test target app data. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#getDevice()()` |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/app/Instrumentation.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#getInstrumentation()()` |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/app/UiAutomation.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#getUiAutomation()()` |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)( long timeoutMs, long pollIntervalMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> 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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `final https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)( long timeoutMs, long pollIntervalMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> 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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2>` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)( long timeoutMs, long pollIntervalMs, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> 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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `final boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressBack()()` Press the back key. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)(int count)` Similar to `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)` times. |
| `final boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressEnter()()` Press the enter key. |
| `final boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressHome()()` Press the home key. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(java.lang.Class,kotlin.collections.List)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Class.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?> clazz, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags )` Starts an activity with the given class. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html activityName, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags )` Starts an activity with the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)` and `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)`. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html intent)` Starts the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivityIntent(android.content.Intent)` for an activity. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags )` Starts the app with the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startApp(kotlin.String,kotlin.collections.List)`. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html text)` Types the given `https://developer.android.com/reference/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)`. |
| `final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#unregisterWatchers()()` Unregisters all the watchers previously registered with `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)`. |
| `final boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#waitForAppToBeVisible(kotlin.String,kotlin.Long)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html appPackageName, long timeoutMs)` Waits for an application to become visible. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/StableResult` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)( long stableTimeoutMs, long stableIntervalMs, long stablePollIntervalMs, boolean requireStableScreenshot )` Waits for the root node of the active window to become stable. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/watcher/WatcherRegistration` | `<T extends https://developer.android.com/reference/java/lang/Object.html> https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#watchFor(androidx.test.uiautomator.watcher.ScopedUiWatcher,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/watcher/ScopedUiWatcher<@https://developer.android.com/reference/androidx/annotation/NonNull T> watcher, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull T, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block )` Registers a watcher for this `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope` to handle unexpected UI elements. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html>` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#windowRoots()()` Returns all the window roots on all the displays. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityWindowInfo.html>` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#windows()()` Returns all the windows on all the displays. |

| ### Protected methods |
|---|---|
| `void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startIntentAndWait(android.content.Intent)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html intent)` Default implementation of synchronous activity launch. |

## Protected constructors

### UiAutomatorTestScope

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
protected UiAutomatorTestScope()
```

## Public methods

### activeWindowRoot

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final @NonNull AccessibilityNodeInfo activeWindowRoot()
```

Returns the active window root node.

### clearAppData

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final void clearAppData()
```

Clears the instrumentation test target app data.

### getDevice

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final @NonNull UiDevice getDevice()
```

### getInstrumentation

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final @NonNull Instrumentation getInstrumentation()
```

### getUiAutomation

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final @NonNull UiAutomation getUiAutomation()
```

### onElement

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` that allows interacting with it. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`.

Example:

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

| Parameters |
|---|---|
| `long timeoutMs` | a timeout to find the element that satisfies the given condition. |
| `long pollIntervalMs` | an interval to wait before rechecking the accessibility tree for updates. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block` | a block that specifies a condition on the node to find. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | a `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` from a node that matches the given `https://developer.android.com/reference/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)

```
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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` that allows interacting with it. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`.

Example:

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

| Parameters |
|---|---|
| `long timeoutMs` | a timeout to find the element that satisfies the given condition. |
| `long pollIntervalMs` | an interval to wait before rechecking the accessibility tree for updates. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block` | a block that specifies a condition on the node to find. |

| Returns |
|---|---|
| `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | a `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` from a node that matches the given `https://developer.android.com/reference/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)

```
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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. The node is returned as an `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` that allows interacting with it. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`.

Example:

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

| Parameters |
|---|---|
| `long timeoutMs` | a timeout to find the element that satisfies the given condition. |
| `long pollIntervalMs` | an interval to wait before rechecking the accessibility tree for updates. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Boolean.html> block` | a block that specifies a condition on the node to find. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2>` | a list of `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` from nodes that matches the given `https://developer.android.com/reference/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)

```
public final boolean pressBack()
```

Press the back key.

### pressDelete

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final void pressDelete(int count)
```

Similar to `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#pressDelete(kotlin.Int)` times.

| Parameters |
|---|---|
| `int count` | 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)

```
public final boolean pressEnter()
```

Press the enter key.

### pressHome

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final boolean pressHome()
```

Press the home key.

### startActivity

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final void startActivity(
    @NonNull Class<@NonNull ?> clazz,
    @NonNull List<@NonNull Integer> intentFlags
)
```

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

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Class.html<@https://developer.android.com/reference/androidx/annotation/NonNull ?> clazz` | the class of the activity to start. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags` | a list of flags to add to the intent before launching it. |

| Returns |
|---|---|
| `void` | 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)

```
public final void startActivity(
    @NonNull String packageName,
    @NonNull String activityName,
    @NonNull List<@NonNull Integer> intentFlags
)
```

Starts an activity with the given `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#startActivity(kotlin.String,kotlin.String,kotlin.collections.List)` and `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName` | the app package name of the activity to start. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html activityName` | the name of the activity to start. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags` | a list of flags to add to the intent before launching it. |

| Returns |
|---|---|
| `void` | 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)

```
public final void startActivityIntent(@NonNull Intent intent)
```

Starts the given `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/content/Intent.html intent` | an intent to start |

| Returns |
|---|---|
| `void` | 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)

```
public final void startApp(
    @NonNull String packageName,
    @NonNull List<@NonNull Integer> intentFlags
)
```

Starts the app with the given `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html packageName` | the package name of the app to start |
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/Integer.html> intentFlags` | 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 |
|---|---|
| `void` | 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)

```
public final void type(@NonNull String text)
```

Types the given `https://developer.android.com/reference/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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html text` | the text to type. |

### unregisterWatchers

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public final void unregisterWatchers()
```

Unregisters all the watchers previously registered with `https://developer.android.com/reference/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)

```
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 `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope#waitForAppToBeVisible(kotlin.String,kotlin.Long)` exists in the accessibility tree.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html appPackageName` | the package name of the app to wait for. |
| `long timeoutMs` | a timeout for the app to become visible. |

| Returns |
|---|---|
| `boolean` | 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)

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

| Parameters |
|---|---|
| `long stableTimeoutMs` | a timeout for the wait operation, to ensure not waiting forever for stability. |
| `long stableIntervalMs` | the interval during which the node should not be changing, in order to be considered stable. |
| `long stablePollIntervalMs` | specifies how often the ui should be checked for changes. |
| `boolean requireStableScreenshot` | specifies if also the bitmap of the node should not change over the specified `https://developer.android.com/reference/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/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/StableResult` | a `https://developer.android.com/reference/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/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)

```
public final @NonNull WatcherRegistration <T extends Object> watchFor(
    @NonNull ScopedUiWatcher<@NonNull T> watcher,
    @NonNull Function1<@NonNull T, Unit> block
)
```

Registers a watcher for this `https://developer.android.com/reference/androidx/test/uiautomator/UiAutomatorTestScope` to handle unexpected UI elements. Internally this method uses the existing `https://developer.android.com/reference/androidx/test/uiautomator/UiDevice#registerWatcher(java.lang.String,androidx.test.uiautomator.UiWatcher)` api. When the given `https://developer.android.com/reference/androidx/test/uiautomator/watcher/ScopedUiWatcher#isVisible()` condition is satisfied, then the given `https://developer.android.com/reference/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/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/androidx/test/uiautomator/UiAutomatorTestScope#onElement(kotlin.Long,kotlin.Long,kotlin.Function1)` 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 |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/watcher/ScopedUiWatcher<@https://developer.android.com/reference/androidx/annotation/NonNull T> watcher` | the dialog to watch for. |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull T, https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-unit/index.html> block` | a block to handle. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/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)

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

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)

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

Returns all the windows on all the displays.

## Protected methods

### startIntentAndWait

Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
protected void startIntentAndWait(@NonNull Intent intent)
```

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.