# Selectors
The selector builders (`text`, `res`, `desc`, …), the `Selector` they return and the match
modes. Guide: [Selectors](../../guide/selectors.md).
## module `tap_e2e.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.
---
### function `text`
```python
text(value: 'str', mode: 'MatchMode' = ) → Selector
```
Visible text; Compose ``Text`` and View ``TextView``/``Button`` both expose it.
---
### function `text_contains`
```python
text_contains(value: 'str') → Selector
```
Text containing ``value``.
---
### function `text_starts_with`
```python
text_starts_with(value: 'str') → Selector
```
Text starting with ``value``.
---
### function `text_matches`
```python
text_matches(re2: 'str') → Selector
```
Text fully matching the RE2 regular expression ``re2``.
---
### function `desc`
```python
desc(value: 'str', mode: 'MatchMode' = ) → Selector
```
``contentDescription`` (View) / ``contentDescription`` semantics (Compose).
---
### function `res_id`
```python
res_id(package_name: 'str', name: 'str') → Selector
```
Exactly the Android View resource id ``package:id/name``.
---
### function `res`
```python
res(name: 'str') → Selector
```
Resource id ``name`` in any 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.
---
### function `class_name`
```python
class_name(
value: 'str',
mode: 'MatchMode' =
) → Selector
```
Widget class name, e.g. ``android.widget.EditText``.
---
### function `hint`
```python
hint(value: 'str', mode: 'MatchMode' = ) → Selector
```
Hint of an empty text field (an empty ``EditText`` shows its hint as its text).
---
### function `clickable`
```python
clickable() → Selector
```
Any clickable node; combine with ``and_text`` etc.
---
### function `scrollable`
```python
scrollable() → Selector
```
Any scrollable node; combine with ``and_res`` etc.
---
### function `any_of`
```python
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 ``|``.
---
### function `all_of`
```python
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 ``&``.
---
### class `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``.
### method `Selector.__init__`
```python
__init__(_proto: 'pb.Selector') → None
```
---
#### method `Selector.and_class_name`
```python
and_class_name(
value: 'str',
mode: 'MatchMode' =
) → Selector
```
Also require this widget class name.
---
#### method `Selector.and_desc`
```python
and_desc(
value: 'str',
mode: 'MatchMode' =
) → Selector
```
Also require this content description.
---
#### method `Selector.and_hint`
```python
and_hint(
value: 'str',
mode: 'MatchMode' =
) → Selector
```
Also require this hint (empty text fields).
---
#### method `Selector.and_res`
```python
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``).
---
#### method `Selector.and_text`
```python
and_text(
value: 'str',
mode: 'MatchMode' =
) → Selector
```
Also require this text (``mode``: ``EXACT``, ``CONTAINS``, ``STARTS_WITH``, ``ENDS_WITH``, ``REGEX``).
---
#### method `Selector.at`
```python
at(index: 'int') → Selector
```
Accept the ``index``-th match (0-based) in accessibility order instead of requiring exactly one.
---
#### method `Selector.checkable`
```python
checkable(value: 'bool' = True) → Selector
```
Require ``isCheckable == value``.
---
#### method `Selector.checked`
```python
checked(value: 'bool' = True) → Selector
```
Require ``isChecked == value``.
---
#### method `Selector.child`
```python
child(other: 'Selector') → Selector
```
Match the direct child ``other`` of this node; same rules as ``descendant``.
---
#### method `Selector.clickable`
```python
clickable(value: 'bool' = True) → Selector
```
Require ``isClickable == value``.
---
#### method `Selector.descendant`
```python
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.
---
#### method `Selector.enabled`
```python
enabled(value: 'bool' = True) → Selector
```
Require ``isEnabled == value``.
---
#### method `Selector.first`
```python
first() → Selector
```
Accept the first match in accessibility order instead of requiring exactly one.
---
#### method `Selector.focusable`
```python
focusable(value: 'bool' = True) → Selector
```
Require ``isFocusable == value``.
---
#### method `Selector.focused`
```python
focused(value: 'bool' = True) → Selector
```
Require ``isFocused == value``.
---
#### classmethod `Selector.from_proto`
```python
from_proto(message: 'pb.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.
---
#### method `Selector.has_ancestor`
```python
has_ancestor(other: 'Selector') → Selector
```
Keep matching this node, but only when an ancestor matches ``other``.
---
#### method `Selector.has_child`
```python
has_child(other: 'Selector') → Selector
```
Keep matching this node, but only when a direct child matches ``other``.
---
#### method `Selector.has_descendant`
```python
has_descendant(other: 'Selector') → Selector
```
Keep matching this node, but only when some descendant matches ``other``.
---
#### method `Selector.has_parent`
```python
has_parent(other: 'Selector') → Selector
```
Keep matching this node, but only when its parent matches ``other``.
---
#### method `Selector.long_clickable`
```python
long_clickable(value: 'bool' = True) → Selector
```
Require ``isLongClickable == value``.
---
#### method `Selector.render`
```python
render() → str
```
The selector as protobuf text, exactly as the device will see it.
---
#### method `Selector.scrollable`
```python
scrollable(value: 'bool' = True) → Selector
```
Require ``isScrollable == value``.
---
#### method `Selector.selected`
```python
selected(value: 'bool' = True) → Selector
```
Require ``isSelected == value``.
---
#### method `Selector.to_proto`
```python
to_proto() → pb.Selector
```
A copy of the ``tap.v1.Selector`` message this Selector sends.