public class UiSelector


Specifies the elements in the layout hierarchy for tests to target, filtered by properties such as text value, content-description, class name, and state information. You can also target an element by its location in a layout hierarchy.

Summary

Public constructors

Public methods

@NonNull UiSelector
checkable(boolean val)

Set the search criteria to match widgets that are checkable.

@NonNull UiSelector
checked(boolean val)

Set the search criteria to match widgets that are currently checked (usually for checkboxes).

@NonNull UiSelector

Adds a child UiSelector criteria to this selector.

@NonNull UiSelector
className(@NonNull String className)

Set the search criteria to match the class property for a widget (for example, "android.widget.Button").

@NonNull UiSelector
<T> className(@NonNull Class<T> type)

Set the search criteria to match the class property for a widget (for example, "android.widget.Button").

@NonNull UiSelector

Set the search criteria to match the class property for a widget, using a regular expression.

@NonNull UiSelector
clickable(boolean val)

Set the search criteria to match widgets that are clickable.

@NonNull UiSelector

Set the search criteria to match the content-description property for a widget.

@NonNull UiSelector

Set the search criteria to match the content-description property for a widget.

@NonNull UiSelector

Set the search criteria to match the content-description property for a widget.

@NonNull UiSelector

Set the search criteria to match the content-description property for a widget.

@NonNull UiSelector
enabled(boolean val)

Set the search criteria to match widgets that are enabled.

@NonNull UiSelector
focusable(boolean val)

Set the search criteria to match widgets that are focusable.

@NonNull UiSelector
focused(boolean val)

Set the search criteria to match widgets that have focus.

@NonNull UiSelector

Adds a child UiSelector criteria to this selector which is used to start search from the parent widget.

@NonNull UiSelector
index(int index)

Set the search criteria to match the widget by its node index in the layout hierarchy.

@NonNull UiSelector
instance(int instance)

Set the search criteria to match the widget by its instance number.

@NonNull UiSelector
longClickable(boolean val)

Set the search criteria to match widgets that are long-clickable.

@NonNull UiSelector

Set the search criteria to match the package name of the application that contains the widget.

@NonNull UiSelector

Set the search criteria to match the package name of the application that contains the widget.

@NonNull UiSelector

Set the search criteria to match the given resource ID.

@NonNull UiSelector

Set the search criteria to match the resource ID of the widget, using a regular expression.

@NonNull UiSelector
scrollable(boolean val)

Set the search criteria to match widgets that are scrollable.

@NonNull UiSelector
selected(boolean val)

Set the search criteria to match widgets that are currently selected.

@NonNull UiSelector

Set the search criteria to match the visible text displayed in a widget (for example, the text label to launch an app).

@NonNull UiSelector

Set the search criteria to match the visible text in a widget where the visible text must contain the string in your input argument.

@NonNull UiSelector

Set the search criteria to match the visible text displayed in a layout element, using a regular expression.

@NonNull UiSelector

Set the search criteria to match visible text in a widget that is prefixed by the text parameter.

String

Protected methods

@NonNull UiSelector

Public constructors

UiSelector

public UiSelector()

Public methods

checkable

public @NonNull UiSelector checkable(boolean val)

Set the search criteria to match widgets that are checkable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

checked

public @NonNull UiSelector checked(boolean val)

Set the search criteria to match widgets that are currently checked (usually for checkboxes). Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

childSelector

public @NonNull UiSelector childSelector(@NonNull UiSelector selector)

Adds a child UiSelector criteria to this selector. Use this selector to narrow the search scope to child widgets under a specific parent widget.

Parameters
@NonNull UiSelector selector
Returns
@NonNull UiSelector

UiSelector with this added search criterion

className

public @NonNull UiSelector className(@NonNull String className)

Set the search criteria to match the class property for a widget (for example, "android.widget.Button").

Parameters
@NonNull String className

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

className

public @NonNull UiSelector <T> className(@NonNull Class<T> type)

Set the search criteria to match the class property for a widget (for example, "android.widget.Button").

Parameters
@NonNull Class<T> type

type

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

classNameMatches

public @NonNull UiSelector classNameMatches(@NonNull String regex)

Set the search criteria to match the class property for a widget, using a regular expression.

Parameters
@NonNull String regex

a regular expression

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

clickable

public @NonNull UiSelector clickable(boolean val)

Set the search criteria to match widgets that are clickable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

description

public @NonNull UiSelector description(@NonNull String desc)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must match exactly with the string in your input argument. Matching is case-sensitive.

Parameters
@NonNull String desc

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

descriptionContains

public @NonNull UiSelector descriptionContains(@NonNull String desc)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must contain the string in your input argument. Matching is case-insensitive.

Parameters
@NonNull String desc

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

descriptionMatches

public @NonNull UiSelector descriptionMatches(@NonNull String regex)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must match exactly with the string in your input argument.

Parameters
@NonNull String regex

a regular expression

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

descriptionStartsWith

public @NonNull UiSelector descriptionStartsWith(@NonNull String desc)

Set the search criteria to match the content-description property for a widget. The content-description is typically used by the Android Accessibility framework to provide an audio prompt for the widget when the widget is selected. The content-description for the widget must start with the string in your input argument. Matching is case-insensitive.

Parameters
@NonNull String desc

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

enabled

public @NonNull UiSelector enabled(boolean val)

Set the search criteria to match widgets that are enabled. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

focusable

public @NonNull UiSelector focusable(boolean val)

Set the search criteria to match widgets that are focusable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

focused

public @NonNull UiSelector focused(boolean val)

Set the search criteria to match widgets that have focus. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

fromParent

public @NonNull UiSelector fromParent(@NonNull UiSelector selector)

Adds a child UiSelector criteria to this selector which is used to start search from the parent widget. Use this selector to narrow the search scope to sibling widgets as well all child widgets under a parent.

Parameters
@NonNull UiSelector selector
Returns
@NonNull UiSelector

UiSelector with this added search criterion

index

public @NonNull UiSelector index(int index)

Set the search criteria to match the widget by its node index in the layout hierarchy. The index value must be 0 or greater. Using the index can be unreliable and should only be used as a last resort for matching. Instead, consider using the instance method.

Parameters
int index

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

instance

public @NonNull UiSelector instance(int instance)

Set the search criteria to match the widget by its instance number. The instance value must be 0 or greater, where the first instance is 0. For example, to simulate a user click on the third image that is enabled in a UI screen, you could specify a a search criteria where the instance is 2, the className matches the image widget class, and enabled is true. The code would look like this: new UiSelector().className("android.widget.ImageView") .enabled(true).instance(2);

Parameters
int instance

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

longClickable

public @NonNull UiSelector longClickable(boolean val)

Set the search criteria to match widgets that are long-clickable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

packageName

public @NonNull UiSelector packageName(@NonNull String name)

Set the search criteria to match the package name of the application that contains the widget.

Parameters
@NonNull String name

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

packageNameMatches

public @NonNull UiSelector packageNameMatches(@NonNull String regex)

Set the search criteria to match the package name of the application that contains the widget.

Parameters
@NonNull String regex

a regular expression

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

resourceId

public @NonNull UiSelector resourceId(@NonNull String id)

Set the search criteria to match the given resource ID.

Parameters
@NonNull String id

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

resourceIdMatches

public @NonNull UiSelector resourceIdMatches(@NonNull String regex)

Set the search criteria to match the resource ID of the widget, using a regular expression.

Parameters
@NonNull String regex

a regular expression

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

scrollable

public @NonNull UiSelector scrollable(boolean val)

Set the search criteria to match widgets that are scrollable. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

selected

public @NonNull UiSelector selected(boolean val)

Set the search criteria to match widgets that are currently selected. Typically, using this search criteria alone is not useful. You should also include additional criteria, such as text, content-description, or the class name for a widget. If no other search criteria is specified, and there is more than one matching widget, the first widget in the tree is selected.

Parameters
boolean val

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

text

public @NonNull UiSelector text(@NonNull String text)

Set the search criteria to match the visible text displayed in a widget (for example, the text label to launch an app). The text for the element must match exactly with the string in your input argument. Matching is case-sensitive.

Parameters
@NonNull String text

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

textContains

public @NonNull UiSelector textContains(@NonNull String text)

Set the search criteria to match the visible text in a widget where the visible text must contain the string in your input argument. The matching is case-sensitive.

Parameters
@NonNull String text

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

textMatches

public @NonNull UiSelector textMatches(@NonNull String regex)

Set the search criteria to match the visible text displayed in a layout element, using a regular expression. The text in the widget must match exactly with the string in your input argument.

Parameters
@NonNull String regex

a regular expression

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

textStartsWith

public @NonNull UiSelector textStartsWith(@NonNull String text)

Set the search criteria to match visible text in a widget that is prefixed by the text parameter. The matching is case-insensitive.

Parameters
@NonNull String text

Value to match

Returns
@NonNull UiSelector

UiSelector with the specified search criteria

toString

public String toString()

Protected methods

cloneSelector

protected @NonNull UiSelector cloneSelector()