Skip to main content

​
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:
  1. Build and run the iOS Portal via Xcode (runs as a UI test)
  2. Forward port with iproxy 6643 6643
  3. 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.

​
See Also