public class UiObject

Known direct subclasses
UiCollection

Used to enumerate a container's UI elements for the purpose of counting, or targeting a sub elements by a child's text or description.

Known indirect subclasses
UiScrollable

UiScrollable is a UiCollection and provides support for searching for items in scrollable layout elements.


A UiObject is a representation of a view. It is not in any way directly bound to a view as an object reference. A UiObject contains information to help it locate a matching view at runtime based on the UiSelector properties specified in its constructor. Once you create an instance of a UiObject, it can be reused for different views that match the selector criteria.

Summary

Constants

static final int
static final int
static final long

This field is deprecated.

use setScrollAcknowledgmentTimeout

static final long
static final long

This field is deprecated.

use setWaitForSelectorTimeout

static final long

Public constructors

UiObject(UiSelector selector)

This method is deprecated.

Use findObject instead.

Public methods

void

Clears the existing text contents in an editable field.

boolean

Performs a click at the center of the visible bounds of the UI element represented by this UiObject.

boolean

Waits for window transitions that would typically take longer than the usual default timeouts.

boolean

Performs a click at the center of the visible bounds of the UI element represented by this UiObject and waits for window transitions.

boolean

Clicks the bottom and right corner of the UI element

boolean

Clicks the top and left corner of the UI element

boolean
dragTo(@NonNull UiObject destObj, int steps)

Drags this object to a destination UiObject.

boolean
dragTo(int destX, int destY, int steps)

Drags this object to arbitrary coordinates.

boolean

Check if view exists.

@NonNull Rect

Returns the view's bounds property.

@NonNull UiObject

Creates a new UiObject for a child view that is under the present UiObject.

int

Counts the child views immediately under the present UiObject.

@NonNull String

Retrieves the className property of the UI element.

@NonNull String

Reads the content_desc property of the UI element

@NonNull UiObject

Creates a new UiObject for a sibling view or a child of the sibling view, relative to the present UiObject.

@NonNull String

Reads the view's package property

final @NonNull UiSelector

Debugging helper.

@NonNull String

Reads the text property of the UI element

@NonNull Rect

Returns the visible bounds of the view.

boolean

Checks if the UI element's checkable property is currently true.

boolean

Check if the UI element's checked property is currently true

boolean

Checks if the UI element's clickable property is currently true.

boolean

Checks if the UI element's enabled property is currently true.

boolean

Check if the UI element's focusable property is currently true.

boolean

Check if the UI element's focused property is currently true

boolean

Check if the view's long-clickable property is currently true

boolean

Check if the view's scrollable property is currently true

boolean

Checks if the UI element's selected property is currently true.

boolean

Long clicks the center of the visible bounds of the UI element

boolean

Long clicks bottom and right corner of the UI element

boolean

Long clicks on the top and left corner of the UI element

boolean
performMultiPointerGesture(
    @NonNull MotionEvent.PointerCoords[][] touches
)

Performs a multi-touch gesture.

boolean
performTwoPointerGesture(
    @NonNull Point startPoint1,
    @NonNull Point startPoint2,
    @NonNull Point endPoint1,
    @NonNull Point endPoint2,
    int steps
)

Generates a two-pointer gesture with arbitrary starting and ending points.

boolean
pinchIn(int percent, int steps)

Performs a two-pointer gesture, where each pointer moves diagonally toward the other, from the edges to the center of this UiObject .

boolean
pinchOut(int percent, int steps)

Performs a two-pointer gesture, where each pointer moves diagonally opposite across the other, from the center out towards the edges of the this UiObject.

boolean

Sets the text in an editable field, after clearing the field's content.

boolean
swipeDown(int steps)

Performs the swipe down action on the UiObject.

boolean
swipeLeft(int steps)

Performs the swipe left action on the UiObject.

boolean
swipeRight(int steps)

Performs the swipe right action on the UiObject.

boolean
swipeUp(int steps)

Performs the swipe up action on the UiObject.

boolean
waitForExists(long timeout)

Waits a specified length of time for a view to become visible.

boolean
waitUntilGone(long timeout)

Waits a specified length of time for a view to become undetectable.

Protected methods

@Nullable AccessibilityNodeInfo

Finds a matching UI element in the accessibility hierarchy, by using the selector for this UiObject.

Constants

FINGER_TOUCH_HALF_WIDTH

protected static final int FINGER_TOUCH_HALF_WIDTH = 20

SWIPE_MARGIN_LIMIT

protected static final int SWIPE_MARGIN_LIMIT = 5

WAIT_FOR_EVENT_TMEOUT

protected static final long WAIT_FOR_EVENT_TMEOUT = 3000

WAIT_FOR_SELECTOR_POLL

protected static final long WAIT_FOR_SELECTOR_POLL = 1000

WAIT_FOR_SELECTOR_TIMEOUT

protected static final long WAIT_FOR_SELECTOR_TIMEOUT = 10000

WAIT_FOR_WINDOW_TMEOUT

protected static final long WAIT_FOR_WINDOW_TMEOUT = 5500

Public constructors

UiObject

public UiObject(UiSelector selector)

Constructs a UiObject to represent a view that matches the specified selector criteria.

Parameters
UiSelector selector

Public methods

clearTextField

public void clearTextField()

Clears the existing text contents in an editable field. The UiSelector of this object must reference a UI element that is editable. When you call this method, the method sets focus on the editable field, selects all of its existing content, and clears it by sending a DELETE key press

click

public boolean click()

Performs a click at the center of the visible bounds of the UI element represented by this UiObject.

Returns
boolean

true id successful else false

clickAndWaitForNewWindow

public boolean clickAndWaitForNewWindow()

Waits for window transitions that would typically take longer than the usual default timeouts. See clickAndWaitForNewWindow

Returns
boolean

true if the event was triggered, else false

clickAndWaitForNewWindow

public boolean clickAndWaitForNewWindow(long timeout)

Performs a click at the center of the visible bounds of the UI element represented by this UiObject and waits for window transitions. This method differ from click only in that this method waits for a a new window transition as a result of the click. Some examples of a window transition:

  • launching a new activity
  • bringing up a pop-up menu
  • bringing up a dialog
Parameters
long timeout

timeout before giving up on waiting for a new window

Returns
boolean

true if the event was triggered, else false

clickBottomRight

public boolean clickBottomRight()

Clicks the bottom and right corner of the UI element

Returns
boolean

true on success

clickTopLeft

public boolean clickTopLeft()

Clicks the top and left corner of the UI element

Returns
boolean

true on success

dragTo

public boolean dragTo(@NonNull UiObject destObj, int steps)

Drags this object to a destination UiObject. The number of steps specified in your input parameter can influence the drag speed, and varying speeds may impact the results. Consider evaluating different speeds when using this method in your tests.

Parameters
@NonNull UiObject destObj

the destination UiObject.

int steps

usually 40 steps. You can increase or decrease the steps to change the speed.

Returns
boolean

true if successful

dragTo

public boolean dragTo(int destX, int destY, int steps)

Drags this object to arbitrary coordinates. The number of steps specified in your input parameter can influence the drag speed, and varying speeds may impact the results. Consider evaluating different speeds when using this method in your tests.

Parameters
int destX

the X-axis coordinate.

int destY

the Y-axis coordinate.

int steps

usually 40 steps. You can increase or decrease the steps to change the speed.

Returns
boolean

true if successful

exists

public boolean exists()

Check if view exists. This methods performs a waitForExists with zero timeout. This basically returns immediately whether the view represented by this UiObject exists or not. If you need to wait longer for this view, then see waitForExists.

Returns
boolean

true if the view represented by this UiObject does exist

getBounds

public @NonNull Rect getBounds()

Returns the view's bounds property. See getVisibleBounds

Returns
@NonNull Rect

Rect

getChild

public @NonNull UiObject getChild(@NonNull UiSelector selector)

Creates a new UiObject for a child view that is under the present UiObject.

Parameters
@NonNull UiSelector selector

for child view to match

Returns
@NonNull UiObject

a new UiObject representing the child view

getChildCount

public int getChildCount()

Counts the child views immediately under the present UiObject.

Returns
int

the count of child views.

getClassName

public @NonNull String getClassName()

Retrieves the className property of the UI element.

Returns
@NonNull String

class name of the current node represented by this UiObject

getContentDescription

public @NonNull String getContentDescription()

Reads the content_desc property of the UI element

Returns
@NonNull String

value of node attribute "content_desc"

getFromParent

public @NonNull UiObject getFromParent(@NonNull UiSelector selector)

Creates a new UiObject for a sibling view or a child of the sibling view, relative to the present UiObject.

Parameters
@NonNull UiSelector selector

for a sibling view or children of the sibling view

Returns
@NonNull UiObject

a new UiObject representing the matched view

getPackageName

public @NonNull String getPackageName()

Reads the view's package property

Returns
@NonNull String

true if it is else false

getSelector

public final @NonNull UiSelector getSelector()

Debugging helper. A test can dump the properties of a selector as a string to its logs if needed. getSelector().toString();

getText

public @NonNull String getText()

Reads the text property of the UI element

Returns
@NonNull String

text value of the current node represented by this UiObject

Throws
androidx.test.uiautomator.UiObjectNotFoundException

if no match could be found

getVisibleBounds

public @NonNull Rect getVisibleBounds()

Returns the visible bounds of the view. If a portion of the view is visible, only the bounds of the visible portion are reported.

Returns
@NonNull Rect

Rect

See also
getBounds

isCheckable

public boolean isCheckable()

Checks if the UI element's checkable property is currently true.

Returns
boolean

true if it is else false

isChecked

public boolean isChecked()

Check if the UI element's checked property is currently true

Returns
boolean

true if it is else false

isClickable

public boolean isClickable()

Checks if the UI element's clickable property is currently true.

Returns
boolean

true if it is else false

isEnabled

public boolean isEnabled()

Checks if the UI element's enabled property is currently true.

Returns
boolean

true if it is else false

isFocusable

public boolean isFocusable()

Check if the UI element's focusable property is currently true.

Returns
boolean

true if it is else false

isFocused

public boolean isFocused()

Check if the UI element's focused property is currently true

Returns
boolean

true if it is else false

isLongClickable

public boolean isLongClickable()

Check if the view's long-clickable property is currently true

Returns
boolean

true if it is else false

isScrollable

public boolean isScrollable()

Check if the view's scrollable property is currently true

Returns
boolean

true if it is else false

isSelected

public boolean isSelected()

Checks if the UI element's selected property is currently true.

Returns
boolean

true if it is else false

longClick

public boolean longClick()

Long clicks the center of the visible bounds of the UI element

Returns
boolean

true if operation was successful

longClickBottomRight

public boolean longClickBottomRight()

Long clicks bottom and right corner of the UI element

Returns
boolean

true if operation was successful

longClickTopLeft

public boolean longClickTopLeft()

Long clicks on the top and left corner of the UI element

Returns
boolean

true if operation was successful

performMultiPointerGesture

public boolean performMultiPointerGesture(
    @NonNull MotionEvent.PointerCoords[][] touches
)

Performs a multi-touch gesture. You must specify touch coordinates for at least 2 pointers. Each pointer must have all of its touch steps defined in an array of PointerCoords. You can use this method to specify complex gestures, like circles and irregular shapes, where each pointer may take a different path. To create a single point on a pointer's touch path: PointerCoords p = new PointerCoords(); p.x = stepX; p.y = stepY; p.pressure = 1; p.size = 1;

Parameters
@NonNull MotionEvent.PointerCoords[][] touches

represents the pointers' paths. Each PointerCoords array represents a different pointer. Each PointerCoords in an array element represents a touch point on a pointer's path.

Returns
boolean

true if all touch events for this gesture are injected successfully, false otherwise

performTwoPointerGesture

public boolean performTwoPointerGesture(
    @NonNull Point startPoint1,
    @NonNull Point startPoint2,
    @NonNull Point endPoint1,
    @NonNull Point endPoint2,
    int steps
)

Generates a two-pointer gesture with arbitrary starting and ending points.

Parameters
@NonNull Point startPoint1

start point of pointer 1

@NonNull Point startPoint2

start point of pointer 2

@NonNull Point endPoint1

end point of pointer 1

@NonNull Point endPoint2

end point of pointer 2

int steps

the number of steps for the gesture. Steps are injected about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.

Returns
boolean

true if all touch events for this gesture are injected successfully, false otherwise

pinchIn

public boolean pinchIn(int percent, int steps)

Performs a two-pointer gesture, where each pointer moves diagonally toward the other, from the edges to the center of this UiObject .

Parameters
int percent

percentage of the object's diagonal length for the pinch gesture

int steps

the number of steps for the gesture. Steps are injected about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.

Returns
boolean

true if all touch events for this gesture are injected successfully, false otherwise

pinchOut

public boolean pinchOut(int percent, int steps)

Performs a two-pointer gesture, where each pointer moves diagonally opposite across the other, from the center out towards the edges of the this UiObject.

Parameters
int percent

percentage of the object's diagonal length for the pinch gesture

int steps

the number of steps for the gesture. Steps are injected about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.

Returns
boolean

true if all touch events for this gesture are injected successfully, false otherwise

setText

public boolean setText(@Nullable String text)

Sets the text in an editable field, after clearing the field's content.

The UiSelector selector of this object must reference a UI element that is editable.

When you call this method, the method sets focus on the editable field, clears its existing content, then injects your specified text into the field.

If you want to capture the original contents of the field, call getText first. You can then modify the text and use this method to update the field.

Improvements: Post API Level 19 (KitKat release), the underlying implementation is updated to a dedicated set text accessibility action, and it also now supports Unicode.

Parameters
@Nullable String text

string to set

Returns
boolean

true if operation is successful

swipeDown

public boolean swipeDown(int steps)

Performs the swipe down action on the UiObject. The swipe gesture can be performed over any surface. The targeted UI element does not need to be scrollable. See also:

Parameters
int steps

indicates the number of injected move steps into the system. Steps are injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.

Returns
boolean

true if successful

swipeLeft

public boolean swipeLeft(int steps)

Performs the swipe left action on the UiObject. The swipe gesture can be performed over any surface. The targeted UI element does not need to be scrollable. See also:

Parameters
int steps

indicates the number of injected move steps into the system. Steps are injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.

Returns
boolean

true if successful

swipeRight

public boolean swipeRight(int steps)

Performs the swipe right action on the UiObject. The swipe gesture can be performed over any surface. The targeted UI element does not need to be scrollable. See also:

Parameters
int steps

indicates the number of injected move steps into the system. Steps are injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.

Returns
boolean

true if successful

swipeUp

public boolean swipeUp(int steps)

Performs the swipe up action on the UiObject. See also:

Parameters
int steps

indicates the number of injected move steps into the system. Steps are injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.

Returns
boolean

true of successful

waitForExists

public boolean waitForExists(long timeout)

Waits a specified length of time for a view to become visible. This method waits until the view becomes visible on the display, or until the timeout has elapsed. You can use this method in situations where the content that you want to select is not immediately displayed.

Parameters
long timeout

the amount of time to wait (in milliseconds)

Returns
boolean

true if the view is displayed, else false if timeout elapsed while waiting

waitUntilGone

public boolean waitUntilGone(long timeout)

Waits a specified length of time for a view to become undetectable. This method waits until a view is no longer matchable, or until the timeout has elapsed. A view becomes undetectable when the UiSelector of the object is unable to find a match because the element has either changed its state or is no longer displayed. You can use this method when attempting to wait for some long operation to compete, such as downloading a large file or connecting to a remote server.

Parameters
long timeout

time to wait (in milliseconds)

Returns
boolean

true if the element is gone before timeout elapsed, else false if timeout elapsed but a matching element is still found.

Protected methods

findAccessibilityNodeInfo

protected @Nullable AccessibilityNodeInfo findAccessibilityNodeInfo(long timeout)

Finds a matching UI element in the accessibility hierarchy, by using the selector for this UiObject.

Parameters
long timeout

in milliseconds

Returns
@Nullable AccessibilityNodeInfo

AccessibilityNodeInfo if found else null