# UiObject2Ext

Added in 2.4.1

*** ** * ** ***


```
public final class UiObject2Ext
```

<br />

*** ** * ** ***

## Summary

| ### Public methods |
|---|---|
| `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/UiObject2Ext#(androidx.test.uiautomator.UiObject2).onElement(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2 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 node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).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/UiObject2Ext#(androidx.test.uiautomator.UiObject2).onElementOrNull(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2 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 node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).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/UiObject2Ext#(androidx.test.uiautomator.UiObject2).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2 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 node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and returns all the nodes matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `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/UiObject2Ext#(androidx.test.uiautomator.UiObject2).scrollToElement(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2 receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/Direction direction, 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 )` Keeps scrolling until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElement(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)` condition is satisfied or until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElement(androidx.test.uiautomator.Direction,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/UiObject2Ext#(androidx.test.uiautomator.UiObject2).scrollToElementOrNull(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2 receiver, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/Direction direction, 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 )` Keeps scrolling until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElementOrNull(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)` condition is satisfied or until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElementOrNull(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)`. |
| `static final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/graphics/Bitmap.html` | `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2Ext#(androidx.test.uiautomator.UiObject2).takeScreenshot()(@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2 receiver)` Takes a screenshot of the screen that contains the accessibility node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and cuts only the area covered by it. |
| `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/UiObject2Ext#(androidx.test.uiautomator.UiObject2).waitForStable(kotlin.Long,kotlin.Long,kotlin.Long,kotlin.Boolean)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/UiObject2 receiver, long stableTimeoutMs, long stableIntervalMs, long stablePollIntervalMs, boolean requireStableScreenshot )` Waits for the node to become stable. |

## Public methods

### 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/UiObject2Ext.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 UiObject2 receiver,
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```

Performs a DFS on the accessibility tree starting from the node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).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.UiObject2).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/package-summary#(androidx.test.uiautomator.UiObject2).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/UiObject2Ext.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 UiObject2 receiver,
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```

Performs a DFS on the accessibility tree starting from the node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and returns the first node matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).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.UiObject2).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/package-summary#(androidx.test.uiautomator.UiObject2).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/UiObject2Ext.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 UiObject2 receiver,
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```

Performs a DFS on the accessibility tree starting from the node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and returns all the nodes matching the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).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.UiObject2).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)`.

Example:

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

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.UiObject2).onElements(kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |

### scrollToElement

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

```
public static final @NonNull UiObject2 scrollToElement(
    @NonNull UiObject2 receiver,
    @NonNull Direction direction,
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```

Keeps scrolling until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElement(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)` condition is satisfied or until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElement(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)`. Throws a `https://developer.android.com/reference/androidx/test/uiautomator/ElementNotFoundException` if the condition is not satisfied at the end of the timeout.

Example:

```
onElement { isScrollable }.scrollToElement(Direction.DOWN) { id == "button" }.click()
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/Direction direction` | the scroll `https://developer.android.com/reference/androidx/test/uiautomator/Direction`. |
| `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` that matches the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElement(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |

### scrollToElementOrNull

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

```
public static final UiObject2 scrollToElementOrNull(
    @NonNull UiObject2 receiver,
    @NonNull Direction direction,
    long timeoutMs,
    long pollIntervalMs,
    @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)
```

Keeps scrolling until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElementOrNull(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)` condition is satisfied or until the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElementOrNull(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)`. Returns null if the condition is not satisfied at the end of the timeout.

Example:

```
onElement { isScrollable }.scrollToElement(Direction.DOWN) { id == "button" }.click()
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/test/uiautomator/Direction direction` | the scroll `https://developer.android.com/reference/androidx/test/uiautomator/Direction`. |
| `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` that matches the given `https://developer.android.com/reference/androidx/test/uiautomator/package-summary#(androidx.test.uiautomator.UiObject2).scrollToElementOrNull(androidx.test.uiautomator.Direction,kotlin.Long,kotlin.Long,kotlin.Function1)` condition. |

### takeScreenshot

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

```
public static final @NonNull Bitmap takeScreenshot(@NonNull UiObject2 receiver)
```

Takes a screenshot of the screen that contains the accessibility node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2` and cuts only the area covered by it.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/android/graphics/Bitmap.html` | a bitmap containing the image of the node associated to this `https://developer.android.com/reference/androidx/test/uiautomator/UiObject2`. |

### waitForStable

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

```
public static final @NonNull StableResult waitForStable(
    @NonNull UiObject2 receiver,
    long stableTimeoutMs,
    long stableIntervalMs,
    long stablePollIntervalMs,
    boolean requireStableScreenshot
)
```

Waits for the node 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/package-summary#(androidx.test.uiautomator.UiObject2).waitForStable(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. |