Selectors¶

The selector builders (text, res, desc, …), the Selector they return and the match modes. Guide: Selectors.

selectors ¶

Selector builders. A Selector builds the protocol's AST (tap.v1.Selector), a small expression tree the server forwards to the driver unchanged, so what a test builds is validated identically by the server and the driver; render() shows it and errors quote it. Building one does no I/O; every action resolves it again on the device.

Functions:

Name	Description
`text`	Visible text; Compose `Text` and View `TextView`/`Button` both expose it.
`text_contains`	Text containing `value`.
`text_starts_with`	Text starting with `value`.
`text_matches`	Text fully matching the RE2 regular expression `re2`.
`desc`	`contentDescription` (View) / `contentDescription` semantics (Compose).
`res_id`	Exactly the Android View resource id `package:id/name`.
`res`	Resource id `name` in any package (`<package>:id/name`), or a Compose `testTag`
`class_name`	Widget class name, e.g. `android.widget.EditText`.
`hint`	Hint of an empty text field (an empty `EditText` shows its hint as its text).
`clickable`	Any clickable node; combine with `and_text` etc.
`scrollable`	Any scrollable node; combine with `and_res` etc.
`any_of`	Any of the selectors may match: `any_of(text("OK"), text("Allow"), desc("Accept"))`.
`all_of`	All of the selectors must hold on one node. Scope and match choice come from `first`;

EXACT ¶

EXACT

CONTAINS ¶

CONTAINS

STARTS_WITH ¶

STARTS_WITH

ENDS_WITH ¶

ENDS_WITH

REGEX ¶

REGEX

Selector ¶

An immutable description of one accessibility node.

Build one with the module functions (text, res, desc, ...), narrow it with the methods below and combine selectors with & / |; each returns a new Selector. Bind it with App.element for one package or Screen.element for whatever is visible. Selectors are values: equal when their protos are equal, and hashable (usable in sets and as dict keys).

Composition never silently drops a part: an operand of &, | or a has_* relation, and the target of descendant/child, must not carry a different scope, and only the selector that ends up as the result may carry a match choice (first/at); anything else raises ValueError.

Methods:

Name	Description
`and_text`	Also require this text (`mode`: `EXACT`, `CONTAINS`, `STARTS_WITH`, `ENDS_WITH`, `REGEX`).
`and_desc`	Also require this content description.
`and_class_name`	Also require this widget class name.
`and_hint`	Also require this hint (empty text fields).
`and_res`	Also require a resource id, like Kotlin `andRes`: `and_res("pkg", "name")` is
`checkable`	Require `isCheckable == value`.
`checked`	Require `isChecked == value`.
`clickable`	Require `isClickable == value`.
`enabled`	Require `isEnabled == value`.
`focusable`	Require `isFocusable == value`.
`focused`	Require `isFocused == value`.
`long_clickable`	Require `isLongClickable == value`.
`scrollable`	Require `isScrollable == value`.
`selected`	Require `isSelected == value`.
`has_descendant`	Keep matching this node, but only when some descendant matches `other`.
`has_child`	Keep matching this node, but only when a direct child matches `other`.
`has_parent`	Keep matching this node, but only when its parent matches `other`.
`has_ancestor`	Keep matching this node, but only when an ancestor matches `other`.
`descendant`	An element matching `other` somewhere below this one. The result keeps `other`'s
`child`	Match the direct child `other` of this node; same rules as `descendant`.
`first`	Accept the first match in accessibility order instead of requiring exactly one.
`at`	Accept the `index`-th match (0-based) in accessibility order instead of requiring exactly one.
`from_proto`	The Selector for a `tap.v1.Selector` message (`tap_e2e.proto`), e.g. one a
`to_proto`	A copy of the `tap.v1.Selector` message this Selector sends.
`render`	The selector as protobuf text, exactly as the device will see it.

and_text ¶

and_text(value: str, mode: MatchMode = EXACT) -> Selector

Also require this text (mode: EXACT, CONTAINS, STARTS_WITH, ENDS_WITH, REGEX).

and_desc ¶

and_desc(value: str, mode: MatchMode = EXACT) -> Selector

Also require this content description.

and_class_name ¶

and_class_name(value: str, mode: MatchMode = EXACT) -> Selector

Also require this widget class name.

and_hint ¶

and_hint(value: str, mode: MatchMode = EXACT) -> Selector

Also require this hint (empty text fields).

and_res ¶

and_res(package_name_or_name: str, name: str | None = None) -> Selector

Also require a resource id, like Kotlin andRes: and_res("pkg", "name") is exactly pkg:id/name; and_res("name") is name in any package (see res).

checkable ¶

checkable(value: bool = True) -> Selector

Require isCheckable == value.

checked ¶

checked(value: bool = True) -> Selector

Require isChecked == value.

clickable ¶

clickable(value: bool = True) -> Selector

Require isClickable == value.

enabled ¶

enabled(value: bool = True) -> Selector

Require isEnabled == value.

focusable ¶

focusable(value: bool = True) -> Selector

Require isFocusable == value.

focused ¶

focused(value: bool = True) -> Selector

Require isFocused == value.

long_clickable ¶

long_clickable(value: bool = True) -> Selector

Require isLongClickable == value.

scrollable ¶

scrollable(value: bool = True) -> Selector

Require isScrollable == value.

selected ¶

selected(value: bool = True) -> Selector

Require isSelected == value.

has_descendant ¶

has_descendant(other: Selector) -> Selector

Keep matching this node, but only when some descendant matches other.

has_child ¶

has_child(other: Selector) -> Selector

Keep matching this node, but only when a direct child matches other.

has_parent ¶

has_parent(other: Selector) -> Selector

Keep matching this node, but only when its parent matches other.

has_ancestor ¶

has_ancestor(other: Selector) -> Selector

Keep matching this node, but only when an ancestor matches other.

descendant ¶

descendant(other: Selector) -> Selector

An element matching other somewhere below this one. The result keeps other's match choice and this selector's scope. This selector must not carry a match choice: the ancestor is a bare predicate, so lst.at(2).descendant(x) would otherwise search under every list; pick among the results instead (lst.descendant(x).at(2)). Raises ValueError for a picked receiver or an other with a different scope.

child ¶

child(other: Selector) -> Selector

Match the direct child other of this node; same rules as descendant.

first ¶

first() -> Selector

Accept the first match in accessibility order instead of requiring exactly one.

at ¶

at(index: int) -> Selector

Accept the index-th match (0-based) in accessibility order instead of requiring exactly one.

from_proto ¶

from_proto(message: Selector) -> Selector

The Selector for a tap.v1.Selector message (tap_e2e.proto), e.g. one a ScreenNode or a stored recording holds; the message is copied.

to_proto ¶

to_proto() -> Selector

A copy of the tap.v1.Selector message this Selector sends.

render ¶

render() -> str

The selector as protobuf text, exactly as the device will see it.

text ¶

text(value: str, mode: MatchMode = EXACT) -> Selector

Visible text; Compose Text and View TextView/Button both expose it.

text_contains ¶

text_contains(value: str) -> Selector

Text containing value.

text_starts_with ¶

text_starts_with(value: str) -> Selector

Text starting with value.

text_matches ¶

text_matches(re2: str) -> Selector

Text fully matching the RE2 regular expression re2.

desc ¶

desc(value: str, mode: MatchMode = EXACT) -> Selector

contentDescription (View) / contentDescription semantics (Compose).

res_id ¶

res_id(package_name: str, name: str) -> Selector

Exactly the Android View resource id package:id/name.

res ¶

res(name: str) -> Selector

Resource id name in any package (<package>:id/name), or a Compose testTag name under testTagsAsResourceId. Under App.element only that app's nodes match; under Screen.element any visible package's. Use res_id to name the id's package.

class_name ¶

class_name(value: str, mode: MatchMode = EXACT) -> Selector

Widget class name, e.g. android.widget.EditText.

hint ¶

hint(value: str, mode: MatchMode = EXACT) -> Selector

Hint of an empty text field (an empty EditText shows its hint as its text).

clickable ¶

clickable() -> Selector

Any clickable node; combine with and_text etc.

scrollable ¶

scrollable() -> Selector

Any scrollable node; combine with and_res etc.

any_of ¶

any_of(first: Selector, *rest: Selector) -> Selector

Any of the selectors may match: any_of(text("OK"), text("Allow"), desc("Accept")). Scope and match choice come from first; the others follow the operand rules of |.

all_of ¶

all_of(first: Selector, *rest: Selector) -> Selector

All of the selectors must hold on one node. Scope and match choice come from first; the others follow the operand rules of &.