UiObject2

Artifact: androidx.test.uiautomator:uiautomator

Kotlin |Java

class UiObject2

Represents a UI element, and exposes methods for performing gestures (clicks, swipes) or searching through its children.

Unlike UiObject, UiObject2 is bound to a particular view instance and can become stale if the underlying view object is destroyed. As a result, it may be necessary to call findObject to obtain a new UiObject2 instance if the UI changes significantly.

Summary

Public functions
`Unit`	`clear()` Clears this object's text content if it is an editable field.
`Unit`	`click()` Clicks on this object's center.
`Unit`	`click(duration: Long)` Clicks on this object's center for `duration` milliseconds.
`Unit`	`click(point: Point)` Clicks on a `point` within this object's visible bounds.
`Unit`	`click(point: Point, duration: Long)` Clicks on a `point` within this object's visible bounds.
`U!`	`<U> clickAndWait(condition: EventCondition<U!>, timeout: Long)` Clicks on this object's center, and waits for a `condition` to be met.
`U!`	`<U> clickAndWait(point: Point, condition: EventCondition<U!>, timeout: Long)` Clicks on a `point` within this object's visible bounds, and waits for a `condition` to be met.
`Unit`	`drag(dest: Point)` Drags this object to the specified point.
`Unit`	`drag(dest: Point, speed: Int)` Drags this object to the specified point.
`Boolean`	`equals(object: Any!)`
`UiObject2!`	`findObject(selector: BySelector)` Searches all elements under this object and returns the first one to match the `selector`, or `null` if no matching objects are found.
`(Mutable)List<UiObject2!>`	`findObjects(selector: BySelector)` Searches all elements under this object and returns those that match the `selector`.
`Boolean`	`fling(direction: Direction)` Performs a fling gesture on this object.
`Boolean`	`fling(direction: Direction, speed: Int)` Performs a fling gesture on this object.
`String!`	`getApplicationPackage()` Returns the package name of the app that this object belongs to.
`Int`	`getChildCount()` Returns the number of child elements directly under this object.
`(Mutable)List<UiObject2!>`	`getChildren()` Returns a collection of the child elements directly under this object.
`String!`	`getClassName()` Returns the class name of this object's underlying `View`.
`String!`	`getContentDescription()` Returns this object's content description.
`Int`	`getDisplayId()` Returns the ID of the display containing this object.
`Int`	`@RequiresApi(value = 24) getDrawingOrder()` Returns the drawing order (z-index) of this object relative to its siblings.
`String?`	`@RequiresApi(value = 26) getHint()` Returns the hint text of this object, or null if hint text is not preset.
`UiObject2!`	`getParent()` Returns this object's parent, or `null` if it has no parent.
`String!`	`getResourceName()` Returns the fully qualified resource name for this object's ID.
`String!`	`getText()` Returns this object's text content.
`Rect`	`getVisibleBounds()` Returns this object's visible bounds.
`Point`	`getVisibleCenter()` Returns a point in the center of this object's visible bounds.
`Boolean`	`hasObject(selector: BySelector)` Returns `true` if there is a nested element which matches the `selector`.
`Int`	`hashCode()`
`Boolean`	`isCheckable()` Returns `true` if this object is checkable.
`Boolean`	`isChecked()` Returns `true` if this object is checked.
`Boolean`	`isClickable()` Returns `true` if this object is clickable.
`Boolean`	`isEnabled()` Returns `true` if this object is enabled.
`Boolean`	`isFocusable()` Returns `true` if this object is focusable.
`Boolean`	`isFocused()` Returns `true` if this object is focused.
`Boolean`	`isLongClickable()` Returns `true` if this object is long clickable.
`Boolean`	`isScrollable()` Returns `true` if this object is scrollable.
`Boolean`	`isSelected()` Returns `true` if this object is selected.
`Unit`	`longClick()` Performs a long click on this object's center.
`Unit`	`pinchClose(percent: Float)` Performs a pinch close gesture on this object.
`Unit`	`pinchClose(percent: Float, speed: Int)` Performs a pinch close gesture on this object.
`Unit`	`pinchOpen(percent: Float)` Performs a pinch open gesture on this object.
`Unit`	`pinchOpen(percent: Float, speed: Int)` Performs a pinch open gesture on this object.
`Unit`	`recycle()` Recycle this object.
`Boolean`	`scroll(direction: Direction, percent: Float)` Performs a scroll gesture on this object.
`Boolean`	`scroll(direction: Direction, percent: Float, speed: Int)` Performs a scroll gesture on this object.
`U!`	`<U> scrollUntil(direction: Direction, condition: Condition<UiObject2!, 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:
`U!`	`<U> scrollUntil(direction: Direction, condition: EventCondition<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:
`Unit`	`setGestureMargin(margin: Int)` Sets the margins used for gestures in pixels.
`Unit`	`setGestureMarginPercentage(percent: @FloatRange(from = 0.0, to = 0.5) Float)` 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.
`Unit`	`setGestureMargins(left: Int, top: Int, right: Int, bottom: Int)` Sets the margins used for gestures in pixels.
`Unit`	`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 )` 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.
`Unit`	`setText(text: String?)` Sets this object's text content if it is an editable field.
`Unit`	`swipe(direction: Direction, percent: Float)` Performs a swipe gesture on this object.
`Unit`	`swipe(direction: Direction, percent: Float, speed: Int)` Performs a swipe gesture on this object.
`U!`	`<U> wait(condition: Condition<UiObject2!, U!>, timeout: Long)` Waits for a `condition` to be met.
`U!`	`<U> wait(condition: SearchCondition<U!>, timeout: Long)` Waits for a `condition` to be met.
`U!`	`<U> wait(condition: UiObject2Condition<U!>, timeout: Long)` Waits for a `condition` to be met.

Public functions

clear

fun clear(): Unit

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

click

fun click(): Unit

Clicks on this object's center.

click

fun click(duration: Long): Unit

Clicks on this object's center for duration milliseconds.

click

fun click(point: Point): Unit

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

Parameters
`point: Point`	The point to click (clipped to ensure it is within the visible bounds).

click

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

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

Parameters
`point: Point`	The point to click (clipped to ensure it is within the visible bounds).
`duration: Long`	The click duration in milliseconds.

clickAndWait

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

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

Parameters
`condition: EventCondition<U!>`	The `EventCondition` to wait for.
`timeout: Long`	The maximum time in milliseconds to wait for.

clickAndWait

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.

Parameters
`point: Point`	The point to click (clipped to ensure it is within the visible bounds).
`condition: EventCondition<U!>`	The `EventCondition` to wait for.
`timeout: Long`	The maximum time in milliseconds to wait for.

drag

fun drag(dest: Point): Unit

Drags this object to the specified point.

Parameters
`dest: Point`	The end point to drag this object to.

drag

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

Drags this object to the specified point.

Parameters
`dest: Point`	The end point to drag this object to.
`speed: Int`	The speed at which to perform this gesture in pixels per second.

equals

fun equals(object: Any!): Boolean

findObject

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.

findObjects

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

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

fling

fun fling(direction: Direction): Boolean

Performs a fling gesture on this object.

Parameters
`direction: Direction`	The direction in which to fling.

Returns
`Boolean`	`true` if the object can still scroll in the given direction.

fling

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

Performs a fling gesture on this object.

Parameters
`direction: Direction`	The direction in which to fling.
`speed: Int`	The speed at which to perform this gesture in pixels per second.

Returns
`Boolean`	`true` if the object can still scroll in the given direction.

getApplicationPackage

fun getApplicationPackage(): String!

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

getChildCount

fun getChildCount(): Int

Returns the number of child elements directly under this object.

getChildren

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

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

getClassName

fun getClassName(): String!

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

getContentDescription

fun getContentDescription(): String!

Returns this object's content description.

See also
`getContentDescription`

getDisplayId

fun getDisplayId(): Int

Returns the ID of the display containing this object.

getDrawingOrder

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

Returns
`Int`	The drawing order of this object relative to its siblings.

getHint

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

See also
`getHint`

getParent

fun getParent(): UiObject2!

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

getResourceName

fun getResourceName(): String!

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

getText

fun getText(): String!

Returns this object's text content.

See also
`getText`

getVisibleBounds

fun getVisibleBounds(): Rect

Returns this object's visible bounds.

getVisibleCenter

fun getVisibleCenter(): Point

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

hasObject

fun hasObject(selector: BySelector): Boolean

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

hashCode

fun hashCode(): Int

isCheckable

fun isCheckable(): Boolean

Returns true if this object is checkable.

See also
`Checkable`

isChecked

fun isChecked(): Boolean

Returns true if this object is checked.

See also
`isChecked`

isClickable

fun isClickable(): Boolean

Returns true if this object is clickable.

See also
`isClickable`

isEnabled

fun isEnabled(): Boolean

Returns true if this object is enabled.

See also
`isEnabled`

isFocusable

fun isFocusable(): Boolean

Returns true if this object is focusable.

See also
`isFocusable`

isFocused

fun isFocused(): Boolean

Returns true if this object is focused.

See also
`isFocused`

isLongClickable

fun isLongClickable(): Boolean

Returns true if this object is long clickable.

See also
`isLongClickable`

isScrollable

fun isScrollable(): Boolean

Returns true if this object is scrollable.

isSelected

fun isSelected(): Boolean

Returns true if this object is selected.

See also
`isSelected`

longClick

fun longClick(): Unit

Performs a long click on this object's center.

pinchClose

fun pinchClose(percent: Float): Unit

Performs a pinch close gesture on this object.

Parameters
`percent: Float`	The size of the pinch as a percentage of this object's size.

pinchClose

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

Performs a pinch close gesture on this object.

Parameters
`percent: Float`	The size of the pinch as a percentage of this object's size.
`speed: Int`	The speed at which to perform this gesture in pixels per second.

pinchOpen

fun pinchOpen(percent: Float): Unit

Performs a pinch open gesture on this object.

Parameters
`percent: Float`	The size of the pinch as a percentage of this object's size.

pinchOpen

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

Performs a pinch open gesture on this object.

Parameters
`percent: Float`	The size of the pinch as a percentage of this object's size.
`speed: Int`	The speed at which to perform this gesture in pixels per second.

recycle

fun recycle(): Unit

Recycle this object.

scroll

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

Performs a scroll gesture on this object.

Parameters
`direction: Direction`	The direction in which to scroll.
`percent: Float`	The distance to scroll as a percentage of this object's visible size.

Returns
`Boolean`	`true` if the object can still scroll in the given direction.

scroll

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

Performs a scroll gesture on this object.

Parameters
`direction: Direction`	The direction in which to scroll.
`percent: Float`	The distance to scroll as a percentage of this object's visible size.
`speed: Int`	The speed at which to perform this gesture in pixels per second.

Returns
`Boolean`	`true` if the object can still scroll in the given direction.

scrollUntil

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")));

Parameters
`direction: Direction`	The direction in which to scroll.
`condition: Condition<UiObject2!, U!>`	The `Condition` to evaluate.

Returns
`U!`	If the condition is satisfied.

scrollUntil

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());

Parameters
`direction: Direction`	The direction in which to scroll.
`condition: EventCondition<U!>`	The `EventCondition` to wait for.

Returns
`U!`	The value obtained after applying the condition.

setGestureMargin

fun setGestureMargin(margin: Int): Unit

Sets the margins used for gestures in pixels.

setGestureMarginPercentage

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

percent Float between [0, 0.5] for four margins: left, top, right, and bottom.

setGestureMargins

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

Sets the margins used for gestures in pixels.

setGestureMarginsPercentage

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

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

setText

fun setText(text: String?): Unit

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

swipe

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

Performs a swipe gesture on this object.

Parameters
`direction: Direction`	The direction in which to swipe.
`percent: Float`	The length of the swipe as a percentage of this object's size.

swipe

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

Performs a swipe gesture on this object.

Parameters
`direction: Direction`	The direction in which to swipe.
`percent: Float`	The length of the swipe as a percentage of this object's size.
`speed: Int`	The speed at which to perform this gesture in pixels per second.

wait

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

Waits for a condition to be met.

Parameters
`condition: Condition<UiObject2!, U!>`	The `Condition` to evaluate.
`timeout: Long`	The maximum time in milliseconds to wait for.

Returns
`U!`	The final result returned by the `condition`, or `null` if the `condition` was not met before the `timeout`.

wait

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

Waits for a condition to be met.

Parameters
`condition: SearchCondition<U!>`	The `SearchCondition` to evaluate.
`timeout: Long`	The maximum time in milliseconds to wait for.

Returns
`U!`	The final result returned by the `condition`, or `null` if the `condition` was not met before the `timeout`.

wait

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

Waits for a condition to be met.

Parameters
`condition: UiObject2Condition<U!>`	The `UiObject2Condition` to wait for.
`timeout: Long`	The maximum time in milliseconds to wait for.

Returns
`U!`	The final result returned by the `condition`, or `null` if the `condition` was not met before the `timeout`.