Struct Locator 

pub struct Locator<'p> { /* private fields */ }

A lazy element descriptor that re-resolves against a fresh accessibility tree snapshot on every operation.

Inspired by Playwright’s Locator pattern: a Locator never holds a live reference to a UI element. Instead, it stores a selector and resolves it on demand, making it immune to staleness.

Example

let target = AppTarget::ByName("MyApp".into());
let save_btn = Locator::new(provider, target, "button[name=\"Save\"]");
save_btn.press()?;           // snapshot → query → press
save_btn.wait_visible(Duration::from_secs(5))?; // poll until visible
save_btn.press()?;           // re-resolves against fresh snapshot

Implementations

impl<'p> Locator<'p>

pub fn new( provider: &'p dyn Provider, target: AppTarget, selector: &str, ) -> Locator<'p>

Create a new Locator with default query options.

pub fn with_opts( provider: &'p dyn Provider, target: AppTarget, selector: &str, opts: QueryOptions, ) -> Locator<'p>

Create a new Locator with custom query options.

pub fn nth(self, n: usize) -> Locator<'p>

Return a new Locator that selects the nth match (0-based).

pub fn first(self) -> Locator<'p>

Return a new Locator that selects the first match. Equivalent to .nth(0) — mainly for readability.

pub fn child(self, child_selector: &str) -> Locator<'p>

Return a new Locator scoped to a direct child matching child_selector.

Appends > {child_selector} to the current selector.

pub fn descendant(self, desc_selector: &str) -> Locator<'p>

Return a new Locator scoped to a descendant matching desc_selector.

Appends {desc_selector} to the current selector.

pub fn selector(&self) -> &str

Get the selector string.

pub fn role(&self) -> Result<Role, Error>

Get the matched element’s role.

pub fn name(&self) -> Result<Option<String>, Error>

Get the matched element’s name.

pub fn value(&self) -> Result<Option<String>, Error>

Get the matched element’s value.

pub fn description(&self) -> Result<Option<String>, Error>

Get the matched element’s description.

pub fn bounds(&self) -> Result<Option<Rect>, Error>

Get the matched element’s bounding rectangle.

pub fn states(&self) -> Result<StateSet, Error>

Get the matched element’s state flags.

pub fn numeric_value(&self) -> Result<Option<f64>, Error>

Get the matched element’s numeric value (for range controls).

pub fn is_visible(&self) -> Result<bool, Error>

Check if the matched element is visible.

pub fn is_enabled(&self) -> Result<bool, Error>

Check if the matched element is enabled.

pub fn is_focused(&self) -> Result<bool, Error>

Check if the matched element is focused.

pub fn exists(&self) -> Result<bool, Error>

Check if a matching element exists in the current tree.

pub fn count(&self) -> Result<usize, Error>

Count matching elements in the current tree.

pub fn get(&self) -> Result<Node, Error>

Get a clone of the matched node from a fresh snapshot.

pub fn perform( &self, action: Action, data: Option<ActionData>, ) -> Result<(), Error>

Perform an arbitrary action on the matched element.

pub fn press(&self) -> Result<(), Error>

Click / invoke the matched element.

pub fn focus(&self) -> Result<(), Error>

Set keyboard focus on the matched element.

pub fn toggle(&self) -> Result<(), Error>

Toggle the matched element (checkbox, switch).

pub fn select(&self) -> Result<(), Error>

Select the matched element (list item, etc.).

pub fn expand(&self) -> Result<(), Error>

Expand the matched element.

pub fn collapse(&self) -> Result<(), Error>

Collapse the matched element.

pub fn set_value(&self, value: &str) -> Result<(), Error>

Set the text value of the matched element.

pub fn set_numeric_value(&self, value: f64) -> Result<(), Error>

Set the numeric value of the matched element (slider, spinner).

pub fn increment(&self) -> Result<(), Error>

Increment the matched element (slider, spinner).

pub fn decrement(&self) -> Result<(), Error>

Decrement the matched element (slider, spinner).

pub fn show_menu(&self) -> Result<(), Error>

Show the context menu for the matched element.

pub fn scroll_into_view(&self) -> Result<(), Error>

Scroll the matched element into view.

pub fn type_text(&self, text: &str) -> Result<(), Error>

Type text character-by-character on the matched element.

pub fn select_text(&self, start: u32, end: u32) -> Result<(), Error>

Select a text range within the matched element.

pub fn wait_visible(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element is visible, polling with fresh snapshots.

If the provider implements EventProvider, delegates to its wait_for method. Otherwise, polls at ~100ms intervals.

pub fn wait_attached(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element exists in the tree.

pub fn wait_detached(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element is removed from the tree.

pub fn wait_enabled(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element is enabled.

pub fn wait_disabled(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element is disabled (exists but not enabled).

pub fn wait_hidden(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element is hidden or removed.

pub fn wait_focused(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element has keyboard focus.

pub fn wait_unfocused(&self, timeout: Duration) -> Result<Node, Error>

Wait until the element does not have keyboard focus.

pub fn wait_for_state( &self, state: ElementState, timeout: Duration, ) -> Result<Node, Error>

Wait for an ElementState condition to be met.

pub fn wait_until( &self, predicate: impl Fn(Option<&Node>) -> bool, timeout: Duration, ) -> Result<Node, Error>

Wait until an arbitrary predicate is satisfied, polling with fresh snapshots at ~100 ms intervals.

The predicate receives Some(&Node) when the selector matches, or None when no element matches. Return true to stop waiting.

Example

// Wait until the element's value becomes "Done":
let node = loc.wait_until(
    |n| n.is_some_and(|n| n.value.as_deref() == Some("Done")),
    Duration::from_secs(5),
)?;