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
const Int
const Int
const Long

This property is deprecated.

use setScrollAcknowledgmentTimeout
const Long
const Long

This property is deprecated.

use setWaitForSelectorTimeout
const Long

Public constructors
UiObject(selector: UiSelector!)

This function is deprecated.

Use findObject instead.

Public functions
Unit

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(destObj: UiObject, steps: Int)

Drags this object to a destination UiObject.
Boolean
dragTo(destX: Int, destY: Int, steps: Int)

Drags this object to arbitrary coordinates.
Boolean

Check if view exists.
Rect

Returns the view's bounds property.
UiObject
getChild(selector: UiSelector)

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

Counts the child views immediately under the present UiObject.
String

Retrieves the className property of the UI element.
String

Reads the content_desc property of the UI element
UiObject

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

Reads the view's package property
UiSelector

Debugging helper.
String

Reads the text property of the UI element
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

Performs a multi-touch gesture.
Boolean
performTwoPointerGesture(
    startPoint1: Point,
    startPoint2: Point,
    endPoint1: Point,
    endPoint2: Point,
    steps: Int
)

Generates a two-pointer gesture with arbitrary starting and ending points.
Boolean
pinchIn(percent: Int, steps: Int)

Performs a two-pointer gesture, where each pointer moves diagonally toward the other, from the edges to the center of this UiObject .
Boolean
pinchOut(percent: Int, steps: Int)

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(text: String?)

Sets the text in an editable field, after clearing the field's content.
Boolean
swipeDown(steps: Int)

Performs the swipe down action on the UiObject.
Boolean
swipeLeft(steps: Int)

Performs the swipe left action on the UiObject.
Boolean
swipeRight(steps: Int)

Performs the swipe right action on the UiObject.
Boolean
swipeUp(steps: Int)

Performs the swipe up action on the UiObject.
Boolean
waitForExists(timeout: Long)

Waits a specified length of time for a view to become visible.
Boolean
waitUntilGone(timeout: Long)

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

Protected functions
AccessibilityNodeInfo?

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

Constants

FINGER_TOUCH_HALF_WIDTH

Added in 2.2.0
protected const val FINGER_TOUCH_HALF_WIDTH = 20: Int

SWIPE_MARGIN_LIMIT

Added in 2.2.0
protected const val SWIPE_MARGIN_LIMIT = 5: Int

WAIT_FOR_EVENT_TMEOUT

Added in 2.2.0
Deprecated in 2.2.0
protected const val WAIT_FOR_EVENT_TMEOUT = 3000: Long

WAIT_FOR_SELECTOR_POLL

Added in 2.2.0
protected const val WAIT_FOR_SELECTOR_POLL = 1000: Long

WAIT_FOR_SELECTOR_TIMEOUT

Added in 2.2.0
Deprecated in 2.2.0
protected const val WAIT_FOR_SELECTOR_TIMEOUT = 10000: Long

WAIT_FOR_WINDOW_TMEOUT

Added in 2.2.0
protected const val WAIT_FOR_WINDOW_TMEOUT = 5500: Long

Public constructors

UiObject

Added in 2.2.0
Deprecated in 2.2.0
UiObject(selector: UiSelector!)

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

Parameters
selector: UiSelector!

Public functions

clearTextField

Added in 2.2.0
fun clearTextField(): Unit

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
androidx.test.uiautomator.UiObjectNotFoundException

click

Added in 2.2.0
fun click(): Boolean

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
Throws
androidx.test.uiautomator.UiObjectNotFoundException

clickAndWaitForNewWindow

Added in 2.2.0
fun clickAndWaitForNewWindow(): Boolean

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
Throws
androidx.test.uiautomator.UiObjectNotFoundException

clickAndWaitForNewWindow

Added in 2.2.0
fun clickAndWaitForNewWindow(timeout: Long): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

clickBottomRight

Added in 2.2.0
fun clickBottomRight(): Boolean

Clicks the bottom and right corner of the UI element

Returns
Boolean

true on success
Throws
androidx.test.uiautomator.UiObjectNotFoundException

clickTopLeft

Added in 2.2.0
fun clickTopLeft(): Boolean

Clicks the top and left corner of the UI element

Returns
Boolean

true on success
Throws
androidx.test.uiautomator.UiObjectNotFoundException

dragTo

Added in 2.2.0
fun dragTo(destObj: UiObject, steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

dragTo

Added in 2.2.0
fun dragTo(destX: Int, destY: Int, steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

exists

Added in 2.2.0
fun exists(): Boolean

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

Added in 2.2.0
fun getBounds(): Rect

Returns the view's bounds property. See getVisibleBounds

Returns
Rect

Rect
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChild

Added in 2.2.0
fun getChild(selector: UiSelector): UiObject

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
androidx.test.uiautomator.UiObjectNotFoundException

getChildCount

Added in 2.2.0
fun getChildCount(): Int

Counts the child views immediately under the present UiObject.

Returns
Int

the count of child views.
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getClassName

Added in 2.2.0
fun getClassName(): String

Retrieves the className property of the UI element.

Returns
String

class name of the current node represented by this UiObject
Throws
androidx.test.uiautomator.UiObjectNotFoundException

if no match was found

getContentDescription

Added in 2.2.0
fun getContentDescription(): String

Reads the content_desc property of the UI element

Returns
String

value of node attribute "content_desc"
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getFromParent

Added in 2.2.0
fun getFromParent(selector: UiSelector): UiObject

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
androidx.test.uiautomator.UiObjectNotFoundException

getPackageName

Added in 2.2.0
fun getPackageName(): String

Reads the view's package property

Returns
String

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getSelector

Added in 2.2.0
fun getSelector(): UiSelector

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

Added in 2.2.0
fun getText(): String

Reads the text property of the UI element

Returns
String

text value of the current node represented by this UiObject
Throws
androidx.test.uiautomator.UiObjectNotFoundException

if no match could be found

getVisibleBounds

Added in 2.2.0
fun getVisibleBounds(): Rect

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
androidx.test.uiautomator.UiObjectNotFoundException
See also
getBounds

isCheckable

Added in 2.2.0
fun isCheckable(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isChecked

Added in 2.2.0
fun isChecked(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isClickable

Added in 2.2.0
fun isClickable(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isEnabled

Added in 2.2.0
fun isEnabled(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isFocusable

Added in 2.2.0
fun isFocusable(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isFocused

Added in 2.2.0
fun isFocused(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isLongClickable

Added in 2.2.0
fun isLongClickable(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isScrollable

Added in 2.2.0
fun isScrollable(): Boolean

Check if the view's scrollable property is currently true

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

isSelected

Added in 2.2.0
fun isSelected(): Boolean

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

Returns
Boolean

true if it is else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

longClick

Added in 2.2.0
fun longClick(): Boolean

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

Returns
Boolean

true if operation was successful
Throws
androidx.test.uiautomator.UiObjectNotFoundException

longClickBottomRight

Added in 2.2.0
fun longClickBottomRight(): Boolean

Long clicks bottom and right corner of the UI element

Returns
Boolean

true if operation was successful
Throws
androidx.test.uiautomator.UiObjectNotFoundException

longClickTopLeft

Added in 2.2.0
fun longClickTopLeft(): Boolean

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

Returns
Boolean

true if operation was successful
Throws
androidx.test.uiautomator.UiObjectNotFoundException

performMultiPointerGesture

fun performMultiPointerGesture(
    touches: Array<Array<MotionEvent.PointerCoords!>!>
): Boolean

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
touches: Array<Array<MotionEvent.PointerCoords!>!>

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

Added in 2.2.0
fun performTwoPointerGesture(
    startPoint1: Point,
    startPoint2: Point,
    endPoint1: Point,
    endPoint2: Point,
    steps: Int
): Boolean

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

Added in 2.2.0
fun pinchIn(percent: Int, steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

pinchOut

Added in 2.2.0
fun pinchOut(percent: Int, steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

setText

Added in 2.2.0
fun setText(text: String?): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

swipeDown

Added in 2.2.0
fun swipeDown(steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

swipeLeft

Added in 2.2.0
fun swipeLeft(steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

swipeRight

Added in 2.2.0
fun swipeRight(steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

swipeUp

Added in 2.2.0
fun swipeUp(steps: Int): Boolean

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
androidx.test.uiautomator.UiObjectNotFoundException

waitForExists

Added in 2.2.0
fun waitForExists(timeout: Long): Boolean

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

Added in 2.2.0
fun waitUntilGone(timeout: Long): Boolean

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 functions

findAccessibilityNodeInfo

Added in 2.2.0
protected fun findAccessibilityNodeInfo(timeout: Long): AccessibilityNodeInfo?

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