class BySelector


A BySelector specifies criteria for matching UI elements during a call to findObject.

Summary

Public functions

BySelector
checkable(isCheckable: Boolean)

Sets the search criteria to match elements that are checkable or not checkable.

BySelector
checked(isChecked: Boolean)

Sets the search criteria to match elements that are checked or unchecked.

BySelector
clazz(className: Pattern)

Sets the class name criteria for matching.

BySelector
clazz(className: String)

Sets the class name criteria for matching.

BySelector
clazz(clazz: Class)

Sets the class name criteria for matching.

BySelector
clazz(packageName: String, className: String)

Sets the class name criteria for matching.

BySelector
clickable(isClickable: Boolean)

Sets the search criteria to match elements that are clickable or not clickable.

BySelector
depth(exactDepth: Int)

Sets the search criteria to match elements that are at a certain depth.

BySelector
depth(min: Int, max: Int)

Sets the search criteria to match elements that are in a range of depths.

BySelector
desc(contentDescription: Pattern)

Sets the content description criteria for matching.

BySelector
desc(contentDescription: String)

Sets the content description criteria for matching.

BySelector
descContains(substring: String)

Sets the content description criteria for matching.

BySelector

Sets the content description criteria for matching.

BySelector

Sets the content description criteria for matching.

BySelector
@RequiresApi(value = 30)
displayId(displayId: Int)

Adds a display ID selector criteria for matching.

BySelector
enabled(isEnabled: Boolean)

Sets the search criteria to match elements that are enabled or disabled.

BySelector
focusable(isFocusable: Boolean)

Sets the search criteria to match elements that are focusable or not focusable.

BySelector
focused(isFocused: Boolean)

Sets the search criteria to match elements that are focused or unfocused.

BySelector
hasAncestor(ancestorSelector: BySelector)

Adds an ancestor selector criteria for matching.

BySelector
hasAncestor(
    ancestorSelector: BySelector,
    maxAncestorDistance: @IntRange(from = 1) Int
)

Adds an ancestor selector criteria for matching.

BySelector
hasChild(childSelector: BySelector)

Adds a child selector criteria for matching.

BySelector
hasDescendant(descendantSelector: BySelector)

Adds a descendant selector criteria for matching.

BySelector
hasDescendant(descendantSelector: BySelector, maxDepth: Int)

Adds a descendant selector criteria for matching.

BySelector
hasParent(parentSelector: BySelector)

Adds a parent selector criteria for matching.

BySelector
@RequiresApi(value = 26)
hint(hintValue: Pattern)

Sets the hint value criteria for matching.

BySelector
@RequiresApi(value = 26)
hint(hintValue: String)

Sets the hint value criteria for matching.

BySelector
@RequiresApi(value = 26)
hintContains(substring: String)

Sets the hint value criteria for matching.

BySelector
@RequiresApi(value = 26)
hintEndsWith(suffix: String)

Sets the hint value criteria for matching.

BySelector
@RequiresApi(value = 26)
hintStartsWith(prefix: String)

Sets the hint value criteria for matching.

BySelector
longClickable(isLongClickable: Boolean)

Sets the search criteria to match elements that are long clickable or not long clickable.

BySelector
maxDepth(max: Int)

Sets the search criteria to match elements that are no more than a certain depth.

BySelector
minDepth(min: Int)

Sets the search criteria to match elements that are at least a certain depth.

BySelector
pkg(applicationPackage: Pattern)

Sets the package name criteria for matching.

BySelector
pkg(applicationPackage: String)

Sets the application package name criteria for matching.

BySelector
res(resourceName: Pattern)

Sets the resource name criteria for matching.

BySelector
res(resourceName: String)

Sets the resource name criteria for matching.

BySelector
res(resourcePackage: String, resourceId: String)

Sets the resource name criteria for matching.

BySelector
scrollable(isScrollable: Boolean)

Sets the search criteria to match elements that are scrollable or not scrollable.

BySelector
selected(isSelected: Boolean)

Sets the search criteria to match elements that are selected or not selected.

BySelector
text(textValue: Pattern)

Sets the text value criteria for matching.

BySelector
text(textValue: String)

Sets the text value criteria for matching.

BySelector
textContains(substring: String)

Sets the text value criteria for matching.

BySelector

Sets the text value criteria for matching.

BySelector

Sets the text value criteria for matching.

String!

Returns a String representation of this BySelector.

Public functions

checkable

Added in 2.2.0
fun checkable(isCheckable: Boolean): BySelector

Sets the search criteria to match elements that are checkable or not checkable.

Parameters
isCheckable: Boolean

Whether to match elements that are checkable or elements that are not checkable.

Returns
BySelector

A reference to this BySelector.

checked

Added in 2.2.0
fun checked(isChecked: Boolean): BySelector

Sets the search criteria to match elements that are checked or unchecked.

Parameters
isChecked: Boolean

Whether to match elements that are checked or elements that are unchecked.

Returns
BySelector

A reference to this BySelector.

clazz

Added in 2.2.0
fun clazz(className: Pattern): BySelector

Sets the class name criteria for matching. A UI element will be considered a match if its full class name matches the classNamePattern and all other criteria for this selector are met.

Parameters
className: Pattern

The Pattern to be used for matching.

Returns
BySelector

A reference to this BySelector.

clazz

Added in 2.2.0
fun clazz(className: String): BySelector

Sets the class name criteria for matching. A UI element will be considered a match if its class name exactly matches the className parameter and all other criteria for this selector are met. If className starts with a period, it is assumed to be in the android.widget package.

Parameters
className: String

The full class name value to match.

Returns
BySelector

A reference to this BySelector.

clazz

Added in 2.2.0
fun clazz(clazz: Class): BySelector

Sets the class name criteria for matching. A UI element will be considered a match if its class name matches clazz and all other criteria for this selector are met.

Parameters
clazz: Class

The class to match.

Returns
BySelector

A reference to this BySelector

clazz

Added in 2.2.0
fun clazz(packageName: String, className: String): BySelector

Sets the class name criteria for matching. A UI element will be considered a match if its package and class name exactly match the packageName and className parameters and all other criteria for this selector are met.

Parameters
packageName: String

The package value to match.

className: String

The class name value to match.

Returns
BySelector

A reference to this BySelector.

clickable

Added in 2.2.0
fun clickable(isClickable: Boolean): BySelector

Sets the search criteria to match elements that are clickable or not clickable.

Parameters
isClickable: Boolean

Whether to match elements that are clickable or elements that are not clickable.

Returns
BySelector

A reference to this BySelector.

depth

Added in 2.2.0
fun depth(exactDepth: Int): BySelector

Sets the search criteria to match elements that are at a certain depth.

depth

Added in 2.2.0
fun depth(min: Int, max: Int): BySelector

Sets the search criteria to match elements that are in a range of depths.

desc

Added in 2.2.0
fun desc(contentDescription: Pattern): BySelector

Sets the content description criteria for matching. A UI element will be considered a match if its content description matches the contentDescriptionPattern and all other criteria for this selector are met.

Parameters
contentDescription: Pattern

The Pattern to be used for matching.

Returns
BySelector

A reference to this BySelector.

desc

Added in 2.2.0
fun desc(contentDescription: String): BySelector

Sets the content description criteria for matching. A UI element will be considered a match if its content description exactly matches the contentDescription parameter and all other criteria for this selector are met.

Parameters
contentDescription: String

The exact value to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

descContains

Added in 2.2.0
fun descContains(substring: String): BySelector

Sets the content description criteria for matching. A UI element will be considered a match if its content description contains the substring parameter and all other criteria for this selector are met.

Parameters
substring: String

The substring to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

descEndsWith

Added in 2.2.0
fun descEndsWith(suffix: String): BySelector

Sets the content description criteria for matching. A UI element will be considered a match if its content description ends with the suffix parameter and all other criteria for this selector are met.

Parameters
suffix: String

The suffix to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

descStartsWith

Added in 2.2.0
fun descStartsWith(prefix: String): BySelector

Sets the content description criteria for matching. A UI element will be considered a match if its content description starts with the prefix parameter and all other criteria for this selector are met.

Parameters
prefix: String

The prefix to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

displayId

Added in 2.3.0
@RequiresApi(value = 30)
fun displayId(displayId: Int): BySelector

Adds a display ID selector criteria for matching. A UI element will be considered a match if it is within the display with the ID of displayId and all other criteria for this selector are met.

Parameters
displayId: Int

The display ID to match. Use getDisplayId to get the ID.

Returns
BySelector

A reference to this BySelector.

enabled

Added in 2.2.0
fun enabled(isEnabled: Boolean): BySelector

Sets the search criteria to match elements that are enabled or disabled.

Parameters
isEnabled: Boolean

Whether to match elements that are enabled or elements that are disabled.

Returns
BySelector

A reference to this BySelector.

focusable

Added in 2.2.0
fun focusable(isFocusable: Boolean): BySelector

Sets the search criteria to match elements that are focusable or not focusable.

Parameters
isFocusable: Boolean

Whether to match elements that are focusable or elements that are not focusable.

Returns
BySelector

A reference to this BySelector.

focused

Added in 2.2.0
fun focused(isFocused: Boolean): BySelector

Sets the search criteria to match elements that are focused or unfocused.

Parameters
isFocused: Boolean

Whether to match elements that are focused or elements that are unfocused.

Returns
BySelector

A reference to this BySelector.

hasAncestor

Added in 2.3.0
fun hasAncestor(ancestorSelector: BySelector): BySelector

Adds an ancestor selector criteria for matching. A UI element will be considered a match if it has an ancestor element which matches the ancestorSelector and all other criteria for this selector are met.

Parameters
ancestorSelector: BySelector

The selector used to find a matching ancestor element.

Returns
BySelector

A reference to this BySelector.

hasAncestor

Added in 2.3.0
fun hasAncestor(
    ancestorSelector: BySelector,
    maxAncestorDistance: @IntRange(from = 1) Int
): BySelector

Adds an ancestor selector criteria for matching. A UI element will be considered a match if it has an ancestor element which matches the ancestorSelector and all other criteria for this selector are met.

Parameters
ancestorSelector: BySelector

The selector used to find a matching ancestor element.

maxAncestorDistance: @IntRange(from = 1) Int

The maximum distance between the element and its relevant ancestor in the view hierarchy, e.g. 1 only matches the parent element, 2 matches parent or grandparent.

Returns
BySelector

A reference to this BySelector.

hasChild

Added in 2.2.0
fun hasChild(childSelector: BySelector): BySelector

Adds a child selector criteria for matching. A UI element will be considered a match if it has a child element (direct descendant) which matches the childSelector and all other criteria for this selector are met. If specified more than once, matches must be found for all childSelectors.

Parameters
childSelector: BySelector

The selector used to find a matching child element.

Returns
BySelector

A reference to this BySelector.

Throws
java.lang.IllegalArgumentException

if the selector has a parent/ancestor selector

hasDescendant

Added in 2.2.0
fun hasDescendant(descendantSelector: BySelector): BySelector

Adds a descendant selector criteria for matching. A UI element will be considered a match if it has a descendant element which matches the descendantSelector and all other criteria for this selector are met. If specified more than once, matches must be found for all descendantSelectors.

Parameters
descendantSelector: BySelector

The selector used to find a matching descendant element.

Returns
BySelector

A reference to this BySelector.

Throws
java.lang.IllegalArgumentException

if the selector has a parent/ancestor selector

hasDescendant

Added in 2.2.0
fun hasDescendant(descendantSelector: BySelector, maxDepth: Int): BySelector

Adds a descendant selector criteria for matching. A UI element will be considered a match if it has a descendant element which matches the descendantSelector and all other criteria for this selector are met. If specified more than once, matches must be found for all descendantSelectors.

Parameters
descendantSelector: BySelector

The selector used to find a matching descendant element.

maxDepth: Int

The maximum depth under the element to search the descendant.

Returns
BySelector

A reference to this BySelector.

Throws
java.lang.IllegalArgumentException

if the selector has a parent/ancestor selector

hasParent

Added in 2.3.0
fun hasParent(parentSelector: BySelector): BySelector

Adds a parent selector criteria for matching. A UI element will be considered a match if it has a parent element (direct ancestor) which matches the parentSelector and all other criteria for this selector are met.

Parameters
parentSelector: BySelector

The selector used to find a matching parent element.

Returns
BySelector

A reference to this BySelector.

hint

Added in 2.3.0
@RequiresApi(value = 26)
fun hint(hintValue: Pattern): BySelector

Sets the hint value criteria for matching. A UI element will be considered a match if its hint value matches the hintValuePattern and all other criteria for this selector are met.

Hint text is displayed when there's no user input text.

Parameters
hintValue: Pattern

The Pattern to be used for matching.

Returns
BySelector

A reference to this BySelector.

hint

Added in 2.3.0
@RequiresApi(value = 26)
fun hint(hintValue: String): BySelector

Sets the hint value criteria for matching. A UI element will be considered a match if its hint value exactly matches the hintValue parameter and all other criteria for this selector are met.

Hint text is displayed when there's no user input text.

Parameters
hintValue: String

The exact value to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

hintContains

Added in 2.3.0
@RequiresApi(value = 26)
fun hintContains(substring: String): BySelector

Sets the hint value criteria for matching. A UI element will be considered a match if its hint value contains the substring parameter and all other criteria for this selector are met.

Hint text is displayed when there's no user input text.

Parameters
substring: String

The substring to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

hintEndsWith

Added in 2.3.0
@RequiresApi(value = 26)
fun hintEndsWith(suffix: String): BySelector

Sets the hint value criteria for matching. A UI element will be considered a match if its hint value ends with the suffix parameter and all other criteria for this selector are met.

Hint text is displayed when there's no user input text.

Parameters
suffix: String

The suffix to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

hintStartsWith

Added in 2.3.0
@RequiresApi(value = 26)
fun hintStartsWith(prefix: String): BySelector

Sets the hint value criteria for matching. A UI element will be considered a match if its hint value starts with the prefix parameter and all other criteria for this selector are met.

Hint text is displayed when there's no user input text.

Parameters
prefix: String

The prefix to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

longClickable

Added in 2.2.0
fun longClickable(isLongClickable: Boolean): BySelector

Sets the search criteria to match elements that are long clickable or not long clickable.

Parameters
isLongClickable: Boolean

Whether to match elements that are long clickable or elements that are not long clickable.

Returns
BySelector

A reference to this BySelector.

maxDepth

Added in 2.2.0
fun maxDepth(max: Int): BySelector

Sets the search criteria to match elements that are no more than a certain depth.

minDepth

Added in 2.2.0
fun minDepth(min: Int): BySelector

Sets the search criteria to match elements that are at least a certain depth.

pkg

Added in 2.2.0
fun pkg(applicationPackage: Pattern): BySelector

Sets the package name criteria for matching. A UI element will be considered a match if its application package name matches the applicationPackagePattern and all other criteria for this selector are met.

Parameters
applicationPackage: Pattern

The Pattern to be used for matching.

Returns
BySelector

A reference to this BySelector.

pkg

Added in 2.2.0
fun pkg(applicationPackage: String): BySelector

Sets the application package name criteria for matching. A UI element will be considered a match if its application package name exactly matches the applicationPackage parameter and all other criteria for this selector are met.

Parameters
applicationPackage: String

The exact value to match.

Returns
BySelector

A reference to this BySelector.

res

Added in 2.2.0
fun res(resourceName: Pattern): BySelector

Sets the resource name criteria for matching. A UI element will be considered a match if its resource name matches the resourceNamePattern and all other criteria for this selector are met.

Parameters
resourceName: Pattern

The Pattern to be used for matching.

Returns
BySelector

A reference to this BySelector.

res

Added in 2.2.0
fun res(resourceName: String): BySelector

Sets the resource name criteria for matching. A UI element will be considered a match if its resource name exactly matches the resourceName parameter and all other criteria for this selector are met.

Parameters
resourceName: String

The exact value to match.

Returns
BySelector

A reference to this BySelector.

res

Added in 2.2.0
fun res(resourcePackage: String, resourceId: String): BySelector

Sets the resource name criteria for matching. A UI element will be considered a match if its resource package and resource id exactly match the resourcePackage and resourceId parameters and all other criteria for this selector are met.

Parameters
resourcePackage: String

The resource package value to match.

resourceId: String

The resouce-id value to match.

Returns
BySelector

A reference to this BySelector.

scrollable

Added in 2.2.0
fun scrollable(isScrollable: Boolean): BySelector

Sets the search criteria to match elements that are scrollable or not scrollable.

Parameters
isScrollable: Boolean

Whether to match elements that are scrollable or elements that are not scrollable.

Returns
BySelector

A reference to this BySelector.

selected

Added in 2.2.0
fun selected(isSelected: Boolean): BySelector

Sets the search criteria to match elements that are selected or not selected.

Parameters
isSelected: Boolean

Whether to match elements that are selected or elements that are not selected.

Returns
BySelector

A reference to this BySelector.

text

Added in 2.2.0
fun text(textValue: Pattern): BySelector

Sets the text value criteria for matching. A UI element will be considered a match if its text value matches the textValuePattern and all other criteria for this selector are met.

Parameters
textValue: Pattern

The Pattern to be used for matching.

Returns
BySelector

A reference to this BySelector.

text

Added in 2.2.0
fun text(textValue: String): BySelector

Sets the text value criteria for matching. A UI element will be considered a match if its text value exactly matches the textValue parameter and all other criteria for this selector are met.

Parameters
textValue: String

The exact value to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

textContains

Added in 2.2.0
fun textContains(substring: String): BySelector

Sets the text value criteria for matching. A UI element will be considered a match if its text value contains the substring parameter and all other criteria for this selector are met.

Parameters
substring: String

The substring to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

textEndsWith

Added in 2.2.0
fun textEndsWith(suffix: String): BySelector

Sets the text value criteria for matching. A UI element will be considered a match if its text value ends with the suffix parameter and all other criteria for this selector are met.

Parameters
suffix: String

The suffix to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

textStartsWith

Added in 2.2.0
fun textStartsWith(prefix: String): BySelector

Sets the text value criteria for matching. A UI element will be considered a match if its text value starts with the prefix parameter and all other criteria for this selector are met.

Parameters
prefix: String

The prefix to match (case-sensitive).

Returns
BySelector

A reference to this BySelector.

toString

fun toString(): String!

Returns a String representation of this BySelector. The format is "BySelector [=' ... ]". Each criteria is listed as a key-value pair where the key is the name of the criteria expressed in all caps (e.g. CLAZZ, RES, etc).