Metadata-Version: 2.4
Name: geppetto-android
Version: 2.0.4
Summary: Android UI Automation Framework — like Geppetto brought Pinocchio to life, this tool brings your tests to life.
Project-URL: Homepage, https://github.com/desodre/geppetto
Project-URL: Repository, https://github.com/desodre/geppetto
Project-URL: Issues, https://github.com/desodre/geppetto/issues
Project-URL: Documentation, https://github.com/desodre/geppetto#readme
Author-email: Jhonatha Sodre <jhon.desodre@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: adb,android,automation,qa,testing,uiautomator2
Classifier: Development Status :: 4 - Beta
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 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: adbutils>=2.9.3
Requires-Dist: lxml>=6.0.0
Requires-Dist: pillow>=11.0.0
Requires-Dist: uiautomator2>=3.3.3
Provides-Extra: all
Requires-Dist: brainstem>=2.9.0; extra == 'all'
Requires-Dist: extcolors>=1.0.0; extra == 'all'
Requires-Dist: imagehash>=4.3.1; extra == 'all'
Requires-Dist: numpy>=1.26.0; extra == 'all'
Requires-Dist: opencv-python>=4.9.0; extra == 'all'
Provides-Extra: analyzers
Requires-Dist: extcolors>=1.0.0; extra == 'analyzers'
Requires-Dist: imagehash>=4.3.1; extra == 'analyzers'
Requires-Dist: numpy>=1.26.0; extra == 'analyzers'
Requires-Dist: opencv-python>=4.9.0; extra == 'analyzers'
Provides-Extra: hardware
Requires-Dist: brainstem>=2.9.0; extra == 'hardware'
Description-Content-Type: text/markdown

# geppetto-android

Geppetto is a high-level Python framework for Android UI automation.
It provides a single, typed API to orchestrate ADB, Fastboot, and UIAutomator2.

Just as Geppetto brought Pinocchio to life, this tool brings your Android tests to life.

## Highlights

- High-level `Device` facade for Android automation workflows.
- Widget search through text, id, class, content description, and XPath.
- Structured UI hierarchy parsing via `lxml` (`WindowDump`, `Widget`, `Bounds`).
- Built-in services for Wi-Fi, lockscreen, and notification controls.
- Optional extras for image/video analyzers and hardware integrations.

## Requirements

- Python 3.12+
- Android SDK platform tools (`adb`, optional `fastboot`) available on PATH
- Android device or emulator with ADB enabled

## Installation

### pip

```bash
pip install geppetto-android
```

Optional extras:

```bash
# Image/video analyzers
pip install "geppetto-android[analyzers]"

# Hardware integrations
pip install "geppetto-android[hardware]"

# All optional features
pip install "geppetto-android[all]"
```

### uv

```bash
uv add geppetto-android
uv add "geppetto-android[analyzers]"
uv add "geppetto-android[hardware]"
uv add "geppetto-android[all]"
```

## Quick start

```python
from geppetto import By, Device, WifiSecurityType

device = Device("SERIAL_NUMBER")

device.install("app.apk", replace=True)
device.open_app("com.example.app")

login_button = device.await_widget(By.TEXT, "Login", timeout=15)
device.click(login_button)

device.screenshot("login_screen", pull_to_results=True)

device.wifi.connect("MyNetwork", WifiSecurityType.WPA2, "password")
```

## Main components

- `Device`: primary facade and entry point.
- `geppetto.core`: ADB/Fastboot clients.
- `geppetto.ui`: UI models (`WindowDump`, `Widget`, `Bounds`, `Children`).
- `geppetto.services`: automation services (`wifi`, `lockscreen`, `notification`).
- `geppetto.models`: enums such as `By`, `Direction`, `WifiSecurityType`, `CommonClasses`.

## Development

```bash
git clone https://github.com/desodre/geppetto.git
cd geppetto
uv sync --all-extras
```

## Links

- Homepage: https://github.com/desodre/geppetto
- Repository: https://github.com/desodre/geppetto
- Issues: https://github.com/desodre/geppetto/issues

## License

MIT License
