page.title=UiObject parent.title=uiautomator parent.link=index.html @jd:body

A UiObject is a representation of a user interface (UI) element. It is not in any way directly bound to a UI element as an object reference. A UiObject holds information to help it locate a matching UI element at runtime based on the UiSelector properties specified in its constructor. Since a UiObject is a representative for a UI element, it can be reused for different views with matching UI elements.

Summary

Public Constructors
UiObject(UiSelector selector)
Constructs a UiObject to represent a specific UI element matched by the specified UiSelector selector properties.
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(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 clickAndWaitForNewWindow()
See clickAndWaitForNewWindow(long) This method is intended to reliably wait for window transitions that would typically take longer than the usual default timeouts.
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 exists()
Check if UI element exists.
Rect getBounds()
Returns the UI element's bounds property.
UiObject getChild(UiSelector selector)
Creates a new UiObject representing a child UI element of the element currently represented by this UiObject.
int getChildCount()
Counts the child UI elements immediately under the UI element currently represented by this UiObject.
String getContentDescription()
Reads the content_desc property of the UI element
UiObject getFromParent(UiSelector selector)
Creates a new UiObject representing a child UI element from the parent element currently represented by this object.
String getPackageName()
Reads the UI element'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 UI element.
boolean isCheckable()
Check 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()
Check if the UI element's clickable property is currently true
boolean isEnabled()
Check 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 UI element's long-clickable property is currently true
boolean isScrollable()
Check if the UI element's scrollable property is currently true
boolean isSelected()
Check 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 setText(String text)
Sets the text in an editable field, after clearing the field's content.
boolean swipeDown(int steps)
Perform the action on the UI element that is represented by this object, Also see #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), #scrollForward().
boolean swipeLeft(int steps)
Perform the action on the UI element that is represented by this object.
boolean swipeRight(int steps)
Perform the action on the UI element that is represented by this object.
boolean swipeUp(int steps)
Perform the action on the UI element that is represented by this UiObject.
boolean waitForExists(long timeout)
Waits a specified length of time for a UI element to become visible.
boolean waitUntilGone(long timeout)
Waits a specified length of time for a UI element to become undetectable.
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public UiObject (UiSelector selector)

Constructs a UiObject to represent a specific UI element matched by the specified UiSelector selector properties.

Public Methods

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 first sets focus at the start edge of the field. The method then simulates a long-press to select the existing text, and deletes the selected text. If a "Select-All" option is displayed, the method will automatically attempt to use it to ensure full text selection. Note that it is possible that not all the text in the field is selected; for example, if the text contains separators such as spaces, slashes, at symbol etc. Also, not all editable fields support the long-press functionality.

Throws
UiObjectNotFoundException

public boolean click ()

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

Returns
  • true id successful else false
Throws
UiObjectNotFoundException

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

    public boolean clickAndWaitForNewWindow ()

    See clickAndWaitForNewWindow(long) This method is intended to reliably wait for window transitions that would typically take longer than the usual default timeouts.

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

    public boolean clickBottomRight ()

    Clicks the bottom and right corner of the UI element

    Returns
    • true on success
    Throws
    Exception
    UiObjectNotFoundException

    public boolean clickTopLeft ()

    Clicks the top and left corner of the UI element

    Returns
    • true on success
    Throws
    Exception
    UiObjectNotFoundException

    public boolean exists ()

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

    Returns
    • true if the UI element represented by this UiObject does exist

    public Rect getBounds ()

    Returns the UI element's bounds property. See getVisibleBounds()

    Returns
    • Rect
    Throws
    UiObjectNotFoundException

    public UiObject getChild (UiSelector selector)

    Creates a new UiObject representing a child UI element of the element currently represented by this UiObject.

    Parameters
    selector for UI element to match
    Returns
    • a new UiObject representing the matched UI element
    Throws
    UiObjectNotFoundException

    public int getChildCount ()

    Counts the child UI elements immediately under the UI element currently represented by this UiObject.

    Returns
    • the count of child UI elements.
    Throws
    UiObjectNotFoundException

    public String getContentDescription ()

    Reads the content_desc property of the UI element

    Returns
    • value of node attribute "content_desc"
    Throws
    UiObjectNotFoundException

    public UiObject getFromParent (UiSelector selector)

    Creates a new UiObject representing a child UI element from the parent element currently represented by this object. Essentially this is starting the search from the parent element and can also be used to find sibling UI elements to the one currently represented by this UiObject.

    Parameters
    selector for the UI element to match
    Returns
    • a new UiObject representing the matched UI element
    Throws
    UiObjectNotFoundException

    public String getPackageName ()

    Reads the UI element's package property

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public final UiSelector getSelector ()

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

    Returns

    public String getText ()

    Reads the text property of the UI element

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

    public Rect getVisibleBounds ()

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

    Returns
    • Rect
    Throws
    UiObjectNotFoundException
    UiObjectNotFoundException
    Since
    • Android API Level 17

    public boolean isCheckable ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isChecked ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isClickable ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isEnabled ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isFocusable ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isFocused ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isLongClickable ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isScrollable ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean isSelected ()

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

    Returns
    • true if it is else false
    Throws
    UiObjectNotFoundException

    public boolean longClick ()

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

    Returns
    • true if operation was successful
    Throws
    UiObjectNotFoundException

    public boolean longClickBottomRight ()

    Long clicks bottom and right corner of the UI element

    Returns
    • true if operation was successful
    Throws
    UiObjectNotFoundException

    public boolean longClickTopLeft ()

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

    Returns
    • true if operation was successful
    Throws
    UiObjectNotFoundException

    public 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 first simulates a click() on editable field to set focus. The method then clears the field's contents and 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.

    Parameters
    text string to set
    Returns
    • true if operation is successful
    Throws
    UiObjectNotFoundException

    public boolean swipeDown (int steps)

    Perform the action on the UI element that is represented by this object, Also see #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), #scrollForward(). This method will perform the swipe gesture over any surface. The targeted UI element does not need to have the attribute scrollable set to true for this operation to be performed.

    Parameters
    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
    • true if successful
    Throws
    UiObjectNotFoundException

    public boolean swipeLeft (int steps)

    Perform the action on the UI element that is represented by this object. Also see #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), #scrollForward(). This method will perform the swipe gesture over any surface. The targeted UI element does not need to have the attribute scrollable set to true for this operation to be performed.

    Parameters
    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
    • true if successful
    Throws
    UiObjectNotFoundException

    public boolean swipeRight (int steps)

    Perform the action on the UI element that is represented by this object. Also see #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), #scrollForward(). This method will perform the swipe gesture over any surface. The targeted UI element does not need to have the attribute scrollable set to true for this operation to be performed.

    Parameters
    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
    • true if successful
    Throws
    UiObjectNotFoundException

    public boolean swipeUp (int steps)

    Perform the action on the UI element that is represented by this UiObject. Also see #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), #scrollForward().

    Parameters
    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
    • true of successful
    Throws
    UiObjectNotFoundException

    public boolean waitForExists (long timeout)

    Waits a specified length of time for a UI element to become visible. This method waits until the UI element 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 the amount of time to wait (in milliseconds)
    Returns
    • true if the UI element is displayed, else false if timeout elapsed while waiting

    public boolean waitUntilGone (long timeout)

    Waits a specified length of time for a UI element to become undetectable. This method waits until a UI element is no longer matchable, or until the timeout has elapsed. A UI element 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 time to wait (in milliseconds)
    Returns
    • true if the element is gone before timeout elapsed, else false if timeout elapsed but a matching element is still found.