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

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

void

Clicks on this object's center.

void
click(long duration)

Clicks on this object's center for duration milliseconds.

void

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

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

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>

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

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

int

Returns the number of child elements directly under this object.

@NonNull List<UiObject2>

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

String

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

String

Returns this object's content description.

int

Returns the ID of the display containing this object.

int

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

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

String

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

String

Returns this object's text content.

@NonNull Rect

Returns this object's visible bounds.

@NonNull Point

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

boolean

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

int
boolean

Returns true if this object is checkable.

boolean

Returns true if this object is checked.

boolean

Returns true if this object is clickable.

boolean

Returns true if this object is enabled.

boolean

Returns true if this object is focusable.

boolean

Returns true if this object is focused.

boolean

Returns true if this object is long clickable.

boolean

Returns true if this object is scrollable.

boolean

Returns true if this object is selected.

void

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 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<Object, 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

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<Object, 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

public void clear()

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

click

public void click()

Clicks on this object's center.

click

public void click(long duration)

Clicks on this object's center for duration milliseconds.

click

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

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

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

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

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

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

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

public @NonNull List<UiObject2findObjects(@NonNull BySelector selector)

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

fling

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

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

public String getApplicationPackage()

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

getChildCount

public int getChildCount()

Returns the number of child elements directly under this object.

getChildren

public @NonNull List<UiObject2getChildren()

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

getClassName

public String getClassName()

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

getContentDescription

public String getContentDescription()

Returns this object's content description.

getDisplayId

public int getDisplayId()

Returns the ID of the display containing this object.

getDrawingOrder

@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

@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

public UiObject2 getParent()

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

getResourceName

public String getResourceName()

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

getText

public String getText()

Returns this object's text content.

See also
getText

getVisibleBounds

public @NonNull Rect getVisibleBounds()

Returns this object's visible bounds.

getVisibleCenter

public @NonNull Point getVisibleCenter()

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

hasObject

public boolean hasObject(@NonNull BySelector selector)

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

hashCode

public int hashCode()

isCheckable

public boolean isCheckable()

Returns true if this object is checkable.

See also
Checkable

isChecked

public boolean isChecked()

Returns true if this object is checked.

See also
isChecked

isClickable

public boolean isClickable()

Returns true if this object is clickable.

See also
isClickable

isEnabled

public boolean isEnabled()

Returns true if this object is enabled.

See also
isEnabled

isFocusable

public boolean isFocusable()

Returns true if this object is focusable.

See also
isFocusable

isFocused

public boolean isFocused()

Returns true if this object is focused.

See also
isFocused

isLongClickable

public boolean isLongClickable()

Returns true if this object is long clickable.

See also
isLongClickable

isScrollable

public boolean isScrollable()

Returns true if this object is scrollable.

isSelected

public boolean isSelected()

Returns true if this object is selected.

See also
isSelected

longClick

public void longClick()

Performs a long click on this object's center.

pinchClose

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

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

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

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

public void recycle()

Recycle this object.

scroll

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

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

public U <U> scrollUntil(
    @NonNull Direction direction,
    @NonNull Condition<Object, 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<Object, U> condition

The Condition to evaluate.

Returns
U

If the condition is satisfied.

scrollUntil

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

public void setGestureMargin(int margin)

Sets the margins used for gestures in pixels.

setGestureMarginPercentage

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

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

Sets the margins used for gestures in pixels.

setGestureMarginsPercentage

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

public void setText(@Nullable String text)

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

swipe

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

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

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

Waits for a condition to be met.

Parameters
@NonNull Condition<Object, 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

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

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.