IOSDriver API Reference

IOSDriver

class IOSDriver(DeviceDriver)

iOS device driver communicating via HTTP REST to the iOS Portal app. Unsupported methods:

drag() — not in supported set
install_app() — not in supported set
press_button() — home only

IOSDriver.init

def __init__(
    url: str,
    bundle_identifiers: List[str] | None = None
) -> None

Initialize the IOSDriver instance. Arguments:

url str - iOS Portal URL (e.g., “http://127.0.0.1:6643”)
bundle_identifiers List[str] | None - Optional list of custom app bundle identifiers

Usage:

from mobilerun.tools.driver import IOSDriver

# Connect via iproxy
driver = IOSDriver(url="http://127.0.0.1:6643")

# With specific bundle identifiers
driver = IOSDriver(
    url="http://127.0.0.1:6643",
    bundle_identifiers=["com.example.app1", "com.example.app2"]
)

Supported methods:

IOSDriver.supported = {
    "tap", "swipe", "input_text", "press_button",
    "start_app", "screenshot", "get_ui_tree",
    "list_packages", "get_apps", "get_date",
}

IOSDriver.supported_buttons = {"home"}

Setup Requirements:

Build and run the iOS Portal via Xcode (runs as a UI test)
Forward port with iproxy 6643 6643
Use http://127.0.0.1:6643 as the URL

See Device Setup — iOS for full instructions.

Lifecycle Methods

IOSDriver.connect

async def connect() -> None

Create an HTTP client and verify connectivity by calling /device/date.

IOSDriver.ensure_connected

async def ensure_connected() -> None

Connect if not already connected. Safe to call multiple times.

Input Action Methods

IOSDriver.tap

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

Tap at coordinates. Arguments:

x int - X coordinate
y int - Y coordinate

Usage:

await driver.tap(200, 400)

IOSDriver.swipe

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

Swipe from one point to another. Arguments:

x1 int - Starting X coordinate
y1 int - Starting Y coordinate
x2 int - Ending X coordinate
y2 int - Ending Y coordinate
duration_ms float - Duration in milliseconds

Usage:

# Swipe up (scroll down)
await driver.swipe(200, 800, 200, 200)

# Swipe left
await driver.swipe(600, 400, 100, 400)

IOSDriver.input_text

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

Input text into the currently focused element. Arguments:

text str - Text to input (supports Unicode)
clear bool - Clear existing text before input

Returns:

bool - True if input succeeded, False otherwise

Usage:

# Tap text field first
await driver.tap(200, 400)

# Input text
success = await driver.input_text("Hello World")

# Clear field and type new text
success = await driver.input_text("new text", clear=True)

IOSDriver.press_button

async def press_button(button: str) -> None

Press a named system button. Supported buttons: home Raises ValueError for unsupported button names. Arguments:

button str - Button name (case-insensitive)

Usage:

await driver.press_button("home")

App Management Methods

IOSDriver.start_app

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

Launch an app by bundle identifier. Arguments:

package str - Bundle identifier (e.g., “com.apple.MobileSMS”)
activity str | None - Ignored on iOS (for API compatibility)

Returns:

str - Result message

Common bundle identifiers:

Messages: com.apple.MobileSMS
Safari: com.apple.mobilesafari
Settings: com.apple.Preferences
Calendar: com.apple.mobilecal
Photos: com.apple.mobileslideshow
Maps: com.apple.Maps
Contacts: com.apple.MobileAddressBook

Usage:

result = await driver.start_app("com.apple.MobileSMS")
result = await driver.start_app("com.apple.mobilesafari")

IOSDriver.list_packages

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

List known bundle identifiers. Arguments:

include_system bool - Include system apps (default: False)

Returns:

List[str] - List of bundle identifiers

Notes:

Returns union of bundle_identifiers + system apps (if included)
Does not query device for installed apps

IOSDriver.get_apps

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

Return known apps as list of dicts with package (bundle identifier) and label (human-readable name). System apps are mapped to friendly names (e.g., com.apple.mobilesafari → Safari). Third-party bundle identifiers are humanized from the last segment. Arguments:

include_system bool - Include system apps (default: True)

Returns:

List[Dict[str, str]] - List of dicts with ‘package’ and ‘label’ keys

State and Observation Methods

IOSDriver.screenshot

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

Capture device screen as raw PNG bytes. Arguments:

hide_overlay bool - Unused on iOS (for API compatibility)

Returns:

bytes - Raw PNG image data

Usage:

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

IOSDriver.get_ui_tree

async def get_ui_tree() -> Dict[str, Any]

Return unified state from the iOS portal. Mobilerun requests GET /state?timeout=4, giving the portal a single 4-second state collection budget. There is no Mobilerun-side retry on iOS state fetches. Returns: Dictionary with:

a11y_tree - The accessibility tree elements
phone_state - Dict with currentApp and keyboardVisible
device_context - Additional device context

Usage:

tree = await driver.get_ui_tree()
print(tree["phone_state"]["currentApp"])

IOSDriver.get_date

async def get_date() -> str

Get the current date and time from the device. Returns:

str - Date string, or empty string on failure

Unsupported Methods

The following DeviceDriver methods are not in supported and will raise NotImplementedError:

drag()

Not supported on iOS.

install_app()

Not supported on iOS.

Instance Properties

driver.url                    # iOS Portal URL
driver.bundle_identifiers     # Custom bundle IDs
driver.supported              # Set of supported method names
driver.supported_buttons      # Set of supported button names

Example Usage

import asyncio
from mobilerun.tools.driver import IOSDriver

async def main():
    # Initialize and connect
    driver = IOSDriver(url="http://127.0.0.1:6643")
    await driver.connect()

    # Launch Messages
    result = await driver.start_app("com.apple.MobileSMS")
    print(result)

    # Get UI tree
    tree = await driver.get_ui_tree()
    print(tree["phone_state"]["currentApp"])

    # Tap at coordinates
    await driver.tap(200, 400)

    # Input text
    await driver.input_text("Hello from Mobilerun!")

    # Take screenshot
    png_bytes = await driver.screenshot()
    with open("screenshot.png", "wb") as f:
        f.write(png_bytes)

asyncio.run(main())

Note: For higher-level interactions with element indexing and structured results, use action functions with ActionContext (see MobileAgent) rather than calling the driver directly.

Introduction

Features

Guides

Concepts

SDK Reference

IOSDriver

IOSDriver API Reference

IOSDriver

IOSDriver.init

Lifecycle Methods

IOSDriver.connect

IOSDriver.ensure_connected

Input Action Methods

IOSDriver.tap

IOSDriver.swipe

IOSDriver.input_text

IOSDriver.press_button

App Management Methods

IOSDriver.start_app

IOSDriver.list_packages

IOSDriver.get_apps

State and Observation Methods

IOSDriver.screenshot

IOSDriver.get_ui_tree

IOSDriver.get_date

Unsupported Methods

drag()

install_app()

Instance Properties

Example Usage

See Also

​IOSDriver API Reference

​IOSDriver

​IOSDriver.__init__

​Lifecycle Methods

​IOSDriver.connect

​IOSDriver.ensure_connected

​Input Action Methods

​IOSDriver.tap

​IOSDriver.swipe

​IOSDriver.input_text

​IOSDriver.press_button

​App Management Methods

​IOSDriver.start_app

​IOSDriver.list_packages

​IOSDriver.get_apps

​State and Observation Methods

​IOSDriver.screenshot

​IOSDriver.get_ui_tree

​IOSDriver.get_date

​Unsupported Methods

​drag()

​install_app()

​Instance Properties

​Example Usage

​See Also

IOSDriver API Reference

IOSDriver

IOSDriver.init

Lifecycle Methods

IOSDriver.connect

IOSDriver.ensure_connected

Input Action Methods

IOSDriver.tap

IOSDriver.swipe

IOSDriver.input_text

IOSDriver.press_button

App Management Methods

IOSDriver.start_app

IOSDriver.list_packages

IOSDriver.get_apps

State and Observation Methods

IOSDriver.screenshot

IOSDriver.get_ui_tree

IOSDriver.get_date

Unsupported Methods

drag()

install_app()

Instance Properties

Example Usage

See Also