UiObject2

Artifact: androidx.test.uiautomator:uiautomator

View Source

Added in 2.2.0

---

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

Added in 2.2.0

fun clear(): Unit

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

click

Added in 2.2.0

fun click(): Unit

Clicks on this object's center.

click

Added in 2.2.0

fun click(duration: Long): Unit

Clicks on this object's center for duration milliseconds.

click

Added in 2.3.0

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

Added in 2.3.0

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

Added in 2.3.0

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

Added in 2.3.0

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

Added in 2.2.0

fun drag(dest: Point): Unit

Drags this object to the specified point.

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

drag

Added in 2.2.0

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

Added in 2.2.0

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

Added in 2.2.0

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

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

fling

Added in 2.2.0

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

Added in 2.2.0

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

Added in 2.2.0

fun getApplicationPackage(): String!

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

getChildCount

Added in 2.2.0

fun getChildCount(): Int

Returns the number of child elements directly under this object.

getChildren

Added in 2.2.0

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

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

getClassName

Added in 2.2.0

fun getClassName(): String!

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

getContentDescription

Added in 2.2.0

fun getContentDescription(): String!

Returns this object's content description.

See also
getContentDescription

getDisplayId

Added in 2.3.0

fun getDisplayId(): Int

Returns the ID of the display containing this object.

getDrawingOrder

Added in 2.3.0

@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

Added in 2.3.0

@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

Added in 2.2.0

fun getParent(): UiObject2!

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

getResourceName

Added in 2.2.0

fun getResourceName(): String!

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

getText

Added in 2.2.0

fun getText(): String!

Returns this object's text content.

See also
getText

getVisibleBounds

Added in 2.2.0

fun getVisibleBounds(): Rect

Returns this object's visible bounds.

getVisibleCenter

Added in 2.2.0

fun getVisibleCenter(): Point

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

hasObject

Added in 2.2.0

fun hasObject(selector: BySelector): Boolean

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

hashCode

fun hashCode(): Int

isCheckable

Added in 2.2.0

fun isCheckable(): Boolean

Returns true if this object is checkable.

See also
Checkable

isChecked

Added in 2.2.0

fun isChecked(): Boolean

Returns true if this object is checked.

See also
isChecked

isClickable

Added in 2.2.0

fun isClickable(): Boolean

Returns true if this object is clickable.

See also
isClickable

isEnabled

Added in 2.2.0

fun isEnabled(): Boolean

Returns true if this object is enabled.

See also
isEnabled

isFocusable

Added in 2.2.0

fun isFocusable(): Boolean

Returns true if this object is focusable.

See also
isFocusable

isFocused

Added in 2.2.0

fun isFocused(): Boolean

Returns true if this object is focused.

See also
isFocused

isLongClickable

Added in 2.2.0

fun isLongClickable(): Boolean

Returns true if this object is long clickable.

See also
isLongClickable

isScrollable

Added in 2.2.0

fun isScrollable(): Boolean

Returns true if this object is scrollable.

isSelected

Added in 2.2.0

fun isSelected(): Boolean

Returns true if this object is selected.

See also
isSelected

longClick

Added in 2.2.0

fun longClick(): Unit

Performs a long click on this object's center.

pinchClose

Added in 2.2.0

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

Added in 2.2.0

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

Added in 2.2.0

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

Added in 2.2.0

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

Added in 2.2.0

fun recycle(): Unit

Recycle this object.

scroll

Added in 2.2.0

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

Added in 2.2.0

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

Added in 2.3.0

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

Added in 2.3.0

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

Added in 2.2.0

fun setGestureMargin(margin: Int): Unit

Sets the margins used for gestures in pixels.

setGestureMarginPercentage

Added in 2.3.0

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

Added in 2.2.0

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

Sets the margins used for gestures in pixels.

setGestureMarginsPercentage

Added in 2.3.0

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

setText

Added in 2.2.0

fun setText(text: String?): Unit

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

swipe

Added in 2.2.0

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

Added in 2.2.0

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

Added in 2.3.0

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

Added in 2.3.0

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

Added in 2.3.0

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.