UiObject2

Artifact: androidx.test.uiautomator:uiautomator

View Source

Added in 2.2.0

---

Kotlin |Java

public 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 methods
void	clear() Clears this object's text content if it is an editable field.
void	click() Clicks on this object's center.
void	click(long duration) Clicks on this object's center for duration milliseconds.
void	click(@NonNull Point point) Clicks on a point within this object's visible bounds.
void	click(@NonNull Point point, long duration) Clicks on a point within this object's visible bounds.
U	<U> clickAndWait(@NonNull EventCondition<U> condition, long timeout) Clicks on this object's center, and waits for a condition to be met.
U	<U> clickAndWait(     @NonNull Point point,     @NonNull EventCondition<U> condition,     long timeout ) Clicks on a point within this object's visible bounds, and waits for a condition to be met.
void	drag(@NonNull Point dest) Drags this object to the specified point.
void	drag(@NonNull Point dest, int speed) Drags this object to the specified point.
boolean	equals(Object object)
UiObject2	findObject(@NonNull BySelector selector) Searches all elements under this object and returns the first one to match the selector, or null if no matching objects are found.
@NonNull List<UiObject2>	findObjects(@NonNull BySelector selector) Searches all elements under this object and returns those that match the selector.
boolean	fling(@NonNull Direction direction) Performs a fling gesture on this object.
boolean	fling(@NonNull Direction direction, int speed) 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.
@NonNull 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.
@Nullable 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.
@NonNull Rect	getVisibleBounds() Returns this object's visible bounds.
@NonNull Point	getVisibleCenter() Returns a point in the center of this object's visible bounds.
boolean	hasObject(@NonNull BySelector selector) 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.
void	longClick() Performs a long click on this object's center.
void	pinchClose(float percent) Performs a pinch close gesture on this object.
void	pinchClose(float percent, int speed) Performs a pinch close gesture on this object.
void	pinchOpen(float percent) Performs a pinch open gesture on this object.
void	pinchOpen(float percent, int speed) Performs a pinch open gesture on this object.
void	recycle() Recycle this object.
boolean	scroll(@NonNull Direction direction, float percent) Performs a scroll gesture on this object.
boolean	scroll(@NonNull Direction direction, float percent, int speed) Performs a scroll gesture on this object.
U	<U> scrollUntil(     @NonNull Direction direction,     @NonNull Condition<UiObject2, U> condition ) 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(     @NonNull Direction direction,     @NonNull EventCondition<U> condition ) 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:
void	setGestureMargin(int margin) Sets the margins used for gestures in pixels.
void	setGestureMarginPercentage(@FloatRange(from = 0.0, to = 0.5) float percent) 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.
void	setGestureMargins(int left, int top, int right, int bottom) Sets the margins used for gestures in pixels.
void	setGestureMarginsPercentage(     @FloatRange(from = 0.0, to = 1.0) float 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 ) 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.
void	setText(@Nullable String text) Sets this object's text content if it is an editable field.
void	swipe(@NonNull Direction direction, float percent) Performs a swipe gesture on this object.
void	swipe(@NonNull Direction direction, float percent, int speed) Performs a swipe gesture on this object.
U	<U> wait(@NonNull Condition<UiObject2, U> condition, long timeout) Waits for a condition to be met.
U	<U> wait(@NonNull SearchCondition<U> condition, long timeout) Waits for a condition to be met.
U	<U> wait(@NonNull UiObject2Condition<U> condition, long timeout) Waits for a condition to be met.

Public methods

clear

Added in 2.2.0

public void clear()

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

click

Added in 2.2.0

public void click()

Clicks on this object's center.

click

Added in 2.2.0

public void click(long duration)

Clicks on this object's center for duration milliseconds.

click

Added in 2.3.0

public void click(@NonNull Point point)

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

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

click

Added in 2.3.0

public void click(@NonNull Point point, long duration)

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

Parameters
@NonNull Point point	The point to click (clipped to ensure it is within the visible bounds).
long duration	The click duration in milliseconds.

clickAndWait

Added in 2.3.0

public U <U> clickAndWait(@NonNull EventCondition<U> condition, long timeout)

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

Parameters
@NonNull EventCondition<U> condition	The EventCondition to wait for.
long timeout	The maximum time in milliseconds to wait for.

clickAndWait

Added in 2.3.0

public U <U> clickAndWait(
    @NonNull Point point,
    @NonNull EventCondition<U> condition,
    long timeout
)

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

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

drag

Added in 2.2.0

public void drag(@NonNull Point dest)

Drags this object to the specified point.

Parameters
@NonNull Point dest	The end point to drag this object to.

drag

Added in 2.2.0

public void drag(@NonNull Point dest, int speed)

Drags this object to the specified point.

Parameters
@NonNull Point dest	The end point to drag this object to.
int speed	The speed at which to perform this gesture in pixels per second.

equals

public boolean equals(Object object)

findObject

Added in 2.2.0

public UiObject2 findObject(@NonNull BySelector selector)

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

public @NonNull List<UiObject2> findObjects(@NonNull BySelector selector)

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

fling

Added in 2.2.0

public boolean fling(@NonNull Direction direction)

Performs a fling gesture on this object.

Parameters
@NonNull 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

public boolean fling(@NonNull Direction direction, int speed)

Performs a fling gesture on this object.

Parameters
@NonNull Direction direction	The direction in which to fling.
int speed	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

public String getApplicationPackage()

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

getChildCount

Added in 2.2.0

public int getChildCount()

Returns the number of child elements directly under this object.

getChildren

Added in 2.2.0

public @NonNull List<UiObject2> getChildren()

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

getClassName

Added in 2.2.0

public String getClassName()

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

getContentDescription

Added in 2.2.0

public String getContentDescription()

Returns this object's content description.

See also
getContentDescription

getDisplayId

Added in 2.3.0

public int getDisplayId()

Returns the ID of the display containing this object.

getDrawingOrder

Added in 2.3.0

@RequiresApi(value = 24)
public int getDrawingOrder()

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)
public @Nullable String getHint()

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

public UiObject2 getParent()

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

getResourceName

Added in 2.2.0

public String getResourceName()

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

getText

Added in 2.2.0

public String getText()

Returns this object's text content.

See also
getText

getVisibleBounds

Added in 2.2.0

public @NonNull Rect getVisibleBounds()

Returns this object's visible bounds.

getVisibleCenter

Added in 2.2.0

public @NonNull Point getVisibleCenter()

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

hasObject

Added in 2.2.0

public boolean hasObject(@NonNull BySelector selector)

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

hashCode

public int hashCode()

isCheckable

Added in 2.2.0

public boolean isCheckable()

Returns true if this object is checkable.

See also
Checkable

isChecked

Added in 2.2.0

public boolean isChecked()

Returns true if this object is checked.

See also
isChecked

isClickable

Added in 2.2.0

public boolean isClickable()

Returns true if this object is clickable.

See also
isClickable

isEnabled

Added in 2.2.0

public boolean isEnabled()

Returns true if this object is enabled.

See also
isEnabled

isFocusable

Added in 2.2.0

public boolean isFocusable()

Returns true if this object is focusable.

See also
isFocusable

isFocused

Added in 2.2.0

public boolean isFocused()

Returns true if this object is focused.

See also
isFocused

isLongClickable

Added in 2.2.0

public boolean isLongClickable()

Returns true if this object is long clickable.

See also
isLongClickable

isScrollable

Added in 2.2.0

public boolean isScrollable()

Returns true if this object is scrollable.

isSelected

Added in 2.2.0

public boolean isSelected()

Returns true if this object is selected.

See also
isSelected

longClick

Added in 2.2.0

public void longClick()

Performs a long click on this object's center.

pinchClose

Added in 2.2.0

public void pinchClose(float percent)

Performs a pinch close gesture on this object.

Parameters
float percent	The size of the pinch as a percentage of this object's size.

pinchClose

Added in 2.2.0

public void pinchClose(float percent, int speed)

Performs a pinch close gesture on this object.

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

pinchOpen

Added in 2.2.0

public void pinchOpen(float percent)

Performs a pinch open gesture on this object.

Parameters
float percent	The size of the pinch as a percentage of this object's size.

pinchOpen

Added in 2.2.0

public void pinchOpen(float percent, int speed)

Performs a pinch open gesture on this object.

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

recycle

Added in 2.2.0

public void recycle()

Recycle this object.

scroll

Added in 2.2.0

public boolean scroll(@NonNull Direction direction, float percent)

Performs a scroll gesture on this object.

Parameters
@NonNull Direction direction	The direction in which to scroll.
float percent	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

public boolean scroll(@NonNull Direction direction, float percent, int speed)

Performs a scroll gesture on this object.

Parameters
@NonNull Direction direction	The direction in which to scroll.
float percent	The distance to scroll as a percentage of this object's visible size.
int speed	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

public U <U> scrollUntil(
    @NonNull Direction direction,
    @NonNull Condition<UiObject2, U> condition
)

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
@NonNull Direction direction	The direction in which to scroll.
@NonNull Condition<UiObject2, U> condition	The Condition to evaluate.

Returns
U	If the condition is satisfied.

scrollUntil

Added in 2.3.0

public U <U> scrollUntil(
    @NonNull Direction direction,
    @NonNull EventCondition<U> condition
)

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
@NonNull Direction direction	The direction in which to scroll.
@NonNull EventCondition<U> condition	The EventCondition to wait for.

Returns
U	The value obtained after applying the condition.

setGestureMargin

Added in 2.2.0

public void setGestureMargin(int margin)

Sets the margins used for gestures in pixels.

setGestureMarginPercentage

Added in 2.3.0

public void setGestureMarginPercentage(@FloatRange(from = 0.0, to = 0.5) float percent)

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

public void setGestureMargins(int left, int top, int right, int bottom)

Sets the margins used for gestures in pixels.

setGestureMarginsPercentage

Added in 2.3.0

public void setGestureMarginsPercentage(
    @FloatRange(from = 0.0, to = 1.0) float 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
)

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

public void setText(@Nullable String text)

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

swipe

Added in 2.2.0

public void swipe(@NonNull Direction direction, float percent)

Performs a swipe gesture on this object.

Parameters
@NonNull Direction direction	The direction in which to swipe.
float percent	The length of the swipe as a percentage of this object's size.

swipe

Added in 2.2.0

public void swipe(@NonNull Direction direction, float percent, int speed)

Performs a swipe gesture on this object.

Parameters
@NonNull Direction direction	The direction in which to swipe.
float percent	The length of the swipe as a percentage of this object's size.
int speed	The speed at which to perform this gesture in pixels per second.

wait

Added in 2.3.0

public U <U> wait(@NonNull Condition<UiObject2, U> condition, long timeout)

Waits for a condition to be met.

Parameters
@NonNull Condition<UiObject2, U> condition	The Condition to evaluate.
long timeout	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

public U <U> wait(@NonNull SearchCondition<U> condition, long timeout)

Waits for a condition to be met.

Parameters
@NonNull SearchCondition<U> condition	The SearchCondition to evaluate.
long timeout	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

public U <U> wait(@NonNull UiObject2Condition<U> condition, long timeout)

Waits for a condition to be met.

Parameters
@NonNull UiObject2Condition<U> condition	The UiObject2Condition to wait for.
long timeout	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.