public class BySelector


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

Summary

Public methods

@NonNull BySelector
checkable(boolean isCheckable)

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

@NonNull BySelector
checked(boolean isChecked)

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

@NonNull BySelector
clazz(@NonNull Pattern className)

Sets the class name criteria for matching.

@NonNull BySelector
clazz(@NonNull String className)

Sets the class name criteria for matching.

@NonNull BySelector

Sets the class name criteria for matching.

@NonNull BySelector
clazz(@NonNull String packageName, @NonNull String className)

Sets the class name criteria for matching.

@NonNull BySelector
clickable(boolean isClickable)

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

@NonNull BySelector
depth(int exactDepth)

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

@NonNull BySelector
depth(int min, int max)

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

@NonNull BySelector
desc(@NonNull Pattern contentDescription)

Sets the content description criteria for matching.

@NonNull BySelector
desc(@NonNull String contentDescription)

Sets the content description criteria for matching.

@NonNull BySelector

Sets the content description criteria for matching.

@NonNull BySelector

Sets the content description criteria for matching.

@NonNull BySelector

Sets the content description criteria for matching.

@NonNull BySelector
@RequiresApi(value = 30)
displayId(int displayId)

Adds a display ID selector criteria for matching.

@NonNull BySelector
enabled(boolean isEnabled)

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

@NonNull BySelector
focusable(boolean isFocusable)

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

@NonNull BySelector
focused(boolean isFocused)

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

@NonNull BySelector
hasAncestor(@NonNull BySelector ancestorSelector)

Adds an ancestor selector criteria for matching.

@NonNull BySelector
hasAncestor(
    @NonNull BySelector ancestorSelector,
    @IntRange(from = 1) int maxAncestorDistance
)

Adds an ancestor selector criteria for matching.

@NonNull BySelector
hasChild(@NonNull BySelector childSelector)

Adds a child selector criteria for matching.

@NonNull BySelector
hasDescendant(@NonNull BySelector descendantSelector)

Adds a descendant selector criteria for matching.

@NonNull BySelector
hasDescendant(@NonNull BySelector descendantSelector, int maxDepth)

Adds a descendant selector criteria for matching.

@NonNull BySelector
hasParent(@NonNull BySelector parentSelector)

Adds a parent selector criteria for matching.

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

Sets the hint value criteria for matching.

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

Sets the hint value criteria for matching.

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

Sets the hint value criteria for matching.

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

Sets the hint value criteria for matching.

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

Sets the hint value criteria for matching.

@NonNull BySelector
longClickable(boolean isLongClickable)

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

@NonNull BySelector
maxDepth(int max)

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

@NonNull BySelector
minDepth(int min)

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

@NonNull BySelector
pkg(@NonNull Pattern applicationPackage)

Sets the package name criteria for matching.

@NonNull BySelector
pkg(@NonNull String applicationPackage)

Sets the application package name criteria for matching.

@NonNull BySelector
res(@NonNull Pattern resourceName)

Sets the resource name criteria for matching.

@NonNull BySelector
res(@NonNull String resourceName)

Sets the resource name criteria for matching.

@NonNull BySelector
res(@NonNull String resourcePackage, @NonNull String resourceId)

Sets the resource name criteria for matching.

@NonNull BySelector
scrollable(boolean isScrollable)

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

@NonNull BySelector
selected(boolean isSelected)

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

@NonNull BySelector
text(@NonNull Pattern textValue)

Sets the text value criteria for matching.

@NonNull BySelector
text(@NonNull String textValue)

Sets the text value criteria for matching.

@NonNull BySelector

Sets the text value criteria for matching.

@NonNull BySelector

Sets the text value criteria for matching.

@NonNull BySelector

Sets the text value criteria for matching.

String

Returns a String representation of this BySelector.

Public methods

checkable

Added in 2.2.0
public @NonNull BySelector checkable(boolean isCheckable)

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

Parameters
boolean isCheckable

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

Returns
@NonNull BySelector

A reference to this BySelector.

checked

Added in 2.2.0
public @NonNull BySelector checked(boolean isChecked)

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

Parameters
boolean isChecked

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

Returns
@NonNull BySelector

A reference to this BySelector.

clazz

Added in 2.2.0
public @NonNull BySelector clazz(@NonNull Pattern className)

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
@NonNull Pattern className

The Pattern to be used for matching.

Returns
@NonNull BySelector

A reference to this BySelector.

clazz

Added in 2.2.0
public @NonNull BySelector clazz(@NonNull String className)

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
@NonNull String className

The full class name value to match.

Returns
@NonNull BySelector

A reference to this BySelector.

clazz

Added in 2.2.0
public @NonNull BySelector clazz(@NonNull Class clazz)

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
@NonNull Class clazz

The class to match.

Returns
@NonNull BySelector

A reference to this BySelector

clazz

Added in 2.2.0
public @NonNull BySelector clazz(@NonNull String packageName, @NonNull String className)

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
@NonNull String packageName

The package value to match.

@NonNull String className

The class name value to match.

Returns
@NonNull BySelector

A reference to this BySelector.

clickable

Added in 2.2.0
public @NonNull BySelector clickable(boolean isClickable)

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

Parameters
boolean isClickable

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

Returns
@NonNull BySelector

A reference to this BySelector.

depth

Added in 2.2.0
public @NonNull BySelector depth(int exactDepth)

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

depth

Added in 2.2.0
public @NonNull BySelector depth(int min, int max)

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

desc

Added in 2.2.0
public @NonNull BySelector desc(@NonNull Pattern contentDescription)

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
@NonNull Pattern contentDescription

The Pattern to be used for matching.

Returns
@NonNull BySelector

A reference to this BySelector.

desc

Added in 2.2.0
public @NonNull BySelector desc(@NonNull String contentDescription)

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
@NonNull String contentDescription

The exact value to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

descContains

Added in 2.2.0
public @NonNull BySelector descContains(@NonNull String substring)

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
@NonNull String substring

The substring to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

descEndsWith

Added in 2.2.0
public @NonNull BySelector descEndsWith(@NonNull String suffix)

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
@NonNull String suffix

The suffix to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

descStartsWith

Added in 2.2.0
public @NonNull BySelector descStartsWith(@NonNull String prefix)

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
@NonNull String prefix

The prefix to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

displayId

Added in 2.3.0
@RequiresApi(value = 30)
public @NonNull BySelector displayId(int displayId)

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
int displayId

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

Returns
@NonNull BySelector

A reference to this BySelector.

enabled

Added in 2.2.0
public @NonNull BySelector enabled(boolean isEnabled)

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

Parameters
boolean isEnabled

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

Returns
@NonNull BySelector

A reference to this BySelector.

focusable

Added in 2.2.0
public @NonNull BySelector focusable(boolean isFocusable)

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

Parameters
boolean isFocusable

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

Returns
@NonNull BySelector

A reference to this BySelector.

focused

Added in 2.2.0
public @NonNull BySelector focused(boolean isFocused)

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

Parameters
boolean isFocused

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

Returns
@NonNull BySelector

A reference to this BySelector.

hasAncestor

Added in 2.3.0
public @NonNull BySelector hasAncestor(@NonNull BySelector ancestorSelector)

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
@NonNull BySelector ancestorSelector

The selector used to find a matching ancestor element.

Returns
@NonNull BySelector

A reference to this BySelector.

hasAncestor

Added in 2.3.0
public @NonNull BySelector hasAncestor(
    @NonNull BySelector ancestorSelector,
    @IntRange(from = 1) int maxAncestorDistance
)

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
@NonNull BySelector ancestorSelector

The selector used to find a matching ancestor element.

@IntRange(from = 1) int maxAncestorDistance

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
@NonNull BySelector

A reference to this BySelector.

hasChild

Added in 2.2.0
public @NonNull BySelector hasChild(@NonNull BySelector childSelector)

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
@NonNull BySelector childSelector

The selector used to find a matching child element.

Returns
@NonNull BySelector

A reference to this BySelector.

Throws
java.lang.IllegalArgumentException

if the selector has a parent/ancestor selector

hasDescendant

Added in 2.2.0
public @NonNull BySelector hasDescendant(@NonNull BySelector descendantSelector)

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
@NonNull BySelector descendantSelector

The selector used to find a matching descendant element.

Returns
@NonNull BySelector

A reference to this BySelector.

Throws
java.lang.IllegalArgumentException

if the selector has a parent/ancestor selector

hasDescendant

Added in 2.2.0
public @NonNull BySelector hasDescendant(@NonNull BySelector descendantSelector, int maxDepth)

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
@NonNull BySelector descendantSelector

The selector used to find a matching descendant element.

int maxDepth

The maximum depth under the element to search the descendant.

Returns
@NonNull BySelector

A reference to this BySelector.

Throws
java.lang.IllegalArgumentException

if the selector has a parent/ancestor selector

hasParent

Added in 2.3.0
public @NonNull BySelector hasParent(@NonNull BySelector parentSelector)

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
@NonNull BySelector parentSelector

The selector used to find a matching parent element.

Returns
@NonNull BySelector

A reference to this BySelector.

hint

Added in 2.3.0
@RequiresApi(value = 26)
public @NonNull BySelector hint(@NonNull Pattern hintValue)

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
@NonNull Pattern hintValue

The Pattern to be used for matching.

Returns
@NonNull BySelector

A reference to this BySelector.

hint

Added in 2.3.0
@RequiresApi(value = 26)
public @NonNull BySelector hint(@NonNull String hintValue)

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
@NonNull String hintValue

The exact value to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

hintContains

Added in 2.3.0
@RequiresApi(value = 26)
public @NonNull BySelector hintContains(@NonNull String substring)

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
@NonNull String substring

The substring to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

hintEndsWith

Added in 2.3.0
@RequiresApi(value = 26)
public @NonNull BySelector hintEndsWith(@NonNull String suffix)

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
@NonNull String suffix

The suffix to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

hintStartsWith

Added in 2.3.0
@RequiresApi(value = 26)
public @NonNull BySelector hintStartsWith(@NonNull String prefix)

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
@NonNull String prefix

The prefix to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

longClickable

Added in 2.2.0
public @NonNull BySelector longClickable(boolean isLongClickable)

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

Parameters
boolean isLongClickable

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

Returns
@NonNull BySelector

A reference to this BySelector.

maxDepth

Added in 2.2.0
public @NonNull BySelector maxDepth(int max)

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

minDepth

Added in 2.2.0
public @NonNull BySelector minDepth(int min)

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

pkg

Added in 2.2.0
public @NonNull BySelector pkg(@NonNull Pattern applicationPackage)

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
@NonNull Pattern applicationPackage

The Pattern to be used for matching.

Returns
@NonNull BySelector

A reference to this BySelector.

pkg

Added in 2.2.0
public @NonNull BySelector pkg(@NonNull String applicationPackage)

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
@NonNull String applicationPackage

The exact value to match.

Returns
@NonNull BySelector

A reference to this BySelector.

res

Added in 2.2.0
public @NonNull BySelector res(@NonNull Pattern resourceName)

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
@NonNull Pattern resourceName

The Pattern to be used for matching.

Returns
@NonNull BySelector

A reference to this BySelector.

res

Added in 2.2.0
public @NonNull BySelector res(@NonNull String resourceName)

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
@NonNull String resourceName

The exact value to match.

Returns
@NonNull BySelector

A reference to this BySelector.

res

Added in 2.2.0
public @NonNull BySelector res(@NonNull String resourcePackage, @NonNull String resourceId)

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
@NonNull String resourcePackage

The resource package value to match.

@NonNull String resourceId

The resouce-id value to match.

Returns
@NonNull BySelector

A reference to this BySelector.

scrollable

Added in 2.2.0
public @NonNull BySelector scrollable(boolean isScrollable)

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

Parameters
boolean isScrollable

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

Returns
@NonNull BySelector

A reference to this BySelector.

selected

Added in 2.2.0
public @NonNull BySelector selected(boolean isSelected)

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

Parameters
boolean isSelected

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

Returns
@NonNull BySelector

A reference to this BySelector.

text

Added in 2.2.0
public @NonNull BySelector text(@NonNull Pattern textValue)

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
@NonNull Pattern textValue

The Pattern to be used for matching.

Returns
@NonNull BySelector

A reference to this BySelector.

text

Added in 2.2.0
public @NonNull BySelector text(@NonNull String textValue)

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
@NonNull String textValue

The exact value to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

textContains

Added in 2.2.0
public @NonNull BySelector textContains(@NonNull String substring)

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
@NonNull String substring

The substring to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

textEndsWith

Added in 2.2.0
public @NonNull BySelector textEndsWith(@NonNull String suffix)

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
@NonNull String suffix

The suffix to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

textStartsWith

Added in 2.2.0
public @NonNull BySelector textStartsWith(@NonNull String prefix)

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
@NonNull String prefix

The prefix to match (case-sensitive).

Returns
@NonNull BySelector

A reference to this BySelector.

toString

public String toString()

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).