idevice 0.1.4

Cross-platform device automation for end-to-end test workflows

idevice

Cross-platform device automation for end-to-end test workflows: install and manage apps on physical devices, transfer files, and drive UI interactions through a small, platform-agnostic API.

Platform status

Platform	Backend	App lifecycle	File transfer	Swipe	UI automation
iOS	go-ios (IOSDevice)	Yes	Yes	—	Planned (WDA)
iOS	pymobiledevice3 (IOSDevice3)	Yes	Yes (AFC + app sandbox)	—	Planned (WDA)
Android	adb (AndroidDevice)	Yes	Yes	Yes	Yes (AndroidUIAuto)
Windows	PowerShell (WindowsDevice)	Partial	—	—	Planned

macOS and HarmonyOS are not implemented yet.

Requirements

• Python >= 3.9
• Platform CLI tools on PATH (or configured via environment variables below):
  • iOS (go-ios): ios
  • iOS (pymobiledevice3): pymobiledevice3 (default: /opt/ios3/bin/pymobiledevice3 on Unix, ~/ios3/bin/pymobiledevice3.exe on Windows)
  • Android: adb

Install

uv sync
# or, with dev dependencies
uv sync --group dev

Quick start

Create a device bound to a single UDID or serial, then call lifecycle methods:

from pathlib import Path

from idevice.device import Platform, create_device

# iOS via go-ios
device = create_device(Platform.IOS, device_id="00008030-001A…")

# iOS via pymobiledevice3 (iOS 17+ tunnel support)
device = create_device(Platform.IOS3, device_id="00008030-001A…")

# Android via adb
device = create_device(Platform.ANDROID, device_id="emulator-5554")

device.install(Path("MyApp.ipa"), app_id="com.example.app")
device.launch_app("com.example.app")
device.is_installed("com.example.app")
device.stop_app("com.example.app")
device.uninstall("com.example.app")

Android swipe (via adb shell input swipe):

device.swipe(100, 800, 100, 200, duration_ms=300)

UI automation (Android only today):

from idevice.uiauto import create_uiauto

uiauto = create_uiauto(Platform.ANDROID, device_id="emulator-5554")
uiauto.swipe(100, 800, 100, 200)
uiauto.dismiss_post_install_dialogs(timeout=30)

API overview

DeviceBase

Every platform implementation shares the same interface:

• install(package_path, app_id=None) — install .ipa / .apk and optionally record bundle id → file name
• uninstall(app_id) / is_installed(app_id) / get_installed_pkg_name(app_id)
• launch_app(app_id) / stop_app(app_id)
• push(local, remote, app_id=None) / pull(remote, local, app_id=None) — host ↔ device file transfer
• ls(remote, app_id=None, recursive=False) — list a remote directory on the device
• swipe(x1, y1, x2, y2, duration_ms=300) — touch gesture (Android implemented; iOS/Windows raise NotImplementedError)
• host_is_running() — whether WebDriverAgent / UIAutomator2 host process is up

Use create_device(Platform, device_id=…) or construct IOSDevice, IOSDevice3, AndroidDevice, or WindowsDevice directly.

UIAutoBase

Higher-level UI helpers built on top of device tooling. Currently only AndroidUIAuto is available (swipe, dismiss_post_install_dialogs, hierarchy access).

iOS backends

IOSDevice (go-ios) — lightweight CLI wrapper around go-ios for install, launch, and AFC transfers.

IOSDevice3 (pymobiledevice3) — uses pymobiledevice3 services:

• App install/uninstall/list via apps
• Process control via developer dvt launch / pkill
• File transfer via afc push/pull or apps push/pull (app sandbox, with optional --documents)
• Developer-mode commands require a mounted DeveloperDiskImage; on iOS 17+ an active tunnel is required

Choose Platform.IOS or Platform.IOS3 depending on which CLI you have deployed.

Configuration

Environment variables override default binary paths:

Variable	Default	Used by
IDEVICE_IOS_BINARY	ios	IOSDevice
IDEVICE_IOS3_BINARY	/opt/ios3/bin/pymobiledevice3 (Unix) / ~/ios3/bin/pymobiledevice3.exe (Windows)	IOSDevice3
IDEVICE_ADB_BINARY	adb	AndroidDevice, AndroidUIAuto
IDEVICE_POWERSHELL_BINARY	powershell	WindowsDevice

User data (e.g. installed-app cache) is stored under ~/.idevice by default.

Testing

Unit tests run without a connected device:

uv run pytest

Integration tests under tests/device/ require a physical iOS device and pymobiledevice3. They are excluded by default; run with:

export IDEVICE_IOS3_UDID="00008030-001A…"
uv run pytest -m integration tests/device/

See tests/device/conftest.py for optional variables (IDEVICE_IOS3_TEST_IPA, sandbox push/pull settings, etc.).

Development

uv run ruff check src tests
uv run pytest