Locator

Selector-based query for finding elements in the JAB accessibility tree.

Uses a CSS-selector-like syntax to describe element attributes — role, states, pseudo-classes, and attribute comparisons — all in a single string.

Usually created via JabDriver.locator(). Call .locator() again on the result to extend the query with a descendant combinator (space):

loc = driver.locator("push_button[name='Clear']")
loc.wait_for()
loc.click()

# Chaining adds a descendant combinator:
loc = driver.locator("dialog").locator("push_button")
loc.wait_for()
# Equivalent to: driver.locator("dialog push_button")

__init__ 

__init__(
    driver: JabDriver,
    selector: str,
    has: list["Locator"] | None = None,
    require_states: set[AccessibleState] | None = None,
    exclude_states: set[AccessibleState] | None = None,
)

Wrap a driver and a selector string.

Parameters:
  • driver (JabDriver) –

    The JabDriver instance.

  • selector (str) –

    A CSS-selector-like query string (e.g. "push_button[name='Clear']").

  • has (list['Locator'] | None, default: None ) –

    A list of locators; each matching element must contain a descendant that satisfies every locator in the list. Appends :has() pseudo-classes to the selector (AND semantics).

  • require_states (set[AccessibleState] | None, default: None ) –

    A set of states an element matching this locator must have

  • exclude_states (set[AccessibleState] | None, default: None ) –

    A set of states an element matching this locator must not have

accessible_click 

accessible_click(
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> None

Click a matching element via the JAB accessibility API.

This does not move the mouse — the click is performed programmatically through the accessibility bridge.

Parameters:
  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.

  • JabInternalError –

    The action could not be performed.

click 

click(
    clicks: int = 1,
    interval: int | float = 0.0,
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> None

Click at a matching element's center using pyautogui.

Moves the mouse to the center of a matching element's bounding box and performs a pyautogui click.

Parameters:
  • clicks (int, default: 1 ) –

    Number of clicks (default 1).

  • interval (int | float, default: 0.0 ) –

    Seconds between clicks (default 0.0).

  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.

click_and_type 

click_and_type(
    text: str,
    clicks: int = 1,
    interval_text: int | float = 0.0,
    interval_clicks: int | float = 0.0,
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> None

Click then type text into a matching element using pyautogui.

Moves the mouse to a matching element's center, clicks, then types the given text.

Parameters:
  • text (str) –

    Text to type after clicking.

  • clicks (int, default: 1 ) –

    Number of clicks before typing (default 1).

  • interval_text (int | float, default: 0.0 ) –

    Seconds between keystrokes (default 0.0).

  • interval_clicks (int | float, default: 0.0 ) –

    Seconds between clicks (default 0.0).

  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.

do_accessible_action 

do_accessible_action(
    action: Action,
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> None

Perform an accessible action on a matching element.

Parameters:
  • action (Action) –

    The Action to perform (e.g. Action("click")).

  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.

  • JabInternalError –

    The action could not be performed.

exists 

exists() -> bool
Returns:
  • bool –

    True if a matching element exists,

  • bool –

    False otherwise
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

filter 

filter(
    has: list["Locator"] | None = None,
    require_states: set[AccessibleState] | None = None,
    exclude_states: set[AccessibleState] | None = None,
) -> "Locator"

Extend the query by requiring more states/sub-locators.

Parameters:
  • has (list['Locator'] | None, default: None ) –

    A list of locators; each matching element must contain a descendant that satisfies every locator in the list. Appends :has() pseudo-classes to the selector (AND semantics).

  • require_states (set[AccessibleState] | None, default: None ) –

    A set of states an element matching this locator must have

  • exclude_states (set[AccessibleState] | None, default: None ) –

    A set of states an element matching this locator must not have
Returns:
  • 'Locator' –

    A new Locator with the added filtering.

get_actions 

get_actions(
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> list[Action]

Get available accessible actions from the first matching element.

Parameters:
  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Returns:
  • list[Action] –

    List of Action objects (each has a name field).
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.

get_info 

get_info(
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> AccessibleInfo

Get accessible info from the first matching element.

Parameters:
  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Returns:
  • AccessibleInfo –

    AccessibleInfo with name, role, states, coordinates, etc.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.

get_info_from_all 

get_info_from_all() -> list[AccessibleInfo]

Get accessible info from all matching elements. Does not wait for a matching element, returns immediately.

Returns:
  • list[AccessibleInfo] –

    List of AccessibleInfo for every matching element.

  • list[AccessibleInfo] –

    Empty list if no element matches.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

get_text 

get_text(
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> str

Get accessible text from the first matching element.

Parameters:
  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Returns:
  • str –

    Accessible text content.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.

locator 

locator(
    selector: str,
    has: list["Locator"] | None = None,
    require_states: set[AccessibleState] | None = None,
    exclude_states: set[AccessibleState] | None = None,
) -> "Locator"

Extend the query with a descendant combinator.

Concatenates the new selector with a space, equivalent to a descendant combinator in CSS.

Parameters:
  • selector (str) –

    Additional CSS-like selector to append.

  • has (list['Locator'] | None, default: None ) –

    A list of locators; each matching element must contain a descendant that satisfies every locator in the list. Appends :has() pseudo-classes to the selector (AND semantics).

  • require_states (set[AccessibleState] | None, default: None ) –

    A set of states an element matching this locator must have

  • exclude_states (set[AccessibleState] | None, default: None ) –

    A set of states an element matching this locator must not have
Returns:
  • 'Locator' –

    A new Locator with the combined selector.

race 

race(
    others: list["Locator"],
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> int

Wait for any of the given locators to have a match.

Parameters:
  • others (list['Locator']) –

    List of Locators.

  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait, or a positive integer for max milliseconds.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Returns:
  • int –

    Index of the first locator that matched (self -> 0, others -> 1..)
Raises:
  • JabInvalidArgumentError –

    One or more locator selectors are malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    No locator matched within the timeout.

to_dict 

to_dict() -> dict[str, Any]

All locator criteria as a dictionary.

wait_for 

wait_for(
    timeout_ms: int | None = None,
    refresh_before_fail: bool = True,
) -> None

Block until a matching element appears in the accessibility tree.

Parameters:
  • timeout_ms (int | None, default: None ) –

    None for default (60s), 0 for no wait (fail fast), or a positive integer for max milliseconds to wait.

  • refresh_before_fail (bool, default: True ) –

    If true, refresh the tree after timeout before the final check.
Raises:
  • JabInvalidArgumentError –

    The selector string is malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    The element did not appear within the timeout.