callstack__agent-device/docs/selectors.md

Selectors

Use find to locate elements by semantic attributes instead of raw refs.

agent-device find "Settings" click
agent-device find text "Sign In" click
agent-device find label "Email" fill "user@example.com"
agent-device find value "Search" click
agent-device type "query"
agent-device find role button click
agent-device find id "com.example:id/login" click

Tips:

• Use find ... wait <timeoutMs> to wait for UI to appear.
• Combine with scoped snapshots using snapshot -s "<label>" for speed.
• [Android] If a matched node is not hittable, agent-device will click/focus the nearest hittable ancestor.
• Use fill when you want find-plus-targeted text replacement in one step. Use click or press plus type when you need append semantics in the focused field.

Response shape (click)

find "<query>" click --json returns deterministic matched-target metadata derived 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 — find strategy 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.