BySelector

Artifact: androidx.test.uiautomator:uiautomator

View Source

Added in 2.2.0

---

Kotlin |Java

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	clazz(@NonNull Class clazz) 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	descContains(@NonNull String substring) Sets the content description criteria for matching.
@NonNull BySelector	descEndsWith(@NonNull String suffix) Sets the content description criteria for matching.
@NonNull BySelector	descStartsWith(@NonNull String prefix) 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	textContains(@NonNull String substring) Sets the text value criteria for matching.
@NonNull BySelector	textEndsWith(@NonNull String suffix) Sets the text value criteria for matching.
@NonNull BySelector	textStartsWith(@NonNull String prefix) Sets the text value criteria for matching.
String	toString() 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).