uiautomator2 Documentation

To develop locally on the uiautomator2 repository, clone the repository, install dependencies using poetry, and sync the required assets (such as APKs) using make.

git clone https://github.com/openatx/uiautomator2
cd uiautomator2

pip install poetry
poetry install

# download apk to assets/
make sync

# run python shell after device or emulator connected
poetry run uiautomator2 console

When working with the uiautomator2 XPath extension, you can use the following external resources to practice and learn advanced XPath syntax:

• XPath Playground: An interactive environment to test your XPath expressions.
• Some Advanced Uses of XPath: A guide for more complex queries.
• XPath Quicksheet: A reference for common XPath syntax and functions.

To use uiautomator2, ensure an Android device with Developer Options enabled is connected and visible via adb devices.

Basic usage pattern:

1. Import uiautomator2.
2. Connect to the device using u2.connect().
3. Perform actions like starting apps, waiting for activities, or interacting with elements via XPath.

To use XPath capabilities in uiautomator2, ensure you have the library installed. The XPath extension is part of the main package.

pip3 install -U uiautomator2

The uiautomator2 XPath extension provides several shorthand rules to speed up script writing:

• Standard XPath: Start with // (e.g., //android.widget.TextView).
• Resource ID: Start with @ to target resource-id (e.g., @android:id/list is equivalent to //*[@resource-id="android:id/list"]).
• Regex: Start with ^ to use regular expressions (e.g., ^.*道了 matches text starting with anything and ending in '道了').
• SQL-like Wildcards:
  • text%: Starts with text (equivalent to starts-with(text(), 'text')).
  • %text: Ends with text (equivalent to ends-with(text(), 'text')).
  • %text%: Contains text (equivalent to contains(text(), 'text')).
• Text/Description Match: Using a bare string like 搜索 matches if text, content-desc, or resource-id contains that string.

The u2cli is a lightweight CLI wrapper designed for agent workflows to view and control devices without writing Python code. It uses a local server to maintain device connections and reuse them across multiple commands.

# Start the u2cli server
u2cli start-server

# Check server status
u2cli server-status

# Kill the server
u2cli kill-server

# Common commands
u2cli device-info
u2cli screenshot screen.png
u2cli dump-hierarchy
u2cli click --text Settings

The u2cli tool is used to automate Android devices. When multiple devices are connected, use the -s <serial> flag to specify the target device.

Basic Syntax: u2cli <command> [args] u2cli -s <serial> <command> [args]

The following changes affect XPath and InputMethod usage:

XPath (d.xpath) changes:

• Removed methods: dump_hierarchy, get_last_hierarchy, add_event_listener, send_click, send_longclick, send_swipe, send_text, take_screenshot, when, run_watchers, watch_background, watch_stop, watch_clear, sleep_watch, and the position method.
• Behavior change: d.xpath("...").wait() now returns a bool instead of XMLElement|None.

InputMethod changes:

• wait_fastinput_ime is deprecated.
• Use set_input_ime instead of the deprecated set_fastinput_ime.

You can connect to a device using several methods:

1. Using Serial Number

Pass the serial number (from adb devices) to u2.connect(). This is an alias for u2.connect_usb().

import uiautomator2 as u2
d = u2.connect('Q5S5T19611004599')

To connect via a non-default port (default is 9008):

d = u2.connect('Q5S5T19611004599', port=9009)

2. Using Environment Variable

Set the ANDROID_SERIAL environment variable to automatically connect without passing arguments.

# export ANDROID_SERIAL=Q5S5T19611004599
python
>>> import uiautomator2 as u2
>>> d = u2.connect()

3. Using transport_id

If you have the transport_id from adb devices -l, you can use adbutils to connect.

import adbutils
import uiautomator2 as u2

dev = adbutils.device(transport_id=6)
d = u2.connect(dev)