UiObject2

fun clear(): Unit

Clears this object's text content if it is an editable field.

fun click(): Unit

Clicks on this object's center.

fun click(duration: Long): Unit

Clicks on this object's center for duration milliseconds.

fun click(point: Point): Unit

Clicks on a point within this object's visible bounds.

fun click(point: Point, duration: Long): Unit

Clicks on a point within this object's visible bounds.

fun <U> clickAndWait(condition: EventCondition<U!>, timeout: Long): U!

Clicks on this object's center, and waits for a condition to be met.

fun <U> clickAndWait(point: Point, condition: EventCondition<U!>, timeout: Long): U!

Clicks on a point within this object's visible bounds, and waits for a condition to be met.

fun drag(dest: Point): Unit

Drags this object to the specified point.

fun drag(dest: Point, speed: Int): Unit

Drags this object to the specified point.

fun findObject(selector: BySelector): UiObject2!

Searches all elements under this object and returns the first one to match the selector, or null if no matching objects are found.

fun findObjects(selector: BySelector): (Mutable)List<UiObject2!>

Searches all elements under this object and returns those that match the selector.

fun fling(direction: Direction): Boolean

Performs a fling gesture on this object.

fun fling(direction: Direction, speed: Int): Boolean

Performs a fling gesture on this object.

fun getAccessibilityNodeInfo(): AccessibilityNodeInfo

Returns an up-to-date AccessibilityNodeInfo corresponding to this object's underlying View. Note that this method can be expensive as it wait for the device to be idle and tries multiple time to refresh the AccessibilityNodeInfo.

fun getApplicationPackage(): String!

Returns the package name of the app that this object belongs to.

fun getChildCount(): Int

Returns the number of child elements directly under this object.

fun getChildren(): (Mutable)List<UiObject2!>

Returns a collection of the child elements directly under this object.

fun getClassName(): String!

Returns the class name of this object's underlying View.

fun getContentDescription(): String!

Returns this object's content description.

fun getDisplayId(): Int

Returns the ID of the display containing this object.

@RequiresApi(value = 24)
fun getDrawingOrder(): Int

Returns the drawing order (z-index) of this object relative to its siblings. Higher values are drawn last (i.e. above their siblings).

In some cases, the drawing order is essentially simultaneous, so it is possible for two siblings to return the same value. It is also possible that values will be skipped.

@RequiresApi(value = 26)
fun getHint(): String?

Returns the hint text of this object, or null if hint text is not preset.

Hint text is displayed when there's no user input text.

fun getParent(): UiObject2!

Returns this object's parent, or null if it has no parent.

fun getResourceName(): String!

Returns the fully qualified resource name for this object's ID.

fun getText(): String!

Returns this object's text content.

fun getVisibleBounds(): Rect

Returns this object's visible bounds.

fun getVisibleCenter(): Point

Returns a point in the center of this object's visible bounds.

fun hasObject(selector: BySelector): Boolean

Returns true if there is a nested element which matches the selector.

fun isCheckable(): Boolean

Returns true if this object is checkable.

fun isChecked(): Boolean

Returns true if this object is checked.

fun isClickable(): Boolean

Returns true if this object is clickable.

fun isEnabled(): Boolean

Returns true if this object is enabled.

fun isFocusable(): Boolean

Returns true if this object is focusable.

fun isFocused(): Boolean

Returns true if this object is focused.

fun isLongClickable(): Boolean

Returns true if this object is long clickable.

fun isScrollable(): Boolean

Returns true if this object is scrollable.

fun isSelected(): Boolean

Returns true if this object is selected.

fun longClick(): Unit

Performs a long click on this object's center.

fun pinchClose(percent: Float): Unit

Performs a pinch close gesture on this object.

fun pinchClose(percent: Float, speed: Int): Unit

Performs a pinch close gesture on this object.

fun pinchOpen(percent: Float): Unit

Performs a pinch open gesture on this object.

fun pinchOpen(percent: Float, speed: Int): Unit

Performs a pinch open gesture on this object.

fun recycle(): Unit

Recycle this object.

fun scroll(direction: Direction, percent: Float): Boolean

Performs a scroll gesture on this object.

fun scroll(direction: Direction, percent: Float, speed: Int): Boolean

Performs a scroll gesture on this object.

fun <U> scrollUntil(direction: Direction, condition: Condition<UiObject2!, U!>): U!

Perform scroll actions in certain direction until a condition is satisfied or scroll has finished, e.g. to scroll until an object contain certain text is found:

 mScrollableUiObject2.scrollUntil(Direction.DOWN, Until.findObject(By.textContains
("sometext"))); 

fun <U> scrollUntil(direction: Direction, condition: EventCondition<U!>): U!

Perform scroll actions in certain direction until a condition is satisfied or scroll has finished, e.g. to scroll until a new window has appeared:

 mScrollableUiObject2.scrollUntil(Direction.DOWN, Until.newWindow()); 

fun setGestureMargin(margin: Int): Unit

Sets the margins used for gestures in pixels.

fun setGestureMarginPercentage(percent: @FloatRange(from = 0.0, to = 0.5) Float): Unit

Sets the percentage of gestures' margins to avoid touching too close to the edges, e.g. when scrolling up, phone open quick settings instead if gesture is close to the top. The percentage is based on the object's visible size, e.g. to set 20% margins:

mUiObject2.setGestureMarginPercentage(0.2f);

fun setGestureMargins(left: Int, top: Int, right: Int, bottom: Int): Unit

Sets the margins used for gestures in pixels.

fun setGestureMarginsPercentage(
    left: @FloatRange(from = 0.0, to = 1.0) Float,
    top: @FloatRange(from = 0.0, to = 1.0) Float,
    right: @FloatRange(from = 0.0, to = 1.0) Float,
    bottom: @FloatRange(from = 0.0, to = 1.0) Float
): Unit

Sets the percentage of gestures' margins to avoid touching too close to the edges, e.g. when scrolling up, phone open quick settings instead if gesture is close to the top. The percentage is based on the object's visible size, e.g. to set 20% bottom margin only:

mUiObject2.setGestureMarginsPercentage(0f, 0f, 0f, 0.2f);

left Float between [0, 1] for left margin

top Float between [0, 1] for top margin

right Float between [0, 1] for right margin

bottom Float between [0, 1] for bottom margin

fun setText(text: String?): Unit

Sets this object's text content if it is an editable field.

fun swipe(direction: Direction, percent: Float): Unit

Performs a swipe gesture on this object.

fun swipe(direction: Direction, percent: Float, speed: Int): Unit

Performs a swipe gesture on this object.

fun <U> wait(condition: Condition<UiObject2!, U!>, timeout: Long): U!

Waits for a condition to be met.

fun <U> wait(condition: SearchCondition<U!>, timeout: Long): U!

Waits for a condition to be met.

fun <U> wait(condition: UiObject2Condition<U!>, timeout: Long): U!

Waits for a condition to be met.

fun UiObject2.onElement(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Performs a DFS on the accessibility tree starting from the node associated to this UiObject2 and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, a ElementNotFoundException is thrown. Internally it works searching periodically every pollIntervalMs.

Example:

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

fun UiObject2.onElementOrNull(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2?

Performs a DFS on the accessibility tree starting from the node associated to this UiObject2 and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, null is returned. Internally it works searching periodically every pollIntervalMs.

Example:

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

fun UiObject2.onElements(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): List<UiObject2>

Performs a DFS on the accessibility tree starting from the node associated to this UiObject2 and returns all the nodes matching the given block. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are UiObject2 that allow interacting with them. Internally it works searching periodically every pollIntervalMs.

Example:

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

If multiple nodes are expected but they appear at different times, it's recommended to call androidx.test.uiautomator.waitForStable before, to ensure any operation is complete.

fun UiObject2.scrollToElement(
    direction: Direction,
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Keeps scrolling until the given block condition is satisfied or until the given timeoutMs. Throws a ElementNotFoundException if the condition is not satisfied at the end of the timeout.

Example:

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

fun UiObject2.scrollToElementOrNull(
    direction: Direction,
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2?

Keeps scrolling until the given block condition is satisfied or until the given timeoutMs. Returns null if the condition is not satisfied at the end of the timeout.

Example:

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

fun UiObject2.takeScreenshot(): Bitmap

Takes a screenshot of the screen that contains the accessibility node associated to this UiObject2 and cuts only the area covered by it.

fun UiObject2.waitForStable(
    stableTimeoutMs: Long = 3000,
    stableIntervalMs: Long = 500,
    stablePollIntervalMs: Long = 50,
    requireStableScreenshot: Boolean = true
): StableResult

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.