UiObject

public class UiObject
extends Object

java.lang.Object
   ↳ android.support.test.uiautomator.UiObject
Known Direct Subclasses
Known Indirect Subclasses

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

int FINGER_TOUCH_HALF_WIDTH

int SWIPE_MARGIN_LIMIT

long WAIT_FOR_EVENT_TMEOUT

This constant is deprecated. use setScrollAcknowledgmentTimeout(long)

long WAIT_FOR_SELECTOR_POLL

long WAIT_FOR_SELECTOR_TIMEOUT

This constant is deprecated. use setWaitForSelectorTimeout(long)

long WAIT_FOR_WINDOW_TMEOUT

Public constructors

UiObject(UiSelector selector)

This constructor is deprecated. Use findObject(UiSelector) instead. This version hides UiObject's dependency on UiDevice and is prone to misuse.

Public methods

void clearTextField()

Clears the existing text contents in an editable field.

boolean click()

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

boolean clickAndWaitForNewWindow()

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

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.

boolean clickBottomRight()

Clicks the bottom and right corner of the UI element

boolean clickTopLeft()

Clicks the top and left corner of the UI element

boolean dragTo(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 exists()

Check if view exists.

Rect getBounds()

Returns the view's bounds property.

UiObject getChild(UiSelector selector)

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

int getChildCount()

Counts the child views immediately under the present UiObject.

String getClassName()

Retrieves the className property of the UI element.

String getContentDescription()

Reads the content_desc property of the UI element

UiObject getFromParent(UiSelector selector)

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

String getPackageName()

Reads the view's package property

final UiSelector getSelector()

Debugging helper.

String getText()

Reads the text property of the UI element

Rect getVisibleBounds()

Returns the visible bounds of the view.

boolean isCheckable()

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

boolean isChecked()

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

boolean isClickable()

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

boolean isEnabled()

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

boolean isFocusable()

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

boolean isFocused()

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

boolean isLongClickable()

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

boolean isScrollable()

Check if the view's scrollable property is currently true

boolean isSelected()

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

boolean longClick()

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

boolean longClickBottomRight()

Long clicks bottom and right corner of the UI element

boolean longClickTopLeft()

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

boolean performMultiPointerGesture(PointerCoords... touches)

Performs a multi-touch gesture.

boolean performTwoPointerGesture(Point startPoint1, Point startPoint2, Point endPoint1, 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 setText(String text)

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

AccessibilityNodeInfo findAccessibilityNodeInfo(long timeout)

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

Inherited methods

From class java.lang.Object

Constants

FINGER_TOUCH_HALF_WIDTH

int FINGER_TOUCH_HALF_WIDTH

Constant Value: 20 (0x00000014)

SWIPE_MARGIN_LIMIT

int SWIPE_MARGIN_LIMIT

Constant Value: 5 (0x00000005)

WAIT_FOR_EVENT_TMEOUT

long WAIT_FOR_EVENT_TMEOUT

This constant is deprecated.
use setScrollAcknowledgmentTimeout(long)

Constant Value: 3000 (0x0000000000000bb8)

WAIT_FOR_SELECTOR_POLL

long WAIT_FOR_SELECTOR_POLL

Constant Value: 1000 (0x00000000000003e8)

WAIT_FOR_SELECTOR_TIMEOUT

long WAIT_FOR_SELECTOR_TIMEOUT

This constant is deprecated.
use setWaitForSelectorTimeout(long)

Constant Value: 10000 (0x0000000000002710)

WAIT_FOR_WINDOW_TMEOUT

long WAIT_FOR_WINDOW_TMEOUT

Constant Value: 5500 (0x000000000000157c)

Public constructors

UiObject

UiObject (UiSelector selector)

This constructor is deprecated.
Use findObject(UiSelector) instead. This version hides UiObject's dependency on UiDevice and is prone to misuse.

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

Public methods

clearTextField

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

Throws
UiObjectNotFoundException
UiObjectNotFoundException

click

boolean click ()

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

Returns
boolean true if successful else false
Throws
UiObjectNotFoundException
UiObjectNotFoundException

clickAndWaitForNewWindow

boolean clickAndWaitForNewWindow ()

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

Returns
boolean true if the event was triggered, else false
Throws
UiObjectNotFoundException
UiObjectNotFoundException

clickAndWaitForNewWindow

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
    timeout long: timeout before giving up on waiting for a new window
    Returns
    boolean true if the event was triggered, else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    clickBottomRight

    boolean clickBottomRight ()

    Clicks the bottom and right corner of the UI element

    Returns
    boolean true on success
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    clickTopLeft

    boolean clickTopLeft ()

    Clicks the top and left corner of the UI element

    Returns
    boolean true on success
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    dragTo

    boolean dragTo (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
    destObj UiObject: the destination UiObject.
    steps int: usually 40 steps. You can increase or decrease the steps to change the speed.
    Returns
    boolean true if successful
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    dragTo

    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
    destX int: the X-axis coordinate.
    destY int: the Y-axis coordinate.
    steps int: usually 40 steps. You can increase or decrease the steps to change the speed.
    Returns
    boolean true if successful
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    exists

    boolean exists ()

    Check if view exists. This methods performs a waitForExists(long) 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(long).

    Returns
    boolean true if the view represented by this UiObject does exist

    getBounds

    Rect getBounds ()

    Returns the view's bounds property. See getVisibleBounds()

    Returns
    Rect Rect
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    getChild

    UiObject getChild (UiSelector selector)

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

    Parameters
    selector UiSelector: for child view to match
    Returns
    UiObject a new UiObject representing the child view
    Throws
    UiObjectNotFoundException

    getChildCount

    int getChildCount ()

    Counts the child views immediately under the present UiObject.

    Returns
    int the count of child views.
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    getClassName

    String getClassName ()

    Retrieves the className property of the UI element.

    Returns
    String class name of the current node represented by this UiObject
    Throws
    UiObjectNotFoundException if no match was found

    getContentDescription

    String getContentDescription ()

    Reads the content_desc property of the UI element

    Returns
    String value of node attribute "content_desc"
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    getFromParent

    UiObject getFromParent (UiSelector selector)

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

    Parameters
    selector UiSelector: for a sibling view or children of the sibling view
    Returns
    UiObject a new UiObject representing the matched view
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    getPackageName

    String getPackageName ()

    Reads the view's package property

    Returns
    String true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    getSelector

    UiSelector getSelector ()

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

    Returns
    UiSelector UiSelector

    getText

    String getText ()

    Reads the text property of the UI element

    Returns
    String text value of the current node represented by this UiObject
    Throws
    UiObjectNotFoundException if no match could be found

    getVisibleBounds

    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
    Rect Rect
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    See also:

    isCheckable

    boolean isCheckable ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    isChecked

    boolean isChecked ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException

    isClickable

    boolean isClickable ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    isEnabled

    boolean isEnabled ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    isFocusable

    boolean isFocusable ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    isFocused

    boolean isFocused ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    isLongClickable

    boolean isLongClickable ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    isScrollable

    boolean isScrollable ()

    Check if the view's scrollable property is currently true

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    isSelected

    boolean isSelected ()

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

    Returns
    boolean true if it is else false
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    longClick

    boolean longClick ()

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

    Returns
    boolean true if operation was successful
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    longClickBottomRight

    boolean longClickBottomRight ()

    Long clicks bottom and right corner of the UI element

    Returns
    boolean true if operation was successful
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    longClickTopLeft

    boolean longClickTopLeft ()

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

    Returns
    boolean true if operation was successful
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    performMultiPointerGesture

    boolean performMultiPointerGesture (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 MotionEvent.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
    touches PointerCoords: represents the pointers' paths. Each MotionEvent.PointerCoords array represents a different pointer. Each MotionEvent.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

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

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

    Parameters
    startPoint1 Point: start point of pointer 1
    startPoint2 Point: start point of pointer 2
    endPoint1 Point: end point of pointer 1
    endPoint2 Point: end point of pointer 2
    steps int: 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

    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
    percent int: percentage of the object's diagonal length for the pinch gesture
    steps int: 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
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    pinchOut

    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
    percent int: percentage of the object's diagonal length for the pinch gesture
    steps int: 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
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    setText

    boolean setText (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
    text String: string to set
    Returns
    boolean true if operation is successful
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    swipeDown

    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
    steps int: 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
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    swipeLeft

    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
    steps int: 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
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    swipeRight

    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
    steps int: 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
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    swipeUp

    boolean swipeUp (int steps)

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

    Parameters
    steps int: 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
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException

    waitForExists

    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
    timeout long: the amount of time to wait (in milliseconds)
    Returns
    boolean true if the view is displayed, else false if timeout elapsed while waiting

    waitUntilGone

    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
    timeout long: 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

    AccessibilityNodeInfo findAccessibilityNodeInfo (long timeout)

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

    Parameters
    timeout long: in milliseconds
    Returns
    AccessibilityNodeInfo AccessibilityNodeInfo if found else null