# UiDeviceExt

Added in 2.4.1

*** ** * ** ***


```
public final class UiDeviceExt
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `static final @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/UiDeviceExt#(androidx.test.uiautomator.UiDevice).activeWindow()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver)` Returns the active window. |
| `static 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/UiDeviceExt#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, 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/package-summary#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `static final https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, 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/package-summary#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `static 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/UiDeviceExt#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, 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 this node and returns all the nodes matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `static final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt#(androidx.test.uiautomator.UiDevice).pressDelete(kotlin.Int)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, int count)` Similar to `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).type(kotlin.String)` but presses the delete key for the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).pressDelete(kotlin.Int)` times. |
| `static final void` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt#(androidx.test.uiautomator.UiDevice).type(kotlin.String)(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, @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/package-summary#(androidx.test.uiautomator.UiDevice).type(kotlin.String)` string simulating key press through `https://developer.android.com/reference/android/app/Instrumentation.html#sendKeySync(android.view.KeyEvent)`. |
| `static final boolean` | `https://developer.android.com/reference/androidx/test/uiautomator/UiDeviceExt#(androidx.test.uiautomator.UiDevice).waitForAppToBeVisible(kotlin.String,kotlin.Long)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, @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. |
| `static 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/UiDeviceExt#(androidx.test.uiautomator.UiDevice).waitForRootInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, long timeoutMs, long sleepIntervalMs, boolean clearCache )` Waits for the root node to become available in this window. |
| `static 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/UiDeviceExt#(androidx.test.uiautomator.UiDevice).waitForStableInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver, long stableTimeoutMs, long stableIntervalMs, long stablePollIntervalMs, boolean requireStableScreenshot )` Waits for the root node of the active window to become stable. |
| `static 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/UiDeviceExt#(androidx.test.uiautomator.UiDevice).windows()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiDevice receiver)` Returns all the windows on all the displays. |

## Public methods

### activeWindow

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/UiDeviceExt.kt+function:activeWindow) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final @NonNull AccessibilityWindowInfo activeWindow(@NonNull UiDevice receiver)
```

Returns the active window.

### onElement

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/UiDeviceExt.kt+function:onElement) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final @NonNull UiObject2 onElement(
    @NonNull UiDevice receiver,
    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/package-summary#(androidx.test.uiautomator.UiDevice).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. If the requested node doesn't exist, a `https://developer.android.com/reference/androidx/test/uiautomator/ElementNotFoundException` is thrown. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)`.

Example:

```
uiDevice.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/package-summary#(androidx.test.uiautomator.UiDevice).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |

### onElementOrNull

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/UiDeviceExt.kt+function:onElementOrNull) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final UiObject2 onElementOrNull(
    @NonNull UiDevice receiver,
    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/package-summary#(androidx.test.uiautomator.UiDevice).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. If the requested node doesn't exist, null is returned. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)`.

Example:

```
uiDevice.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/package-summary#(androidx.test.uiautomator.UiDevice).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)` condition or null. |

### onElements

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/UiDeviceExt.kt+function:onElements) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final @NonNull List<@NonNull UiObject2> onElements(
    @NonNull UiDevice receiver,
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```

Performs a DFS on the accessibility tree starting from this node and returns all the nodes matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` that allow interacting with them. Internally it works searching periodically every `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`.

Example:

```
node.onElements { className == Button::class.java.name }
```

If multiple nodes are expected but they appear at different times, it's recommended to call `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(android.view.accessibility.AccessibilityNodeInfo).waitForStable(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)` before, to ensure any operation is complete.

| 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/package-summary#(androidx.test.uiautomator.UiDevice).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |

### pressDelete

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/UiDeviceExt.kt+function:pressDelete) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final void pressDelete(@NonNull UiDevice receiver, int count)
```

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

| Parameters |
|---|---|
| `int count` | how many times the press delete key should be pressed. |

### type

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/UiDeviceExt.kt+function:type) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final void type(@NonNull UiDevice receiver, @NonNull String text)
```

Types the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).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. |

### waitForAppToBeVisible

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/UiDeviceExt.kt+function:waitForAppToBeVisible) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final boolean waitForAppToBeVisible(
    @NonNull UiDevice receiver,
    @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/package-summary#(androidx.test.uiautomator.UiDevice).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. By default is the target app package name. |
| `long timeoutMs` | a timeout for the app to become visible. |

| Returns |
|---|---|
| `boolean` | whether the app became visible in the given timeout. |

### waitForRootInActiveWindow

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/UiDeviceExt.kt+function:waitForRootInActiveWindow) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final @NonNull AccessibilityNodeInfo waitForRootInActiveWindow(
    @NonNull UiDevice receiver,
    long timeoutMs,
    long sleepIntervalMs,
    boolean clearCache
)
```

Waits for the root node to become available in this window.

| Parameters |
|---|---|
| `long timeoutMs` | a timeout for the root node to become available. |
| `long sleepIntervalMs` | a interval to wait before retrying checking if the node is available. |
| `boolean clearCache` | whether the accessibility nodes cache should be cleared when checking. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/view/accessibility/AccessibilityNodeInfo.html` | the root node for this window. |

| Throws |
|---|---|
| `https://kotlinlang.org/api/core/kotlin-stdlib/kotlin/-illegal-state-exception/index.html` | if the root node in the active window cannot be acquired before the give timeout `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiDevice).waitForRootInActiveWindow(kotlin.Long,kotlin.Long,kotlin.Boolean)`. |

### waitForStableInActiveWindow

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/UiDeviceExt.kt+function:waitForStableInActiveWindow) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

```
public static final @NonNull StableResult waitForStableInActiveWindow(
    @NonNull UiDevice receiver,
    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.

**Note** : Usage of this API in tests will result in non-deterministic tests. So, this API should only be used as a last resort and **only** when there are no other alternatives available.

| 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/package-summary#(androidx.test.uiautomator.UiDevice).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. |

### windows

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/UiDeviceExt.kt+function:windows) Added in [2.4.1](https://developer.android.com/jetpack/androidx/releases/test-uiautomator#2.4.1)

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

Returns all the windows on all the displays.