JabDriver

High-level driver that manages the JAB server and provides the main entry point.

Requires a binary package to be installed (e.g. pip install jab-rpa[java8]).

JabDriver handles the full lifecycle:

  1. Locates the server binary (from the installed binary package)
  2. Spawns the jab-rpa-server.exe subprocess
  3. Waits for a Java window matching the given title regex
  4. Brings the window to the foreground and maximizes it
  5. Selects the window on the server to build the accessibility tree

Typical usage:

with JabDriver("MyApp.*") as driver:
    loc = driver.locator("push_button[name='Clear']")
    loc.wait_for()
    loc.click()

__init__ 

__init__(
    window_title: str | Pattern[str],
    *,
    java_bitness: Literal["32 bit", "64 bit"] = "32 bit",
    java_version: Literal[
        "8", "11", "17", "21", "25"
    ] = "8",
    server_address: str = "127.0.0.1",
    server_port: str = "50051",
    server_timeout: int = _WAIT_FOR_SERVER_TIMEOUT,
    server_step: int = _INIT_SERVER_STEP,
    window_timeout: int = _WAIT_FOR_WINDOW_TIMEOUT,
    window_step: int = _WAIT_FOR_WINDOW_STEP,
) -> None

Configure the driver.

Parameters:
  • window_title (str | Pattern[str]) –

    Regex pattern to match against Java window titles. The first window whose title matches via re.search() is selected. Can be a string or compiled pattern.

  • java_bitness (Literal['32 bit', '64 bit'], default: '32 bit' ) –

    "32 bit" (default) or "64 bit". Controls which pre-built server binary is used.

  • java_version (Literal['8', '11', '17', '21', '25'], default: '8' ) –

    "8" (default), "11", "17", "21", or "25". Java version the target application runs on. Only Java 8 has been proven to work reliably in production.

  • server_address (str, default: '127.0.0.1' ) –

    Server bind address (default "127.0.0.1").

  • server_port (str, default: '50051' ) –

    Server bind port (default "50051").

  • server_timeout (int, default: _WAIT_FOR_SERVER_TIMEOUT ) –

    Maximum seconds to wait for the server to start.

  • server_step (int, default: _INIT_SERVER_STEP ) –

    Seconds between server readiness checks.

  • window_timeout (int, default: _WAIT_FOR_WINDOW_TIMEOUT ) –

    Maximum seconds to wait for a matching window.

  • window_step (int, default: _WAIT_FOR_WINDOW_STEP ) –

    Seconds between window discovery polls.

get_version_info 

get_version_info() -> VersionInfo | None

Get version info for the JAB bridge and server.

Returns:
  • VersionInfo | None –

    VersionInfo if available, or None.
Raises:
  • JabNoWindowError –

    No window has been selected yet.

  • JabInternalError –

    The version info call failed.

list_java_windows 

list_java_windows() -> list[WindowInfo]

List all Java windows currently detected by the server.

Returns:
  • list[WindowInfo] –

    List of WindowInfo with hwnd and title.

locator 

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

Build a locator to find elements in the accessibility tree.

Parameters:
  • 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
Returns:
  • Locator –

    A Locator bound to this driver.

race 

race(
    locators: 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:
  • locators (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.
Raises:
  • JabInvalidArgumentError –

    One or more locator selectors are malformed.

  • JabNoWindowError –

    No window has been selected yet.

  • JabTimeoutError –

    No locator matched within the timeout.

refresh_tree 

refresh_tree() -> None

Rebuild the cached accessibility tree on the server.

Call this after UI changes (e.g. a dialog opens) so subsequent locator queries see the updated tree.

Raises:
  • JabNoWindowError –

    No window has been selected yet.

  • JabInternalError –

    The tree has no root node.

start 

start() -> None

Start the server and connect to the target window.

Spawns the JAB gRPC server, polls for Java windows whose title matches window_title, brings the first match to the foreground, maximizes it, and selects it on the server.

Raises:

stop 

stop() -> None

Stop the client and terminate the server.

switch_window 

switch_window(window_info: WindowInfo) -> None

Set the active window to build the accessibility tree from.

Parameters:
  • window_info (WindowInfo) –

    A WindowInfo from list_java_windows().
Raises:
  • JabInvalidArgumentError –

    The HWND does not belong to a Java window.

  • JabInternalError –

    The JAB bridge call failed.

Bases: Exception

Raised when no Java window matching the given title is found within the timeout.