> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobilerun.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# IOSDriver
# IOSDriver API Reference
## IOSDriver
```python theme={null}
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\_\_
```python theme={null}
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](http://127.0.0.1:6643)")
* `bundle_identifiers` *List\[str] | None* - Optional list of custom app bundle identifiers
**Usage:**
```python theme={null}
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:**
```python theme={null}
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](/framework/guides/device-setup) for full instructions.
***
## Lifecycle Methods
#### IOSDriver.connect
```python theme={null}
async def connect() -> None
```
Create an HTTP client and verify connectivity by calling `/device/date`.
#### IOSDriver.ensure\_connected
```python theme={null}
async def ensure_connected() -> None
```
Connect if not already connected. Safe to call multiple times.
***
## Input Action Methods
#### IOSDriver.tap
```python theme={null}
async def tap(x: int, y: int) -> None
```
Tap at coordinates.
**Arguments**:
* `x` *int* - X coordinate
* `y` *int* - Y coordinate
**Usage:**
```python theme={null}
await driver.tap(200, 400)
```
#### IOSDriver.swipe
```python theme={null}
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:**
```python theme={null}
# Swipe up (scroll down)
await driver.swipe(200, 800, 200, 200)
# Swipe left
await driver.swipe(600, 400, 100, 400)
```
#### IOSDriver.input\_text
```python theme={null}
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:**
```python theme={null}
# 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
```python theme={null}
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:**
```python theme={null}
await driver.press_button("home")
```
***
## App Management Methods
#### IOSDriver.start\_app
```python theme={null}
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:**
```python theme={null}
result = await driver.start_app("com.apple.MobileSMS")
result = await driver.start_app("com.apple.mobilesafari")
```
#### IOSDriver.list\_packages
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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:**
```python theme={null}
png_bytes = await driver.screenshot()
with open("screenshot.png", "wb") as f:
f.write(png_bytes)
```
#### IOSDriver.get\_ui\_tree
```python theme={null}
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:**
```python theme={null}
tree = await driver.get_ui_tree()
print(tree["phone_state"]["currentApp"])
```
#### IOSDriver.get\_date
```python theme={null}
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
```python theme={null}
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
```python theme={null}
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](/framework/sdk/droid-agent)) rather than calling the driver directly.
***
## See Also
* [AndroidDriver](/framework/sdk/adb-tools) - Android device driver
* [DeviceDriver Base Class](/framework/sdk/base-tools) - Base class and architecture reference
* [Device Setup — iOS](/framework/guides/device-setup) - Full setup instructions