droidlink 0.1.0

Android device control and test automation - Python client for the DeviceKit agent

droidlink

Android device control and test automation in Python — the client library of the DeviceKit platform. Connect to phones over USB or WiFi, drive the UI, run shell commands, manage files and apps, read metrics and notifications, and plug straight into pytest for device testing in CI.

Devices run the lightweight DeviceKit agent app (an HTTP server on the phone); droidlink talks to it directly — over USB via ADB port forwarding, or over WiFi with UDP auto-discovery. No backend server required.

Install

pip install droidlink

Quick Start

import droidlink

# Connect via USB (auto-detect)
d = droidlink.connect()

# Connect to a specific device
d = droidlink.connect("EMULATOR5554")

# Connect via WiFi (no ADB needed)
d = droidlink.connect_wifi("192.168.1.5")

# Device info
print(d.info)       # model, SDK, screen size
print(d.battery)    # level, charging, temperature

# UI Automation
d(text="Login").click()
d(resourceId="com.app:id/input").set_text("hello")
d(className="android.widget.EditText", instance=2).clear_text()
d(scrollable=True).scroll.to(text="Bottom Item")
if d(text="Error").exists(timeout=3):
    print("Error dialog appeared")

# Screenshots
d.screenshot("screen.png")

# Shell commands
result = d.shell("whoami")
print(result.output)

# File management
files = d.files.list("/sdcard/DCIM/")
d.files.push("./config.json", "/sdcard/config.json")
d.files.pull("/sdcard/photo.jpg", "./photo.jpg")

# App management
d.app.launch("com.android.chrome")
apps = d.app.list(filter="user")
results = d.app.search("chrome")

# Notifications
notifications = d.notifications.list()

# Device metrics
metrics = d.metrics.snapshot()
print(f"CPU: {metrics.cpu_percent}%, RAM: {metrics.ram_used_mb}MB")

# Clipboard
d.clipboard.set("copied text")
print(d.clipboard.get())

CLI

droidlink devices              # list connected devices
droidlink ping                 # check agent connectivity
droidlink info                 # show device info
droidlink screenshot -o s.png  # take screenshot
droidlink shell "ls /sdcard"   # run shell command
droidlink apps                 # list user apps
droidlink notifications        # list notifications
droidlink metrics              # show device metrics

pytest plugin

The package ships a pytest plugin with device and device_pool fixtures:

def test_login_flow(device):
    device.app.launch("com.example.app")
    device(text="Login").click()
    assert device(text="Welcome").exists(timeout=5)

pytest tests/ --device <SERIAL>              # USB device
pytest tests/ --device-wifi 192.168.1.5      # WiFi device
pytest tests/ --devicekit-url http://ci:5050 # report results to a DeviceKit backend

With --devicekit-url, test results, build lifecycle, and failure screenshots are reported to the DeviceKit dashboard automatically.

Requirements

• Python 3.8+
• Android device with the DeviceKit agent app installed and running
• ADB (for USB connections) or WiFi connectivity

Part of DeviceKit

droidlink is the programmatic entry point to the larger DeviceKit platform: a fleet dashboard with real-time streaming, a visual automation editor with AI generation and self-healing, visual regression testing, fleet queries, and failure debug bundles.

License

MIT