Metadata-Version: 2.4
Name: dynamic-test-engine
Version: 0.1.0
Summary: UI Automation Library for Robot Framework — Android and Windows Desktop
Author-email: Mohamad Mussa <mohamad.mussa@aitimatic.com>
Maintainer: aitimatic GmbH
License-Expression: MIT
Project-URL: Homepage, https://github.com/aitimatic-GmbH/UI-Automation-Library
Project-URL: Repository, https://github.com/aitimatic-GmbH/UI-Automation-Library
Project-URL: Documentation, https://github.com/aitimatic-GmbH/UI-Automation-Library#readme
Keywords: robot-framework,automation,android,windows,ui-testing,uiautomator2,pywinauto,ocr,computer-vision
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Robot Framework
Classifier: Framework :: Robot Framework :: Library
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: uiautomator2==3.5.0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: robotframework==7.4.2
Requires-Dist: opencv-python==4.13.0.92
Requires-Dist: pytesseract==0.3.13
Requires-Dist: numpy==2.2.6
Provides-Extra: windows
Requires-Dist: pywinauto>=0.6.9; extra == "windows"
Requires-Dist: comtypes>=1.4; sys_platform == "win32" and extra == "windows"
Requires-Dist: pywin32>=306; sys_platform == "win32" and extra == "windows"
Requires-Dist: Pillow>=10.0; extra == "windows"
Provides-Extra: remote
Requires-Dist: robotremoteserver>=1.1; extra == "remote"
Provides-Extra: dev
Requires-Dist: ruff>=0.15; extra == "dev"
Dynamic: license-file

# UI Automation Library

Robot Framework Library für die Automatisierung nativer Apps.  
Primäre Engine: UIAutomator2 (Android) / UI Automation (Windows) — Fallback: OpenCV + Tesseract OCR.

> **Status:** In Entwicklung — PoC Phase 1  
> **Plattformen:** Android (produktiv), Windows Desktop (PoC)

## Ziel

Ein wiederverwendbares Test-Framework für native legacy Apps (Android und Windows Desktop).  
Das Framework läuft lokal auf einem echten Gerät oder Desktop, deterministisch, debugbar und Cloud-unabhängig.

---

## Funktionsübersicht

- **12 Robot Framework Keywords** — direkt in `.robot`-Testdateien nutzbar, keine Python-Kenntnisse nötig
- **Dual-Engine-Architektur** — UI Automation als primäre Engine, OpenCV + Tesseract OCR als Fallback
- **Plattformunabhängige Vision-Schicht** — gleiche OCR/Template-Logik auf Android und Windows
- **Text-Interaktion** — Tippen auf sichtbaren Text, prüfen ob Text vorhanden ist
- **Icon-Erkennung** — Custom Element Matching findet Icons auch ohne Text-Label
- **Scrollen mit Retry** — automatisches Scrollen bis ein Element sichtbar wird
- **App-Management** — APK installieren (Android), App starten per Package-Name
- **Geräteverbindung** — USB und Wireless (Android 11+), Prozess-Attach (Windows)
- **Screenshots** — Aufnahme und Speicherung für Debugging und Logs
- **Cloud-unabhängig** — läuft lokal auf echtem Gerät oder Desktop, keine externe Abhängigkeit

---

## Voraussetzungen

- **Python 3.10** — muss vorab installiert sein; auf Ubuntu/Debian zusätzlich: `sudo apt install python3.10-venv`
- ADB 1.0.41 (Platform Tools 34.0.5) — wird von `run.sh` / `run.ps1` installiert
- Tesseract OCR 5.4.1 — wird von `run.sh` / `run.ps1` installiert
- Android-Gerät mit aktiviertem USB-Debugging

### Python installieren

| Plattform | Installation |
|---|---|
| Windows | `winget install Python.Python.3.10` oder Installer: https://www.python.org/downloads/release/python-31011/ |
| Ubuntu/Debian | `sudo add-apt-repository ppa:deadsnakes/ppa && sudo apt install python3.10 python3.10-venv` |
| macOS | `brew install python@3.10` oder Installer: https://www.python.org/downloads/release/python-31011/ |

> Python muss **vor** dem ersten Ausführen von `run.sh` / `run.ps1` verfügbar sein.  
> `ADB` und `Tesseract` werden automatisch vom Setup-Script installiert.

## Installation

### 1. System-Dependencies + Python-Umgebung

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
```

Oder mit dem Setup-Script (installiert auch ADB und Tesseract automatisch):

```bash
# Linux / macOS
bash run.sh

# Windows (PowerShell)
.\run.ps1
```

### 2. UIAutomator2-Server auf Gerät installieren

`run.sh` / `run.ps1` führen diesen Schritt automatisch aus, wenn beim Setup ein Gerät verbunden war.

War kein Gerät verbunden, einmalig manuell nachholen:

```bash
source .venv/bin/activate
python -m uiautomator2 init
```

## Gerät verbinden

### Smartphone vorbereiten

1. Einstellungen → Über das Telefon → **Build-Nummer 7× tippen** (Entwickleroptionen aktivieren)
2. Einstellungen → Entwickleroptionen → **USB-Debugging** aktivieren
3. Einstellungen → Entwickleroptionen → **USB-Debugging (Sicherheitseinstellungen)** aktivieren

### Option A — USB

```bash
# Kabel verbinden, Erlaubnis am Smartphone bestätigen
adb devices
```

Ausgabe:
```
List of devices attached
R5CR61D4VAX     device
```

Status muss `device` sein. Bei `unauthorized`: Verbindungsdialog am Smartphone bestätigen.  
Bei `offline`: `adb kill-server && adb start-server`, dann neu verbinden.

> **Im Devcontainer:** Der Container kommuniziert mit dem ADB-Server des Hosts via TCP.  
> Erst auf dem Host `adb devices` prüfen, dann den Container starten. Details: [docs/usb_debugging_setup.md](docs/usb_debugging_setup.md)

### Option B — Wireless (Android 11+)

Einstellungen → Entwickleroptionen → **Wireless Debugging** aktivieren

**1. Einmalig koppeln:**

Am Smartphone: Wireless Debugging → "Gerät mit Kopplungscode koppeln" → IP, Pairing-Port und Code notieren.

```bash
adb pair <IP>:<PAIRING_PORT>
# Beispiel: adb pair 192.168.178.47:46605
```

**2. Verbinden:**

Am Smartphone: Wireless Debugging → "IP-Adresse & Port" (≠ Pairing-Port!) notieren.

```bash
adb connect <IP>:<CONNECT_PORT>
# Beispiel: adb connect 192.168.178.47:45547
```

Nach erfolgreichem Connect erscheint das Gerät in `adb devices` mit `IP:PORT` als ID.  
Dieser Wert wird als `ANDROID_DEVICE_ID` in `.env` eingetragen — **`adb connect` muss vor jedem Framework-Start manuell ausgeführt werden**, da sich der Port bei Neustart von Wireless Debugging ändert.

Details und Fehlerbehebung: [docs/wireless_debugging_nutzen.md](docs/wireless_debugging_nutzen.md)

### Device ID in .env eintragen

```bash
adb devices -l
```

Die angezeigte ID (z.B. `R5CR61D4VAX` oder `192.168.178.47:45547`) in `.env` eintragen:

```bash
cp .env.example .env
# ANDROID_DEVICE_ID=R5CR61D4VAX
```

---

## Keywords

| Keyword | Beschreibung | engine | Plattform |
|---|---|---|---|
| `Connect Device` | Verbindung zum Gerät herstellen (USB, IP oder Windows-Prozess) | — | Android + Windows |
| `Install App` | App per ADB installieren | — | Android |
| `Launch App` | App starten (Android: per UIAutomator2; Windows: beendet eine laufende Instanz und startet neu, optional `fullscreen`) | — | Android + Windows |
| `Tap Text` | Auf sichtbaren Text tippen | `auto` / `uia` / `vision` | Android + Windows |
| `Input Text` | Text in ein Eingabefeld eingeben; `anchor` disambiguiert bei mehreren Treffern (nur bei `engine=uia` unter Windows relevant) | `auto` / `uia` / `vision` | Android + Windows |
| `Tap Icon Near Text` | Icon neben bestimmtem Text tippen (`near`-Spezialfall von `Tap Element`) | `auto` / `uia` / `vision` | Android + Windows |
| `Scroll To Text` | Scrollen bis Text sichtbar wird; `anchor`/`relation` steuern bei `engine=vision` die Scroll-Region | `auto` / `uia` / `vision` | Android + Windows |
| `Text Should Exist` | Prüfen ob Text auf dem Bildschirm ist | `auto` / `uia` / `vision` | Android + Windows |
| `Find Element` | Ziel (Text/Icon) relativ zu einem Anker-Text lokalisieren, gibt `(x, y)` zurück | `vision` | Android + Windows |
| `Tap Element` | Ziel relativ zu einem Anker-Text antippen; `relation` = `near` / `left_of` / `right_of` / `above` / `below` | `vision` | Android + Windows |
| `Take Screenshot` | Screenshot speichern | — | Android + Windows |
| `Move Mouse` | Mauszeiger an Position bewegen, ohne zu klicken | — | Windows |

| engine | Verhalten |
|---|---|
| `auto` *(Standard)* | UIAutomator2 zuerst — bei Fehler Fallback auf Vision |
| `uia` | Nur UIAutomator2, kein Fallback |
| `vision` | Nur Vision (OpenCV + Tesseract OCR) |

### Optionaler Cache

Die Vision-Engine kann das OCR-Zeilen-Layout je Screen cachen (`VISION_OCR_CACHE=true`, Default
aus). Ein Treffer überspringt das teure Full-Screen-OCR und verifiziert das Ziel stattdessen
live per Crop-OCR, Koordinaten bleiben also live. Schlüssel ist die stabile Screen-Identität
(`package/activity/version/device`), nicht der Pixelinhalt, daher trifft der Cache über Läufe
hinweg. Hintergrund, Methode und Messungen: [docs/recherche_caching.md](docs/recherche_caching.md).

## Verwendung

### Android

```robot
*** Settings ***
Library      automation.keywords.automation_keywords.AutomationKeywords
Suite Setup  Connect Device
Test Setup   Launch App    com.android.settings

*** Test Cases ***
WLAN öffnen
    Tap Text          WLAN
    Text Should Exist    WLAN
    Take Screenshot   ergebnis
```

- `Suite Setup  Connect Device` — Geräteverbindung einmalig für die gesamte Suite
- `Test Setup   Launch App ...` — App-Neustart vor jedem Testfall: Standard-Muster für Android-UI-Tests (Espresso, UI Automator, Appium). Jeder Test startet aus einem bekannten Zustand, unabhängig davon ob der vorherige Test in eine Unterseite navigiert hat.

### Windows Desktop (PoC)

Zwei Betriebsarten: **lokal** (Tests laufen auf derselben Windows-Maschine) oder **remote**
(die Windows-Maschine ist nur Testziel, der Testtreiber läuft woanders).

#### Setup lokal

```powershell
.\run.ps1
```

`run.ps1` installiert die Windows-Extras (`.[windows]`) automatisch mit. Bei manueller
Installation ohne Setup-Script:

```powershell
pip install -e ".[windows]"
```

Danach direkt mit `platform=windows` verwenden (Beispiel unten), kein weiterer Schritt nötig —
für den lokalen PoC-Test wird **kein Remote Server** benötigt. Remote Server (siehe
"Setup remote" unten) ist nur relevant, wenn die Windows-Maschine reines Testziel ist und der
Testtreiber woanders läuft.

Voraussetzungen und Konfiguration: [docs/konfiguration.md](docs/konfiguration.md).
Ausführliche Tester-Anleitung für den Windows-PoC: [docs/tester_windows_poc.md](docs/tester_windows_poc.md).

#### Setup remote

Auf der Windows-Maschine (Testziel):

```powershell
.\run.ps1 -Remote
.venv\Scripts\python.exe remote_server.py
```

`remote_server.py` bindet `0.0.0.0:8270` ohne Authentifizierung und muss in einer interaktiven
Session laufen, kein Hintergrunddienst. Nur im internen PoC-Netz betreiben, Firewall-Regel auf
die IP des Testtreibers einschränken.

Im Testtreiber-Robot-File ersetzt `Library Remote` die direkte Library-Einbindung, der Rest der
Suite (`Connect Device`, Testfälle) bleibt identisch:

```robot
*** Settings ***
Library      Remote    http://<windows-ip>:8270
```

#### Verwendung

```robot
*** Settings ***
Library      automation.keywords.automation_keywords.AutomationKeywords
Suite Setup  Connect Device    legacy-app.exe    platform=windows

*** Test Cases ***
Anmeldeseite prüfen
    Text Should Exist    Willkommen
    Tap Text             Anmelden
    Take Screenshot      ergebnis
```

- `Connect Device` mit `platform=windows` verbindet sich per Prozessname oder Fenstertitel
- `Install App` ist auf Windows nicht verfügbar, die App muss vorab installiert sein
- `Launch App` beendet auf Windows eine ggf. laufende Instanz und startet sie neu, damit jeder Testlauf von einem definierten Zustand beginnt

#### Bekannte Grenzen des Windows-PoC

- PoC-Stand, kein finaler Gesamtumfang
- 100%-Anzeigeskalierung empfohlen
- Ein Monitor empfohlen
- Komplexe Dialog-/Popup-Szenarien nur eingeschränkt unterstützt
- Scroll in komplexen Custom Controls noch nicht final stabilisiert
- Android wird separat oben dokumentiert

## Projektstruktur

```
automation/
├── engines/              # UIAutomator2-, Windows-UIA- und Vision-Engine
├── keywords/             # Robot Framework Keywords
├── utils/                # Geräte-Abstraktionen, ADB-Wrapper, Bildverarbeitung
└── config.py             # Schwellwerte, Timeouts, Pfade
custom_elements/          # Referenz-Icons für Custom Element Matching
tests/                    # Robot Framework Testfälle
logs/                     # Screenshots und Debug-Logs
apks/                     # APK-Ablage (wird nicht eingecheckt)
scripts/                  # Automatisierte Integrationstests
devcontainer.example/    # Devcontainer-Vorlage (nach .devcontainer/ kopieren)
setup_env.py              # Plattformübergreifende System-Dependency-Installation
run.sh                    # Setup-Einstiegspunkt Linux/macOS
run.ps1                   # Setup-Einstiegspunkt Windows
system-requirements.txt   # Gepinnte Versionen für Tesseract und ADB
```

## Testing

Testdokumentation und automatisierter Test-Runner:

- [docs/testing.md](docs/testing.md) — vollständige Testanleitung (manuell + automatisiert)
- [docs/custom_elements_erstellen.md](docs/custom_elements_erstellen.md) — Referenz-Icons für Custom Element Matching erstellen

**Vision Stack** (adb.py, image_processing.py, vision_engine.py):
```bash
source .venv/bin/activate
python scripts/run_integration_tests.py <DEVICE_ID>
# Optional: python scripts/run_integration_tests.py <DEVICE_ID> --threshold 0.85
```
18 automatisierte Tests.

**Core Stack** (uia_engine.py, engine_manager.py):
```bash
source .venv/bin/activate
python scripts/run_integration_tests_core.py <DEVICE_ID>
```
15 automatisierte Tests.

Benchmark-Anleitung (Config-Matrix, Auswertung, Plattform-Vergleich): [docs/benchmark.md](docs/benchmark.md)

## Performance

Gemessen mit [tools/run_benchmark.py](tools/run_benchmark.py), Konfiguration `uia_timeout_3`, je 10 Läufe pro Kombination.

**UIA vs. Vision Engine** (Linux Devcontainer):

| Keyword | UIA | Vision |
|---|---|---|
| Launch App | 2 246 ms | 2 280 ms |
| Scroll To Text | 3 861 ms | 4 659 ms |
| Tap Icon Near Text | 4 500 ms | 1 314 ms |
| Tap Text | 416 ms | 1 083 ms |
| Text Should Exist | 71 ms | 1 027 ms |

**Plattform-Vergleich** (UIA Engine):

| Keyword | Ubuntu 24.04 | Linux Devcontainer | Windows 11 |
|---|---|---|---|
| Launch App | 2 067 ms | 2 246 ms | 7 254 ms |
| Scroll To Text | 3 872 ms | 3 861 ms | 3 800 ms |
| Tap Icon Near Text | 4 437 ms | 4 500 ms | 3 025 ms |
| Tap Text | 397 ms | 416 ms | 299 ms |
| Text Should Exist | 71 ms | 71 ms | 55 ms |

Alle Messungen über USB-Verbindung (kein WiFi). Windows 11 zeigt bei Launch App
deutlich höhere Werte — Ursache plattformspezifisch, nicht verbindungsbedingt.
Vollständige Rohdaten werden über die CI-Pipeline erzeugt und liegen unter `benchmark_results/`.

## Tech-Stack

| Komponente | Version |
|---|---|
| Python | 3.10 |
| Robot Framework | 7.4.2 |
| uiautomator2 | 3.5.0 |
| opencv-python | 4.13.0.92 |
| pytesseract | 0.3.13 |
| numpy | 2.2.6 |
| python-dotenv | 1.2.2 |
| Tesseract OCR | 5.4.1 |
| ADB | 1.0.41 (34.0.5) |

## Lizenz

MIT — siehe [LICENSE](LICENSE).
