UiScrollable

Artifact: androidx.test.uiautomator:uiautomator

View Source

Added in 2.2.0

---

Kotlin |Java

class UiScrollable : UiCollection

kotlin.Any
↳	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
UiScrollable(container: UiSelector) Constructor.

Public functions
Boolean	flingBackward() Performs a backwards fling action with the default number of fling steps (5).
Boolean	flingForward() Performs a forward fling with the default number of fling steps (5).
Boolean	flingToBeginning(maxSwipes: Int) Performs a fling gesture to reach the beginning of a scrollable layout element.
Boolean	flingToEnd(maxSwipes: Int) Performs a fling gesture to reach the end of a scrollable layout element.
UiObject	getChildByDescription(childPattern: UiSelector, text: String) Searches for a child element in the present scrollable container.
UiObject	getChildByDescription(     childPattern: UiSelector,     text: String,     allowScrollSearch: Boolean ) Searches for a child element in the present scrollable container.
UiObject	getChildByInstance(childPattern: UiSelector, instance: Int) Searches for a child element in the present scrollable container that matches the selector you provided.
UiObject	getChildByText(childPattern: UiSelector, text: String) Searches for a child element in the present scrollable container.
UiObject	getChildByText(     childPattern: UiSelector,     text: String,     allowScrollSearch: Boolean ) Searches for a child element in the present scrollable container.
Int	getMaxSearchSwipes() Gets the maximum number of scrolls allowed when performing a scroll action in search of a child element.
Double	getSwipeDeadZonePercentage() Returns the percentage of a widget's size that's considered as a no-touch zone when swiping.
Boolean	scrollBackward() Performs a backward scroll with the default number of scroll steps (55).
Boolean	scrollBackward(steps: Int) Performs a backward scroll.
Boolean	scrollDescriptionIntoView(text: String) Performs a forward scroll action on the scrollable layout element until the content-description is found, or until swipe attempts have been exhausted.
Boolean	scrollForward() Performs a forward scroll with the default number of scroll steps (55).
Boolean	scrollForward(steps: Int) Performs a forward scroll.
Boolean	scrollIntoView(obj: UiObject) Perform a forward scroll action to move through the scrollable layout element until a visible item that matches the UiObject is found.
Boolean	scrollIntoView(selector: UiSelector) Perform a scroll forward action to move through the scrollable layout element until a visible item that matches the selector is found.
Boolean	scrollTextIntoView(text: String) 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(maxSwipes: Int) Scrolls to the beginning of a scrollable layout element.
Boolean	scrollToBeginning(maxSwipes: Int, steps: Int) Scrolls to the beginning of a scrollable layout element.
Boolean	scrollToEnd(maxSwipes: Int) Scrolls to the end of a scrollable layout element.
Boolean	scrollToEnd(maxSwipes: Int, steps: Int) Scrolls to the end of a scrollable layout element.
UiScrollable	setAsHorizontalList() Set the direction of swipes to be horizontal when performing scroll actions.
UiScrollable	setAsVerticalList() Set the direction of swipes to be vertical when performing scroll actions.
UiScrollable	setMaxSearchSwipes(swipes: Int) Sets the maximum number of scrolls allowed when performing a scroll action in search of a child element.
UiScrollable	setSwipeDeadZonePercentage(swipeDeadZonePercentage: Double) Sets the percentage of a widget's size that's considered as no-touch zone when swiping.

Protected functions
Boolean	exists(selector: UiSelector) Used privately when performing swipe searches to decide if an element has become visible or not.

Inherited Constants

From androidx.test.uiautomator.UiObject const Int FINGER_TOUCH_HALF_WIDTH = 20 const Int SWIPE_MARGIN_LIMIT = 5 const Long WAIT_FOR_EVENT_TMEOUT = 3000 This property is deprecated. use setScrollAcknowledgmentTimeout const Long WAIT_FOR_SELECTOR_POLL = 1000 const Long WAIT_FOR_SELECTOR_TIMEOUT = 10000 This property is deprecated. use setWaitForSelectorTimeout const Long WAIT_FOR_WINDOW_TMEOUT = 5500

Inherited functions
From androidx.test.uiautomator.UiCollection Int getChildCount(childPattern: UiSelector) Counts child UI element instances matching the childPattern argument.
From androidx.test.uiautomator.UiObject Unit 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(timeout: Long) 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(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 exists() Check if view exists. AccessibilityNodeInfo? findAccessibilityNodeInfo(timeout: Long) Finds a matching UI element in the accessibility hierarchy, by using the selector for this UiObject. Rect getBounds() 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 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(selector: UiSelector) 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 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(     touches: Array<Array<MotionEvent.PointerCoords!>!> ) 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.

Public constructors

UiScrollable

Added in 2.2.0

UiScrollable(container: UiSelector)

Constructor.

Parameters
container: UiSelector	a UiSelector selector to identify the scrollable layout element.

Public functions

flingBackward

Added in 2.2.0

fun flingBackward(): Boolean

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

fun flingForward(): Boolean

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

fun flingToBeginning(maxSwipes: Int): Boolean

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
maxSwipes: Int	maximum number of flings allowed

Returns
Boolean	true if beginning reached within maxSwipes

Throws
androidx.test.uiautomator.UiObjectNotFoundException

flingToEnd

Added in 2.2.0

fun flingToEnd(maxSwipes: Int): Boolean

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
maxSwipes: Int	maximum number of flings allowed

Returns
Boolean	true if end reached within maxSwipes

Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByDescription

fun getChildByDescription(childPattern: UiSelector, text: String): UiObject

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
childPattern: UiSelector	UiSelector for a child in a scollable layout element
text: String	Content-description to find in the children of the childPattern match

Returns
UiObject	UiObject representing the child element that matches the search conditions

Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByDescription

Added in 2.2.0

fun getChildByDescription(
    childPattern: UiSelector,
    text: String,
    allowScrollSearch: Boolean
): UiObject

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
childPattern: UiSelector	UiSelector for a child in a scollable layout element
text: String	Content-description to find in the children of the childPattern match (may be a partial match)
allowScrollSearch: Boolean	set to true if scrolling is allowed

Returns
UiObject	UiObject representing the child element that matches the search conditions

Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByInstance

fun getChildByInstance(childPattern: UiSelector, instance: Int): UiObject

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
childPattern: UiSelector	UiSelector for a child in a scollable layout element
instance: Int	int number representing the occurance of a childPattern match

Returns
UiObject	UiObject representing the child element that matches the search conditions

Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByText

fun getChildByText(childPattern: UiSelector, text: String): UiObject

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
childPattern: UiSelector	UiSelector selector for a child in a scrollable layout element
text: String	String to find in the children of the childPattern match

Returns
UiObject	UiObject representing the child element that matches the search conditions

Throws
androidx.test.uiautomator.UiObjectNotFoundException

getChildByText

Added in 2.2.0

fun getChildByText(
    childPattern: UiSelector,
    text: String,
    allowScrollSearch: Boolean
): UiObject

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
childPattern: UiSelector	UiSelector selector for a child in a scrollable layout element
text: String	String to find in the children of the childPattern match
allowScrollSearch: Boolean	set to true if scrolling is allowed

Returns
UiObject	UiObject representing the child element that matches the search conditions

Throws
androidx.test.uiautomator.UiObjectNotFoundException

getMaxSearchSwipes

Added in 2.2.0

fun getMaxSearchSwipes(): Int

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

fun getSwipeDeadZonePercentage(): Double

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

fun scrollBackward(): Boolean

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

fun scrollBackward(steps: Int): Boolean

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
steps: Int	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

fun scrollDescriptionIntoView(text: String): Boolean

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
text: String	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

fun scrollForward(): Boolean

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

fun scrollForward(steps: Int): Boolean

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
steps: Int	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

fun scrollIntoView(obj: UiObject): Boolean

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

Parameters
obj: UiObject	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

fun scrollIntoView(selector: UiSelector): Boolean

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
selector: UiSelector	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

fun scrollTextIntoView(text: String): 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. See setMaxSearchSwipes

Parameters
text: String	test to look for

Returns
Boolean	true if item is found; else, false

Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollToBeginning

Added in 2.2.0

fun scrollToBeginning(maxSwipes: Int): Boolean

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
maxSwipes: Int	maximum number of scrolls allowed

Returns
Boolean	true if beginning reached within maxSwipes

Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollToBeginning

Added in 2.2.0

fun scrollToBeginning(maxSwipes: Int, steps: Int): Boolean

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
maxSwipes: Int	maximum number of scrolls allowed
steps: Int	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

fun scrollToEnd(maxSwipes: Int): Boolean

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
maxSwipes: Int	maximum number of scrolls allowed

Returns
Boolean	true if end reached within maxSwipes

Throws
androidx.test.uiautomator.UiObjectNotFoundException

scrollToEnd

Added in 2.2.0

fun scrollToEnd(maxSwipes: Int, steps: Int): Boolean

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
maxSwipes: Int	maximum number of scrolls allowed
steps: Int	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

fun setAsHorizontalList(): UiScrollable

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

Returns
UiScrollable	reference to itself

setAsVerticalList

Added in 2.2.0

fun setAsVerticalList(): UiScrollable

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

Returns
UiScrollable	reference to itself

setMaxSearchSwipes

Added in 2.2.0

fun setMaxSearchSwipes(swipes: Int): UiScrollable

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

Parameters
swipes: Int	the number of search swipes to perform until giving up

Returns
UiScrollable	reference to itself

setSwipeDeadZonePercentage

Added in 2.2.0

fun setSwipeDeadZonePercentage(swipeDeadZonePercentage: Double): UiScrollable

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
swipeDeadZonePercentage: Double	is a value between 0 and 1

Returns
UiScrollable	reference to itself

Protected functions

exists

Added in 2.2.0

protected fun exists(selector: UiSelector): Boolean

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

Parameters
selector: UiSelector

Returns
Boolean	true if found else false