Metadata-Version: 2.4
Name: droidlink
Version: 0.1.0
Summary: Android device control and test automation - Python client for the DeviceKit agent
Author: Juan Denis
License: MIT
Project-URL: Homepage, https://github.com/jhd3197/droidlink
Project-URL: Repository, https://github.com/jhd3197/droidlink
Project-URL: Platform, https://github.com/jhd3197/DeviceKit
Keywords: android,adb,automation,testing,device-farm,ui-automation,pytest
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Framework :: Pytest
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Dynamic: license-file

# droidlink

Android device control and test automation in Python — the client library of the
[DeviceKit](https://github.com/jhd3197/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

```bash
pip install droidlink
```

## Quick Start

```python
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

```bash
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:

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

```bash
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](https://github.com/jhd3197/DeviceKit): 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
