Locator & Element
Locator and Element are the two ways to reach a node in the accessibility
tree. This page lists what each one offers. Full signatures, including
parameter types and defaults, are in the generated API reference:
Rust, Python,
JavaScript.
For the model behind the two, see How xa11y works.
Locator
Section titled “Locator”Created by app.locator(selector), or by the module-level
xa11y.locator(selector) for a search rooted at the system rather than at one
application. A Locator re-resolves its selector on every operation.
Actions
Section titled “Actions”press(), focus(), blur(), toggle(), select(), expand(),
collapse(), set_value(), set_numeric_value(), type_text(),
select_text(), increment(), decrement(), show_menu(),
scroll_into_view(), perform_action(name).
Each auto-waits for the target to be visible and enabled before dispatching.
The exception is scroll_into_view(), which waits for attached and enabled
alone: an off-screen element is what it exists to bring on-screen, so gating it
on visibility would never resolve.
Which platform API each verb reaches is in Platform Details.
wait_visible(), wait_hidden(), wait_attached(), wait_detached(),
wait_enabled(), wait_disabled(), wait_focused(), wait_unfocused(),
wait_until().
Each polls until the condition holds or the timeout expires, then raises
Timeout with a diagnosis. wait_until() takes a predicate over the resolved
element, which is None when the selector did not match.
Rust adds wait_for_state(), a generic wait over the ElementState enum. The
bindings expose the specific wait_* helpers above and wait_until() in its
place.
Queries
Section titled “Queries”| Method | Returns |
|---|---|
element() |
The first match in document order, or the nth() index when one is set. Raises SelectorNotMatched when there is none. Several matches is not an error. |
elements() |
Every match |
exists() |
Boolean |
count() |
Number of matches |
Chaining
Section titled “Chaining”nth(n), first(), child(selector), descendant(selector).
child() and descendant() distribute over every clause of an alternation
selector. See Selectors.
Element
Section titled “Element”A live handle returned by app.children(), element.children(),
element.parent(), locator.element(), or locator.elements().
Properties
Section titled “Properties”| Property | Type |
|---|---|
role |
Normalized role, snake_case |
name |
String, optional |
value |
String, optional |
description |
String, optional |
bounds |
Rect (x, y, width, height), optional |
states |
State set (enabled, visible, focused, and the rest) |
actions |
List of action names this element supports |
numeric_value |
Number, optional |
min_value |
Number, optional |
max_value |
Number, optional |
stable_id |
String, optional |
pid |
Process ID of the owning application |
raw |
Platform-native key/value map |
name, value, and description are stripped of Unicode bidi format
controls. raw holds the unstripped platform string under the platform-native
key. Each of these properties except raw, states, and actions is also
usable as a selector attribute, along with the individual state flags.
pid is the exception, having no attribute of its own. See
Selectors.
Navigation and snapshots
Section titled “Navigation and snapshots”| Method | Returns |
|---|---|
children() |
Direct children, queried from the platform on each call |
parent() |
The parent element |
tree(max_depth) |
The subtree as a structured snapshot (role, name, value, children) |
dump(max_depth) |
The same snapshot as an indented string |
max_depth of 0 returns the root node alone, 1 adds its direct children,
and so on. Omit it for the full subtree. tree() and dump() are also
available on App and Locator.
Actions
Section titled “Actions”The same action verbs listed for Locator are available on Element. The
difference is what they act on:
Locator |
Element |
|
|---|---|---|
| Selector | Re-resolved on every call | Not applicable; the handle is fixed |
| Auto-wait | Waits for visible and enabled | None |
| Handle went away | Re-resolves against the current tree | Raises ElementStale |
Default timeout
Section titled “Default timeout”Auto-waiting actions, the wait_* family, and application lookup share one
process-wide default of 5 seconds. Resolution runs from most to least
specific: an explicit per-call timeout argument, then
set_default_timeout(), then the XA11Y_DEFAULT_TIMEOUT environment variable
(seconds, read once at startup), then the built-in 5 seconds. A timeout of 0
means a single attempt with no polling.
An unparsable XA11Y_DEFAULT_TIMEOUT raises InvalidConfig. See
Errors.