Quickstart

Installation

Install from PyPI with the appropriate Java version extra:

pip install jab-rpa[java8]      # Java 8 (proven in production)
pip install jab-rpa[java11]     # Java 11
pip install jab-rpa[java17]     # Java 17
pip install jab-rpa[java21]     # Java 21
pip install jab-rpa[java25]     # Java 25

The extra selects which pre-built server binary is included. Each binary package contains both 32-bit and 64-bit builds for the given Java version.

Prerequisites

On your Windows machine, enable Java Access Bridge:

jabswitch -enable

Basic usage

from jab_rpa import JabDriver

with JabDriver("My Java Application.*") as driver:
    locator = driver.locator("push_button[name='Clear']")
    locator.click()

What's happening

1. JabDriver("My Java Application.*") — locates the server binary (provided by the installed binary package, e.g. jab-rpa-bin-java8), spawns it, waits for a Java window whose title matches the regex "My Java Application.*", then brings it to the foreground and maximizes it.
2. driver.locator("push_button[name='Clear']") — builds a locator query using CSS-selector-like syntax (see Selector syntax).
3. .click() — polls until a matching element appears in the accessibility tree, moves the mouse to the matching element's center and clicks via pyautogui.

Waiting for elements

# Wait up to 30 seconds (default: 60s)
locator.wait_for(timeout_ms=30_000)

# Wait with no timeout (fail fast if element doesn't exist yet)
locator.wait_for(timeout_ms=0)

Interacting with elements

# Accessible click (uses JAB API directly — no mouse movement)
locator.accessible_click()

# Coordinate click (uses pyautogui)
locator.click()
locator.click(clicks=2, interval=0.5)

# Click and type text
locator.click_and_type("hello world")

Accessible actions

Elements may expose additional actions beyond clicking (e.g. "toggle", "expand", "select"):

# List available actions
actions: list[Action] = locator.get_actions()
for action in actions:
    print(action.name)

# Perform a specific action by name
locator.do_accessible_action(action)

Getting element info

info = locator.get_info()

print(info.name)                # Accessible name
print(info.role)                # e.g. "push_button"
print(info.states)              # Localized states
print(info.states_en_us)        # en-US states
print(info.description)         # Accessible description
print(info.x, info.y)           # Screen coordinates
print(info.width, info.height)
print(info.index_in_parent)
print(info.children_count)
print(info.to_dict())           # All properties as dict

The Locator also supports querying across all matching nodes or retrieving specific fields:

# Get info from all matching elements
all_info = locator.get_info_from_all()

# Get accessible text directly
text = locator.get_text()

# Get available actions
actions = locator.get_actions()

Driver utilities

# List all detected Java windows
for w in driver.list_java_windows():
    print(w.hwnd, w.title)

# Switch to a different window
driver.switch_window(some_window_info)

# Rebuild the accessibility tree (call after UI changes)
driver.refresh_tree()

# Get JAB bridge and server version info
info = driver.get_version_info()

Error handling

The library defines 8 custom exceptions:

Exception	Raised when
WindowNotFound	No Java window matches the given title pattern
ServerStoppedError	The jab-rpa-server.exe process exits prematurely
JabError	Base exception for all jab-rpa server-side errors
JabInvalidArgumentError	Invalid argument
JabNoWindowError	No window selected
JabElementNotFoundError	Element not found
JabTimeoutError	Operation timed out
JabInternalError	Internal server error

from jab_rpa import JabDriver
from jab_rpa.driver import WindowNotFound

try:
    with JabDriver("MyApp.*") as driver:
        loc = driver.locator("push_button[name='Clear']")
        loc.wait_for()
except WindowNotFound:
    print("Application not running")