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.
Constants | |
---|---|
int |
FINGER_TOUCH_HALF_WIDTH
|
int |
SWIPE_MARGIN_LIMIT
|
long |
WAIT_FOR_EVENT_TMEOUT
This constant is deprecated.
use |
long |
WAIT_FOR_SELECTOR_POLL
|
long |
WAIT_FOR_SELECTOR_TIMEOUT
This constant is deprecated.
use |
long |
WAIT_FOR_WINDOW_TMEOUT
|
Public constructors | |
---|---|
UiObject(UiSelector selector)
This constructor is deprecated.
Use |
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 |
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 |
String
|
getContentDescription()
Reads the |
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 |
final
UiSelector
|
getSelector()
Debugging helper. |
String
|
getText()
Reads the |
Rect
|
getVisibleBounds()
Returns the visible bounds of the view. |
boolean
|
isCheckable()
Checks if the UI element's |
boolean
|
isChecked()
Check if the UI element's |
boolean
|
isClickable()
Checks if the UI element's |
boolean
|
isEnabled()
Checks if the UI element's |
boolean
|
isFocusable()
Check if the UI element's |
boolean
|
isFocused()
Check if the UI element's |
boolean
|
isLongClickable()
Check if the view's |
boolean
|
isScrollable()
Check if the view's |
boolean
|
isSelected()
Checks if the UI element's |
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
|
int FINGER_TOUCH_HALF_WIDTH
Constant Value: 20 (0x00000014)
int SWIPE_MARGIN_LIMIT
Constant Value: 5 (0x00000005)
long WAIT_FOR_EVENT_TMEOUT
This constant is deprecated.
use setScrollAcknowledgmentTimeout(long)
Constant Value: 3000 (0x0000000000000bb8)
long WAIT_FOR_SELECTOR_POLL
Constant Value: 1000 (0x00000000000003e8)
long WAIT_FOR_SELECTOR_TIMEOUT
This constant is deprecated.
use setWaitForSelectorTimeout(long)
Constant Value: 10000 (0x0000000000002710)
long WAIT_FOR_WINDOW_TMEOUT
Constant Value: 5500 (0x000000000000157c)
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.
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 |
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 |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
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 |
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:
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 |
boolean clickBottomRight ()
Clicks the bottom and right corner of the UI element
Returns | |
---|---|
boolean |
true on success |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean clickTopLeft ()
Clicks the top and left corner of the UI element
Returns | |
---|---|
boolean |
true on success |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
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 |
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 |
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 |
Rect getBounds ()
Returns the view's bounds
property. See getVisibleBounds()
Returns | |
---|---|
Rect |
Rect |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
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 |
int getChildCount ()
Counts the child views immediately under the present UiObject.
Returns | |
---|---|
int |
the count of child views. |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
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 |
String getContentDescription ()
Reads the content_desc
property of the UI element
Returns | |
---|---|
String |
value of node attribute "content_desc" |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
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 |
String getPackageName ()
Reads the view's package
property
Returns | |
---|---|
String |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
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 |
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 |
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:
boolean isCheckable ()
Checks if the UI element's checkable
property is currently true.
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean isChecked ()
Check if the UI element's checked
property is currently true
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
UiObjectNotFoundException |
boolean isClickable ()
Checks if the UI element's clickable
property is currently true.
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean isEnabled ()
Checks if the UI element's enabled
property is currently true.
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean isFocusable ()
Check if the UI element's focusable
property is currently true.
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean isFocused ()
Check if the UI element's focused
property is currently true
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean isLongClickable ()
Check if the view's long-clickable
property is currently true
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean isScrollable ()
Check if the view's scrollable
property is currently true
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean isSelected ()
Checks if the UI element's selected
property is currently true.
Returns | |
---|---|
boolean |
true if it is else false |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean longClick ()
Long clicks the center of the visible bounds of the UI element
Returns | |
---|---|
boolean |
true if operation was successful |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean longClickBottomRight ()
Long clicks bottom and right corner of the UI element
Returns | |
---|---|
boolean |
true if operation was successful |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
boolean longClickTopLeft ()
Long clicks on the top and left corner of the UI element
Returns | |
---|---|
boolean |
true if operation was successful |
Throws | |
---|---|
|
UiObjectNotFoundException |
UiObjectNotFoundException |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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 |