AndroidDriver

Raw Android device I/O over ADB, with optional Mobilerun Portal enhancement.

class AndroidDriver(DeviceDriver)

AndroidDriver controls Android devices through ADB. Portal is optional and adds Unicode text input, app labels, richer UI state, and overlay-aware screenshots. Import the driver from mobilerun-core-local:

from mobilerun_core_local import AndroidDriver

Constructor

driver = AndroidDriver(
    serial=None,
    use_tcp=False,
    portal_mode="auto",
)

Arguments:

serial — ADB serial, such as emulator-5554, a USB serial, or an ADB-over-network address.
use_tcp — Use Portal HTTP through an ADB port forward when available.
portal_mode — "auto", "required", or "disabled".

Portal modes

Mode	Connection behavior
`auto`	Use Portal when available; otherwise use ADB.
`required`	Stop with an error if Portal or its keyboard is unavailable.
`disabled`	Use ADB only and skip Portal setup.

An invalid mode raises ValueError. In Framework configuration, portal_mode="disabled" also skips automatic Portal setup. Examples:

# Use Portal when available
driver = AndroidDriver(serial="emulator-5554", portal_mode="auto")

# Use ADB only
driver = AndroidDriver(serial="emulator-5554", portal_mode="disabled")

# Require Portal and prefer its HTTP transport
driver = AndroidDriver(
    serial="emulator-5554",
    use_tcp=True,
    portal_mode="required",
)

Supported methods

AndroidDriver.supported = {
    "tap",
    "swipe",
    "input_text",
    "press_button",
    "press_key_code",
    "start_app",
    "install_app",
    "stop_app",
    "uninstall_app",
    "get_apps",
    "list_packages",
    "screenshot",
    "get_ui_tree",
    "get_date",
}

AndroidDriver.supported_buttons = {"back", "home", "enter"}

drag() is not supported. Use swipe() instead.

Lifecycle

AndroidDriver.connect

async def connect() -> None

Select and verify an online ADB device. Unless Portal is disabled, the driver connects to Portal and configures its keyboard. In auto mode, connection continues through ADB if Portal is unavailable. In required mode, it raises an error.

AndroidDriver.ensure_connected

async def ensure_connected() -> None

Connect once if necessary. It is safe to call repeatedly.

Input actions

AndroidDriver.tap

async def tap(x: int, y: int) -> None

Tap at absolute Android display-pixel coordinates through ADB.

AndroidDriver.swipe

async def swipe(
    x1: int,
    y1: int,
    x2: int,
    y2: int,
    duration_ms: float = 1000,
) -> None

Swipe between two absolute points over duration_ms milliseconds.

AndroidDriver.input_text

async def input_text(text: str, clear: bool = False) -> bool

Type into the focused field and return True on success.

When the Portal keyboard is available, text input supports Unicode.
If Portal input fails in auto mode, the driver switches to ADB text input.
ADB-only input supports printable ASCII. It rejects control/non-ASCII characters and the literal substring %s, which Android reserves as a space escape.
clear=True clears the focused field first when possible.

AndroidDriver.press_button

async def press_button(button: str) -> None

Press back, home, or enter (case-insensitive). An unknown name raises ValueError.

AndroidDriver.press_key_code

async def press_key_code(key_code: int) -> None

Send an Android integer key code through ADB.

AndroidDriver.drag

drag() raises NotImplementedError. Use swipe() instead.

App management

AndroidDriver.start_app

async def start_app(package: str, activity: str | None = None) -> str

Launch an Android package through ADB. If activity is omitted, Mobilerun opens the app’s launcher activity. It raises RuntimeError when the app cannot be launched.

AndroidDriver.install_app

async def install_app(path: str, **kwargs) -> str

Install a local APK through ADB. reinstall=False and grant_permissions=True are the defaults. A missing path raises FileNotFoundError.

grant_permissions=True grants eligible runtime permissions. Grant special access such as Accessibility, Display over other apps, Notification Access, Install unknown apps, and screen-capture consent on the device.

AndroidDriver.stop_app

async def stop_app(package: str) -> str

Force-stop a package with am force-stop.

AndroidDriver.uninstall_app

async def uninstall_app(package: str) -> str

Uninstall a package with pm uninstall.

AndroidDriver.list_packages

async def list_packages(include_system: bool = False) -> list[str]

List package names through ADB. By default, only third-party packages are returned.

AndroidDriver.get_apps

async def get_apps(include_system: bool = True) -> list[dict[str, str]]

Return {"package": ..., "label": ...} records. Portal supplies display labels when available. Without Portal, package names are used for both fields.

State and observation

AndroidDriver.screenshot

async def screenshot(hide_overlay: bool = True) -> bytes

Return raw PNG bytes. Portal can hide its overlay when hide_overlay=True. In auto mode, the driver uses an ADB screenshot if Portal is unavailable.

AndroidDriver.get_ui_tree

async def get_ui_tree() -> dict[str, object]

Return the accessibility tree, phone state, and device context. ADB-only results may contain less detail than Portal results.

AndroidDriver.get_date

async def get_date() -> str

Return the output of the device’s ADB date command.

Portal transport

use_tcp=True uses Portal HTTP over an ADB port forward. In auto mode, Mobilerun uses the ContentProvider or ADB if HTTP is unavailable. Authentication is handled automatically. See the Portal Local API for direct API access.

Example

import asyncio
from mobilerun_core_local import AndroidDriver

async def main() -> None:
    driver = AndroidDriver(
        serial="emulator-5554",
        portal_mode="auto",
        use_tcp=True,
    )
    await driver.connect()

    await driver.start_app("com.android.settings")
    await driver.tap(540, 300)
    await driver.input_text("Mobilerun")
    await driver.press_button("enter")

    png = await driver.screenshot()
    with open("screen.png", "wb") as output:
        output.write(png)

asyncio.run(main())

For element-based actions, see DeviceDriver and actions.

Introduction

Features

Guides

Concepts

SDK Reference

AndroidDriver

AndroidDriver

Constructor

Portal modes

Supported methods

Lifecycle

AndroidDriver.connect

AndroidDriver.ensure_connected

Input actions

AndroidDriver.tap

AndroidDriver.swipe

AndroidDriver.input_text

AndroidDriver.press_button

AndroidDriver.press_key_code

AndroidDriver.drag

App management

AndroidDriver.start_app

AndroidDriver.install_app

AndroidDriver.stop_app

AndroidDriver.uninstall_app

AndroidDriver.list_packages

AndroidDriver.get_apps

State and observation

AndroidDriver.screenshot

AndroidDriver.get_ui_tree

AndroidDriver.get_date

Portal transport

Example

​AndroidDriver

​Constructor

​Portal modes

​Supported methods

​Lifecycle

​AndroidDriver.connect

​AndroidDriver.ensure_connected

​Input actions

​AndroidDriver.tap

​AndroidDriver.swipe

​AndroidDriver.input_text

​AndroidDriver.press_button

​AndroidDriver.press_key_code

​AndroidDriver.drag

​App management

​AndroidDriver.start_app

​AndroidDriver.install_app

​AndroidDriver.stop_app

​AndroidDriver.uninstall_app

​AndroidDriver.list_packages

​AndroidDriver.get_apps

​State and observation

​AndroidDriver.screenshot

​AndroidDriver.get_ui_tree

​AndroidDriver.get_date

​Portal transport

​Example

AndroidDriver

Constructor

Portal modes

Supported methods

Lifecycle

AndroidDriver.connect

AndroidDriver.ensure_connected

Input actions

AndroidDriver.tap

AndroidDriver.swipe

AndroidDriver.input_text

AndroidDriver.press_button

AndroidDriver.press_key_code

AndroidDriver.drag

App management

AndroidDriver.start_app

AndroidDriver.install_app

AndroidDriver.stop_app

AndroidDriver.uninstall_app

AndroidDriver.list_packages

AndroidDriver.get_apps

State and observation

AndroidDriver.screenshot

AndroidDriver.get_ui_tree

AndroidDriver.get_date

Portal transport

Example