dynamic-test-engine 0.1.0

UI Automation Library for Robot Framework — Android and Windows Desktop

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

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):

# 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:

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

# 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

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.

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.

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

Device ID in .env eintragen

adb devices -l

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

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.

Verwendung

Android

*** 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

.\run.ps1

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

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. Ausführliche Tester-Anleitung für den Windows-PoC: docs/tester_windows_poc.md.

Setup remote

Auf der Windows-Maschine (Testziel):

.\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:

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

Verwendung

*** 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 — vollständige Testanleitung (manuell + automatisiert)
• docs/custom_elements_erstellen.md — Referenz-Icons für Custom Element Matching erstellen

Vision Stack (adb.py, image_processing.py, vision_engine.py):

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):

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

Performance

Gemessen mit 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.