Selectors
Target an element by what it says or is, instead of a snapshot ref. Use find to search by text,
label, value, role, or id, or pass a selector expression to any command that takes a target.
agent-device find "Settings" clickagent-device find text "Sign In" clickagent-device find label "Email" fill "user@example.com"agent-device find value "Search" clickagent-device type "query"agent-device find role button clickagent-device find id "com.example:id/login" clickagent-device find "Follow" listFind an element
find <query> [action] and find <locator> <query> [action] [value] take an optional locator
(text, label, value, role, or id), the query, and an optional action; the action defaults to
click. Without a locator it searches labels, values, and ids. Text
matches ignore case, and a field containing the query matches too; an exact match wins over a
partial one.
Actions:
click(default;pressandtapare aliases)listfocusfill <text>type <text>existswait [timeoutMs]get text,get attrs
list is read-only: it returns every match with its @ref and never taps, so use it to inspect
matches before you act. find has no longpress or swipe action; run list, then run the gesture
on the ref you picked, for example longpress @e14.
When more than one element matches, the mutating actions (click, focus, fill, type) reject
the query and list the candidates. This applies to text queries and selector expressions alike.
Read-only actions (exists, wait, get) use the first match, and list returns every match. Add --first or --last to pick a match by
position instead.
agent-device find "Follow" click --firstA read-only find that prints a ref (get text, get attrs, list) publishes only the refs it
returns, so it ends the earlier snapshot’s refs. A later get or wait on one of those older refs
fails with error.details.reason: ref_not_issued instead of reading whichever element now has that
number. Use a ref the find printed, or run snapshot -i again.
Tips:
find role <value>and therole=selector key use the same role names that snapshots show. See Structured node fields.- Use
find ... wait <timeoutMs>to wait for an element to appear. - Pair
findwith a scoped snapshot (snapshot -s "<label>") for speed. - [Android] If the matched node is not hittable, agent-device clicks or focuses the nearest hittable ancestor.
find ... focusandfind ... typeaim at a text field. If the match is a field or sits inside one, that field is the target, even when it is not hittable or has other fields beside it. Otherwise the target is the one enabled on-screen field inside the match.- Several enabled on-screen fields inside the match refuse with
AMBIGUOUS_MATCHand the field candidates. - A disabled target refuses with
COMMAND_FAILEDand reasontarget_disabled. This includes a match whose only on-screen fields are disabled. - A match or field covered by another visible element refuses with
COMMAND_FAILEDand reasontarget_covered. - Web text boxes are not recognized as text fields, so a web match keeps its own aim.
- Several enabled on-screen fields inside the match refuse with
- Use
fillto find a field and replace its text in one step. To append to the text in the focused field, useclickorpress, thentype.
Selector syntax
A selector expression is one or more key=value terms separated by spaces. An element must match
every term. Commands that take a target, such as press, fill, longpress, get, is, wait,
and scroll --until, accept a selector wherever they accept an @ref. find accepts one as its
query.
agent-device press 'role=button label="Continue"'agent-device fill 'label="Email" editable=true' "qa@example.com"agent-device wait 'id="checkout-total"' 5000agent-device press 'id="submit" || label="Submit order"'agent-device find 'role=button label="Follow"' listText keys:
| Key | Matches |
|---|---|
id |
The element’s identifier (test ID, resource ID, accessibility identifier) |
label |
The accessibility label |
value |
The accessibility value |
text |
The first non-empty of label, value, and identifier |
role |
The role shown in brackets in snapshot output (button, text-field, switch, …) |
appname |
The owning app’s name, on desktop targets that report it |
windowtitle |
The owning window’s title, on desktop targets that report it |
Text values match the whole field, ignoring case and extra whitespace: label="sign in" matches
Sign In but not Sign In Now. For partial matches, use find.
On Android, id= matches the element’s full resource-id, which keeps its pkg:id/name form for
native XML ids, while a React Native testID arrives bare (id="login"). A Jetpack Compose
Modifier.testTag is exposed to agent-device only when the app sets
semantics { testTagsAsResourceId = true }; then id="<tag>" matches it.
Boolean keys: visible, hidden, editable, selected, checked, focused, enabled, hittable. Write
visible=true or visible=false; a bare visible means visible=true.
checked (and is checked) reads the state of a checkable control (switch, checkbox, radio).
checked=true matches only an explicitly checked control and checked=false only an explicitly
unchecked one; an iOS mixed state and a control with no checked state match neither.
editable (and is editable) uses the node’s native editable fact when the snapshot carries one,
so a custom text view can match and a read-only field cannot. Without the fact it is inferred from
the element type. A disabled element is never editable.
Quoting and alternatives:
- Quote values that contain spaces, with double or single quotes:
label="Sign in". Escape a quote inside a value with a backslash:label="Say \"hi\"". - Wrap the whole expression in single quotes in the shell so it reaches agent-device as one argument.
- Separate alternatives with
||. agent-device tries them left to right and uses the first one that resolves. - Keys are case-insensitive. Commands that take a target reject an unknown key, such as
button="Save"; writerole=button label="Save"instead.
Response shape (click)
find "<query>" click --json returns metadata for the element it matched, taken from the resolved snapshot node:
{ "ref": "@e3", "locator": "any", "query": "Sign In", "x": 195, "y": 422}ref— snapshot ref of the matched (or nearest hittable ancestor) element.locator— the locator used (any,text,label,value,role,id).query— the search term as provided.x,y— tap coordinates derived from the matched element’s rect center.