convez.ai
SkillAutomaçãoIntermediário
hah23255

Controle Android via ADB

hah23255/adb-android-control

Controle completo de dispositivos Android via ADB com tipos, testes e CLI

Ver no GitHub
BomPluginScore · de 0 a 100

Pacote Python tipado com CLI e skill para Claude que envolve o binário `adb` com uma API limpa e testada. Permite controlar dispositivos Android — capturar screenshots, monitorar logs, executar workflows de automação — tanto como biblioteca Python quanto ferramenta CLI ou skill do Claude.

Instalação

$npx convez-ai hah23255/adb-android-control

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
20
Forks
3
Acompanhando
1
Saúde
85%
Último commit
há 1 mês
Versão
v2.0.1
Issues abertas
0
Contribuidores
2

Casos de uso

  • Automação de testes em dispositivos Android via CI/CD
  • Captura de screenshots e monitoramento de logcat em tempo real
  • Workflows de teste repetitivos via JSON ou Python API
  • Integração com agentes Claude para tarefas mobile

Veredito

Ferramenta sólida e bem testada (1.59:1 teste/código) para quem precisa controlar Android programaticamente. Excelente para CI/CD e integração com Claude, mas exige `adb` instalado e conhecimento básico de Android. Type-safe e production-ready.

README

A tradução para o português deste README ainda está na fila.

adb-android-control

Comprehensive Android device control via ADB — for humans, agents, and CI.

Python License: MIT Doctrine Tests Test ratio Type check Pre-commit

A typed Python package + CLI that wraps the standard adb binary with a clean, doctrine-tested API. Pairs with Claude Code as a marketplace skill, but works equally well as a plain Python library or shell tool.


30-second pitch

pip install adb-android-control
adb-control devices
adb-control info -s EMULATOR-1
adb-control shot screen.png
adb-control monitor logcat
adb-control workflow ./my-test.json

Built around three principles:

  1. Behavioural test contracts. Every public method has a typed test exercising the failure mode it claims to handle. 338 tests today, 1.59 : 1 test/code ratio.
  2. No hidden subprocess interleaving. Every shell-out goes through ADBController (or one flagged streaming carve-out). No shell=True anywhere. Argv lists only.
  3. Observable contracts. Typed exceptions, frozen value objects, wire-format-stable enum values. If we change a public name, your tests will tell you.

Install

As a Python package

# From source (PyPI publish pending)
pip install -e ".[dev]"

# Or just the runtime dependencies
pip install -e .

As a Claude Code skill

git clone https://github.com/hah23255/adb-android-control.git \
    ~/.claude/skills/adb-android-control
claude /plugin marketplace add ~/.claude/skills/adb-android-control

Quickstart

1. Verify your adb is available

adb version

If this fails, install Android platform-tools or pkg install android-tools on Termux.

2. Connect a device

USB

adb devices    # Authorize on the device when prompted

Wireless (Android 11+)

adb pair      <device-ip>:<pair-port>  <pair-code>
adb connect   <device-ip>:<connect-port>

See docs/SETUP.md for screenshots of the device-side flow.

3. Use it

Python

from adb_android_control import ADBController, DeviceOfflineError

ctrl = ADBController()                          # raises ADBNotFoundError if adb missing
print(ctrl.devices())                            # → list of dicts
info = ctrl.get_device_info()                    # → DeviceInfo
print(f"{info.model} on Android {info.android_version}")
ctrl.screenshot("/tmp/shot.png")

CLI

adb-control devices                  # list connected devices
adb-control info                     # JSON device snapshot
adb-control shot                     # screenshot.png in $CWD
adb-control monitor logcat -l W      # warning+ logcat stream
adb-control monitor crash            # crash detector
adb-control radio                    # WiFi + Bluetooth status
adb-control workflow ./test.json     # run an automation workflow
adb-control health                   # JSON health check
adb-control --version                # 2.0.0

4. Author a workflow

{
  "steps": [
    { "action": "wake",       "delay": 0.5 },
    { "action": "home",       "delay": 0.5 },
    { "action": "start_app",  "params": {"package": "com.example.app"}, "delay": 3 },
    { "action": "tap_center", "delay": 1 },
    { "action": "screenshot", "params": {"path": "after_tap.png"}, "delay": 0 }
  ]
}
adb-control workflow my-test.json

22 step kinds available — see adb_android_control/automation.py.

Architecture

flowchart LR
  CLI["adb-control<br/>(cli.py)"] --> Ctrl["ADBController<br/>(controller.py)"]
  CLI --> Mon["LogcatMonitor<br/>PerformanceMonitor<br/>CrashMonitor"]
  CLI --> Auto["ADBAutomation<br/>AppTester<br/>DeviceManager"]
  CLI --> Radio["RadioScanner"]
  CLI --> Conn["ConnectionMonitor"]
  CLI --> Port["PortScanner"]
  Mon --> Ctrl
  Auto --> Ctrl
  Radio --> Ctrl
  Conn --> Ctrl
  Ctrl -.subprocess.-> ADB["adb (CLI)"]
  ADB -.TCP/USB.-> Device["Android device"]
  style Ctrl fill:#0066cc,color:#fff
  style CLI fill:#009933,color:#fff

The full architecture deep-dive lives at docs/ARCHITECTURE.md, including sequence + state-machine diagrams.

Why this exists

Most Android automation libraries are either:

  • Java/Kotlin (e.g. libadb-android) — great for Android-app-internal usage, no help on the host.
  • uiautomator2 / Appium — focused on UI test automation; heavyweight install; not great for raw ADB control.
  • Pure shell scripts — fragile parsing; hard to test; brittle.

adb-android-control is the missing piece: a typed, doctrine-tested Python wrapper for everything adb can do, with sane error classification and zero hidden state.

Testing — the Master Tester Doctrine

This project is governed by the Master Tester Doctrine (HH directive 2026-03-05). The 10 non-negotiable laws live at docs/TESTING_DOCTRINE.md. Highlights:

LawMechanism in this repo
1. Never modify a test to fix CIpre-commit + CI test-file-integrity gate (Phase 7)
6. Never mock subprocess directlyPoison-Pill mock_adb fixture in tests/conftest.py
7. Ban as any in testsmypy --strict with disallow_any_explicit = true
8. Tests must be deterministicfreezegun, _sleep/_now indirection, no real timers

Run the tests

pytest                       # 338 tests; ~10-20K Hypothesis examples
pytest -m unit               # unit only (default)
pytest -m property           # property-based fuzzing
pytest -m race               # threading + concurrency
pytest --cov                 # coverage report

Project status

PhaseStatus
0. Security purge✅ v1.0.1 shipped
1. Test foundation + 8 modules✅ phase-1b-complete
2. Code quality + CLI✅ phase-2-complete
3. Hypothesis + race + failure injection✅ phase-3-complete
4. Documentation✅ shipped with v2.0 GA
5. Discoverability✅ shipped with v2.0 GA
6. Visual polish (logo + GIFs)🟡 in progress
7. CI matrix + Codecov + CodeQL✅ shipped with v2.0 GA
8. v2.0 GA✅ 2026-05-05 🚀

Public GA shipped 2026-05-05 (v2.0.0 — see CHANGELOG). Roadmap and per-release deliverables are tracked in CHANGELOG.md.

Documentation

DocAudience
docs/ARCHITECTURE.mdNew contributors
docs/TESTING_DOCTRINE.mdAnyone writing tests
SECURITY.mdVulnerability reporters
docs/MIGRATING.mdUsers on v1.0.x
docs/SETUP.mdFirst-time setup
docs/TROUBLESHOOTING.mdWhen things go wrong (decision tree)
docs/USE_CASES.mdRecipe gallery
docs/TUTORIALS.mdStep-by-step walkthroughs
CHANGELOG.mdRelease history
CONTRIBUTING.mdContributors

Contributing

PRs welcome — see CONTRIBUTING.md for the doctrine-aligned workflow.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados