uiautodev Documentation

The uiautodev repository is organized into the following core components:

• binaries/: Contains binary files.
• driver/: Contains drivers for different types of devices.
• remote/: Contains remote-related code (extracted from driver).
• router/: Encapsulates drivers into an interface.
• app.py: The entry point for the FastAPI application.
• cli.py: Contains CLI-related logic.

The development server defaults to port 20242.

To start the local inspector server and automatically open your web browser, run:

uiauto.dev

Install the core package via pip:

pip install uiautodev

If you require support for HarmonyOS, install the package with the harmony extra:

pip install "uiautodev[harmony]"

For HarmonyOS support, refer to the official Huawei Hypium Python guidelines.

By default, uiautodev uses U2AndroidDriver. You can switch the default driver to ADBAndroidDriver by setting the UIAUTODEV_USE_ADB_DRIVER environment variable to 1, true, or True before starting the server.

export UIAUTODEV_USE_ADB_DRIVER=true
python -m uiautodev.app

To set up the uiautodev development environment on Windows, you must install poetry and make (via Chocolatey) before running the project tasks.

Follow these steps:

1. Install poetry using pip.
2. Install project dependencies using poetry install.
3. Install make using Chocolatey (choco install make).
4. Format imports using make format.
5. Start the development server using make dev.

Note: The server runs on a fixed port 20242.

# install poetry (python package manager)
pip install poetry

# install deps
poetry install

# install make, choco
choco install make

# format import
make format

# run server
make dev

You can run the server in offline mode to ensure that disconnecting from the internet does not affect usage. To do this, visit <http://localhost:20242> at least once while online to cache frontend resources in the cache/ directory.

To start the server in offline mode:

uiauto.dev server --offline

If you need to specify a custom server URL while in offline mode:

uiauto.dev server --offline --server-url https://uiauto.dev

To set up the uiautodev development environment on Mac or Linux, you need to install poetry for dependency management and use make to run development tasks.

Follow these steps:

1. Install poetry using pip.
2. Install project dependencies using poetry install.
3. Format imports using make format.
4. Start the development server using make dev.

Note: The server runs on a fixed port 20242.

# install poetry (python package manager)
pip install poetry

# install deps
poetry install

# format import
make format

# run server
make dev

By default, uiautodev uses the uiautomator2 driver for Android. To switch to the adb driver, set the UIAUTODEV_USE_ADB_DRIVER environment variable to 1.

export UIAUTODEV_USE_ADB_DRIVER=1

The proxy intercepts all HTTP methods (GET, POST, PUT, DELETE, OPTIONS, HEAD, PATCH, TRACE) and forwards them to the target server.

Compatibility Note: If a request path ends with /execute/sync, the proxy intercepts it and returns a 404 response with a specific JSON error body instead of forwarding it. This prevents issues with older Appium versions or services like BrowserStack that do not support this specific endpoint.

Error Response for /execute/sync:

{
  "value": {
    "error": "unknown command",
    "message": "unknown command",
    "stacktrace": "UnknownCommandError"
  }
}

The BaseProvider is an abstract base class used to discover devices and obtain driver instances for different mobile platforms. You can implement or use specific provider subclasses to interact with Android, iOS, or HarmonyOS devices.

Key methods available in provider implementations:

• list_devices() -> list[DeviceInfo]: Returns a list of available devices and their metadata.
• get_device_driver(serial: str) -> BaseDriver: Returns a driver instance for the specified device serial.
• get_single_device_driver() -> BaseDriver: A convenience method that returns a driver for the only available device. It raises UiautoException if zero or multiple devices are found.

from uiautodev.provider import AndroidProvider

# Initialize the provider
provider = AndroidProvider()

# Get a driver for the single connected device
driver = provider.get_single_device_driver()

Use the following commands to manage the lifecycle of the local uiautodev server:

• server: Starts the local server. If no command is provided to the CLI, it defaults to running the server command.
• shutdown: Sends a shutdown request to the server running on the specified port.
• self-update: Upgrades the uiautodev package to the latest version using pip.

# Shutdown the server running on port 20242
uiautodev shutdown --port 20242

# Update the package
uiautodev self-update

The uiautodev CLI allows you to execute driver commands directly on connected devices. You can target different platforms using the android, ios, or appium commands.

Each command requires a command (of type Command) and optional params. If a command requires parameters, they must be provided as positional arguments following the command name. The CLI validates these parameters against a Pydantic model schema.

To see available commands for a platform, run the command with the --help flag.

# Example: Running an Android command
# Replace <command> and <params> with actual values
uiautodev android <command> <param1> <param2>

# Example: Running an iOS command
uiautodev ios <command> <param1>

# Example: Running an Appium command
uiautodev appium <command> <param1>