UiScrollable

public class UiScrollable extends UiCollection

java.lang.Object
   ↳ androidx.test.uiautomator.UiObject
     ↳ androidx.test.uiautomator.UiCollection
       ↳ androidx.test.uiautomator.UiScrollable

UiScrollable is a UiCollection and provides support for searching for items in scrollable layout elements. This class can be used with horizontally or vertically scrollable controls.

Summary

Public constructors

Constructor.

Public methods
boolean

Performs a backwards fling action with the default number of fling steps (5).
boolean

Performs a forward fling with the default number of fling steps (5).
boolean
flingToBeginning(int maxSwipes)

Performs a fling gesture to reach the beginning of a scrollable layout element.
boolean
flingToEnd(int maxSwipes)

Performs a fling gesture to reach the end of a scrollable layout element.
@NonNull UiObject
getChildByDescription(
    @NonNull UiSelector childPattern,
    @NonNull String text
)

Searches for a child element in the present scrollable container.
@NonNull UiObject
getChildByDescription(
    @NonNull UiSelector childPattern,
    @NonNull String text,
    boolean allowScrollSearch
)

Searches for a child element in the present scrollable container.
@NonNull UiObject
getChildByInstance(@NonNull UiSelector childPattern, int instance)

Searches for a child element in the present scrollable container that matches the selector you provided.
@NonNull UiObject

Searches for a child element in the present scrollable container.
@NonNull UiObject
getChildByText(
    @NonNull UiSelector childPattern,
    @NonNull String text,
    boolean allowScrollSearch
)

Searches for a child element in the present scrollable container.
int

Gets the maximum number of scrolls allowed when performing a scroll action in search of a child element.
double

Returns the percentage of a widget's size that's considered as a no-touch zone when swiping.
boolean

Performs a backward scroll with the default number of scroll steps (55).
boolean
scrollBackward(int steps)

Performs a backward scroll.
boolean

Performs a forward scroll action on the scrollable layout element until the content-description is found, or until swipe attempts have been exhausted.
boolean

Performs a forward scroll with the default number of scroll steps (55).
boolean
scrollForward(int steps)

Performs a forward scroll.
boolean

Perform a forward scroll action to move through the scrollable layout element until a visible item that matches the UiObject is found.
boolean

Perform a scroll forward action to move through the scrollable layout element until a visible item that matches the selector is found.
boolean

Performs a forward scroll action on the scrollable layout element until the text you provided is visible, or until swipe attempts have been exhausted.
boolean
scrollToBeginning(int maxSwipes)

Scrolls to the beginning of a scrollable layout element.
boolean
scrollToBeginning(int maxSwipes, int steps)

Scrolls to the beginning of a scrollable layout element.
boolean
scrollToEnd(int maxSwipes)

Scrolls to the end of a scrollable layout element.
boolean
scrollToEnd(int maxSwipes, int steps)

Scrolls to the end of a scrollable layout element.
@NonNull UiScrollable

Set the direction of swipes to be horizontal when performing scroll actions.
@NonNull UiScrollable

Set the direction of swipes to be vertical when performing scroll actions.
@NonNull UiScrollable
setMaxSearchSwipes(int swipes)

Sets the maximum number of scrolls allowed when performing a scroll action in search of a child element.
@NonNull UiScrollable
setSwipeDeadZonePercentage(double swipeDeadZonePercentage)

Sets the percentage of a widget's size that's considered as no-touch zone when swiping.

Protected methods
boolean

Used privately when performing swipe searches to decide if an element has become visible or not.

Inherited Constants
From androidx.test.uiautomator.UiObject
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

Inherited methods
From androidx.test.uiautomator.UiCollection
int

Counts child UI element instances matching the childPattern argument.
From androidx.test.uiautomator.UiObject
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.
@Nullable AccessibilityNodeInfo

Finds a matching UI element in the accessibility hierarchy, by using the selector for this UiObject.
@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.

Public constructors

UiScrollable

Added in 2.2.0
public UiScrollable(@NonNull UiSelector container)

Constructor.

Parameters
@NonNull UiSelector container

a UiSelector selector to identify the scrollable layout element.

Public methods

flingBackward

Added in 2.2.0
public boolean flingBackward()

Performs a backwards fling action with the default number of fling steps (5). If the swipe direction is set to vertical, then the swipe will be performed from top to bottom. If the swipe direction is set to horizontal, then the swipes will be performed from left to right. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
boolean

true if scrolled, and false if can't scroll anymore
Throws
androidx.test.uiautomator.UiObjectNotFoundException

flingForward

Added in 2.2.0
public boolean flingForward()

Performs a forward fling with the default number of fling steps (5). If the swipe direction is set to vertical, then the swipes will be performed from bottom to top. If the swipe direction is set to horizontal, then the swipes will be performed from right to left. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
boolean

true if scrolled, false if can't scroll anymore
Throws
androidx.test.uiautomator.UiObjectNotFoundException

flingToBeginning

Added in 2.2.0
public boolean flingToBeginning(int maxSwipes)

Performs a fling gesture to reach the beginning of a scrollable layout element. The beginning can be at the top-most edge in the case of vertical controls, or the left-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int maxSwipes

maximum number of flings allowed
Returns
boolean

true if beginning reached within maxSwipes
Throws
androidx.test.uiautomator.UiObjectNotFoundException

flingToEnd

Added in 2.2.0
public boolean flingToEnd(int maxSwipes)

Performs a fling gesture to reach the end of a scrollable layout element. The end can be at the bottom-most edge in the case of vertical controls, or the right-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int maxSwipes

maximum number of flings allowed
Returns
boolean

true if end reached within maxSwipes
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByDescription

public @NonNull UiObject getChildByDescription(
    @NonNull UiSelector childPattern,
    @NonNull String text
)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the content-description in its children elements. If both search conditions are fulfilled, the method returns a UiObject representing the element matching the selector (not the child element in its subhierarchy containing the content-description). By default, this method performs a scroll search. See getChildByDescription

Parameters
@NonNull UiSelector childPattern

UiSelector for a child in a scollable layout element
@NonNull String text

Content-description to find in the children of the childPattern match
Returns
@NonNull UiObject

UiObject representing the child element that matches the search conditions
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByDescription

Added in 2.2.0
public @NonNull UiObject getChildByDescription(
    @NonNull UiSelector childPattern,
    @NonNull String text,
    boolean allowScrollSearch
)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the content-description in its children elements. If both search conditions are fulfilled, the method returns a UiObject representing the element matching the selector (not the child element in its subhierarchy containing the content-description).

Parameters
@NonNull UiSelector childPattern

UiSelector for a child in a scollable layout element
@NonNull String text

Content-description to find in the children of the childPattern match (may be a partial match)
boolean allowScrollSearch

set to true if scrolling is allowed
Returns
@NonNull UiObject

UiObject representing the child element that matches the search conditions
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByInstance

public @NonNull UiObject getChildByInstance(@NonNull UiSelector childPattern, int instance)

Searches for a child element in the present scrollable container that matches the selector you provided. The search is performed without scrolling and only on visible elements.

Parameters
@NonNull UiSelector childPattern

UiSelector for a child in a scollable layout element
int instance

int number representing the occurance of a childPattern match
Returns
@NonNull UiObject

UiObject representing the child element that matches the search conditions
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByText

public @NonNull UiObject getChildByText(@NonNull UiSelector childPattern, @NonNull String text)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the text in its children elements. If both search conditions are fulfilled, the method returns a UiObject representing the element matching the selector (not the child element in its subhierarchy containing the text). By default, this method performs a scroll search. See getChildByText

Parameters
@NonNull UiSelector childPattern

UiSelector selector for a child in a scrollable layout element
@NonNull String text

String to find in the children of the childPattern match
Returns
@NonNull UiObject

UiObject representing the child element that matches the search conditions
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByText

Added in 2.2.0
public @NonNull UiObject getChildByText(
    @NonNull UiSelector childPattern,
    @NonNull String text,
    boolean allowScrollSearch
)

Searches for a child element in the present scrollable container. The search first looks for a child element that matches the selector you provided, then looks for the text in its children elements. If both search conditions are fulfilled, the method returns a UiObject representing the element matching the selector (not the child element in its subhierarchy containing the text).

Parameters
@NonNull UiSelector childPattern

UiSelector selector for a child in a scrollable layout element
@NonNull String text

String to find in the children of the childPattern match
boolean allowScrollSearch

set to true if scrolling is allowed
Returns
@NonNull UiObject

UiObject representing the child element that matches the search conditions
Throws
androidx.test.uiautomator.UiObjectNotFoundException

getMaxSearchSwipes

Added in 2.2.0
public int getMaxSearchSwipes()

Gets the maximum number of scrolls allowed when performing a scroll action in search of a child element. See getChildByDescription and getChildByText.

Returns
int

max the number of search swipes to perform until giving up

getSwipeDeadZonePercentage

Added in 2.2.0
public double getSwipeDeadZonePercentage()

Returns the percentage of a widget's size that's considered as a no-touch zone when swiping. The no-touch zone is set as a percentage of a widget's total width or height, denoting a margin around the swipable area of the widget. Swipes must start and end inside this margin. This is important when the widget being swiped may not respond to the swipe if started at a point too near to the edge. The default is 10% from either edge.

Returns
double

a value between 0 and 1

scrollBackward

Added in 2.2.0
public boolean scrollBackward()

Performs a backward scroll with the default number of scroll steps (55). If the swipe direction is set to vertical, then the swipes will be performed from top to bottom. If the swipe direction is set to horizontal, then the swipes will be performed from left to right. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
boolean

true if scrolled, and false if can't scroll anymore
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollBackward

Added in 2.2.0
public boolean scrollBackward(int steps)

Performs a backward scroll. If the swipe direction is set to vertical, then the swipes will be performed from top to bottom. If the swipe direction is set to horizontal, then the swipes will be performed from left to right. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int steps

number of steps. Use this to control the speed of the scroll action.
Returns
boolean

true if scrolled, false if can't scroll anymore
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollDescriptionIntoView

Added in 2.2.0
public boolean scrollDescriptionIntoView(@NonNull String text)

Performs a forward scroll action on the scrollable layout element until the content-description is found, or until swipe attempts have been exhausted. See setMaxSearchSwipes

Parameters
@NonNull String text

content-description to find within the contents of this scrollable layout element.
Returns
boolean

true if item is found; else, false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollForward

Added in 2.2.0
public boolean scrollForward()

Performs a forward scroll with the default number of scroll steps (55). If the swipe direction is set to vertical, then the swipes will be performed from bottom to top. If the swipe direction is set to horizontal, then the swipes will be performed from right to left. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Returns
boolean

true if scrolled, false if can't scroll anymore
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollForward

Added in 2.2.0
public boolean scrollForward(int steps)

Performs a forward scroll. If the swipe direction is set to vertical, then the swipes will be performed from bottom to top. If the swipe direction is set to horizontal, then the swipes will be performed from right to left. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int steps

number of steps. Use this to control the speed of the scroll action
Returns
boolean

true if scrolled, false if can't scroll anymore
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollIntoView

Added in 2.2.0
public boolean scrollIntoView(@NonNull UiObject obj)

Perform a forward scroll action to move through the scrollable layout element until a visible item that matches the UiObject is found.

Parameters
@NonNull UiObject obj

UiObject
Returns
boolean

true if the item was found and now is in view else false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollIntoView

Added in 2.2.0
public boolean scrollIntoView(@NonNull UiSelector selector)

Perform a scroll forward action to move through the scrollable layout element until a visible item that matches the selector is found. See scrollDescriptionIntoView and scrollTextIntoView.

Parameters
@NonNull UiSelector selector

UiSelector selector
Returns
boolean

true if the item was found and now is in view; else, false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollTextIntoView

Added in 2.2.0
public boolean scrollTextIntoView(@NonNull String text)

Performs a forward scroll action on the scrollable layout element until the text you provided is visible, or until swipe attempts have been exhausted. See setMaxSearchSwipes

Parameters
@NonNull String text

test to look for
Returns
boolean

true if item is found; else, false
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollToBeginning

Added in 2.2.0
public boolean scrollToBeginning(int maxSwipes)

Scrolls to the beginning of a scrollable layout element. The beginning can be at the top-most edge in the case of vertical controls, or the left-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int maxSwipes

maximum number of scrolls allowed
Returns
boolean

true if beginning reached within maxSwipes
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollToBeginning

Added in 2.2.0
public boolean scrollToBeginning(int maxSwipes, int steps)

Scrolls to the beginning of a scrollable layout element. The beginning can be at the top-most edge in the case of vertical controls, or the left-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int maxSwipes

maximum number of scrolls allowed
int steps

use steps to control the speed, so that it may be a scroll, or fling
Returns
boolean

true if beginning reached within maxSwipes
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollToEnd

Added in 2.2.0
public boolean scrollToEnd(int maxSwipes)

Scrolls to the end of a scrollable layout element. The end can be at the bottom-most edge in the case of vertical controls, or the right-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int maxSwipes

maximum number of scrolls allowed
Returns
boolean

true if end reached within maxSwipes
Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollToEnd

Added in 2.2.0
public boolean scrollToEnd(int maxSwipes, int steps)

Scrolls to the end of a scrollable layout element. The end can be at the bottom-most edge in the case of vertical controls, or the right-most edge for horizontal controls. Make sure to take into account devices configured with right-to-left languages like Arabic and Hebrew.

Parameters
int maxSwipes

maximum number of scrolls allowed
int steps

use steps to control the speed, so that it may be a scroll, or fling
Returns
boolean

true if end reached within maxSwipes
Throws
androidx.test.uiautomator.UiObjectNotFoundException

setAsHorizontalList

Added in 2.2.0
public @NonNull UiScrollable setAsHorizontalList()

Set the direction of swipes to be horizontal when performing scroll actions.

Returns
@NonNull UiScrollable

reference to itself

setAsVerticalList

Added in 2.2.0
public @NonNull UiScrollable setAsVerticalList()

Set the direction of swipes to be vertical when performing scroll actions.

Returns
@NonNull UiScrollable

reference to itself

setMaxSearchSwipes

Added in 2.2.0
public @NonNull UiScrollable setMaxSearchSwipes(int swipes)

Sets the maximum number of scrolls allowed when performing a scroll action in search of a child element. See getChildByDescription and getChildByText.

Parameters
int swipes

the number of search swipes to perform until giving up
Returns
@NonNull UiScrollable

reference to itself

setSwipeDeadZonePercentage

Added in 2.2.0
public @NonNull UiScrollable setSwipeDeadZonePercentage(double swipeDeadZonePercentage)

Sets the percentage of a widget's size that's considered as no-touch zone when swiping. The no-touch zone is set as percentage of a widget's total width or height, denoting a margin around the swipable area of the widget. Swipes must always start and end inside this margin. This is important when the widget being swiped may not respond to the swipe if started at a point too near to the edge. The default is 10% from either edge.

Parameters
double swipeDeadZonePercentage

is a value between 0 and 1
Returns
@NonNull UiScrollable

reference to itself

Protected methods

exists

Added in 2.2.0
protected boolean exists(@NonNull UiSelector selector)

Used privately when performing swipe searches to decide if an element has become visible or not.

Parameters
@NonNull UiSelector selector
Returns
boolean

true if found else false