A phone Locator describes a target and sends nothing until you act on it or
query it. Each call resolves it against whatever is on screen at that moment,
waits until it is actionable, and acts, all on the phone in one round trip.
row = phone.get_by_text("Battery").within(phone.get_by_role("list"))
result = row.tap()
print(result.resolved_by, result.bounds)
Build one from phone.locator(),
get_by_text() or get_by_role(). Refining it returns a new locator; a locator
never changes.
Timeouts are in milliseconds, as in the browser driver: 5,000 by default,
at most 60,000. A value outside that range raises ValueError. Running out raises TimeoutError (kind ActionTimeout).
Strategies
strategy, model and ocr_engine are set when the locator is built, and fall
back to the driver’s defaults. Actions and queries take only timeout.
| Strategy | How it resolves |
|---|
"auto" | The default. Uses the accessibility tree when the phone has one, and vision otherwise. |
"accessibility" | The tree only. Raises UnsupportedError on a phone without one. |
"vision" | The screen only: OCR for text, a model for query. Skips the tree. |
role, name, states and node_id always need the tree and raise
UnsupportedError without one; they are never turned into a model prompt.
query is the only selector a model reads.
Strategy is the type Literal["auto", "vision", "accessibility"], importable
from halyard.phone.
Refining
locator.nth() and locator.first()
The nth match in reading order, zero-based; first() is nth(0).
locator.nth(n)
locator.first()
locator.within()
Keep a match that is inside other. Calling it again scopes the new ancestor
inside the earlier one.
Only other’s selector fields become the scope: the outer locator’s strategy,
model and OCR engine govern the whole call. Raises ValueError when other
sets any of them.
locator.has()
Keep a match that contains other. Same rules as within().
locator.filter()
Add a natural-language query on top of the locator’s fields. A second filter
adds to the first query rather than replacing it.
phone.get_by_role("button").filter(query="the blue one at the bottom")
Returns Locator from each of these.
Actions
Each resolves the locator, waits until the target is actionable, then acts.
locator.tap()
Tap the target’s centre.
locator.tap(*, timeout=None)
Returns LocatorResult.
locator.fill()
Resolve and wait as tap() does, focus the target, then type text.
locator.fill(text, *, timeout=None)
Returns LocatorResult.
locator.press()
Focus the target, then press a named key. See Key.
locator.press(key, *, timeout=None)
Returns LocatorResult.
locator.wait_for()
Block on the phone until the locator reaches state.
locator.wait_for(*, state="visible", timeout=None)
| Parameter | Type | Default | Description |
|---|
state | WaitState | "visible" | "visible", "hidden" or "enabled". "enabled" reads the accessibility tree. |
timeout | float | None | 5000 | Milliseconds. |
Returns LocatorResult, or None for state="hidden".
WaitState is the type Literal["visible", "hidden", "enabled"].
Queries
locator.bounding_box()
Wait until the locator resolves, then report where the target is.
locator.bounding_box(*, timeout=None)
Returns LocatorResult; the box is its bounds.
locator.accessible_name() and locator.text()
Wait until the locator resolves through the accessibility tree, then return the
target’s accessible name. text() is the same call.
locator.accessible_name(*, timeout=None)
locator.text(*, timeout=None)
Returns str. Needs the tree.
locator.count()
How many targets match the current screen, zero included. Never waits;
timeout only bounds the call itself.
locator.count(*, timeout=None)
Returns int.
locator.selector
The DCP selector this locator sends. See Selectors.
Returns dict.
LocatorResult
What every action and query returns. A frozen dataclass.
| Field | Type | Description |
|---|
resolved_by | "a11y" | "ocr" | "vlm" | None | How the target was found: the accessibility tree, OCR, or a vision model. None when nothing was resolved. |
bounds | BBox | None | Where the target was when the phone acted, in screen pixels. |
took_ms | int | Time on the phone, waiting included. |
model_name | str | None | The model that resolved the target, set only when resolved_by is "vlm". |
input | str | None | The input backend that carried the action, when reported. |