dynamic-test-engine 0.1.0__tar.gz

dynamic_test_engine-0.1.0/.env.example

@@ -0,0 +1,145 @@
+# Android Gerät
+# Device ID ermitteln mit: adb devices
+ANDROID_DEVICE_ID=your_device_id_here
+
+# Engine-Konfiguration
+# Optionen: auto | uia | vision
+# leer lassen = Standardwert: auto
+DEFAULT_ENGINE=auto
+
+# Custom Element Matching Schwellwert (0.0 – 1.0)
+# leer lassen = Standardwert: 0.9
+CUSTOM_ELEMENT_MATCH_THRESHOLD=0.9
+
+# OCR-Sprachen (Tesseract-Format, z.B. deu+eng)
+# leer lassen = Standardwert: deu+eng
+OCR_LANGUAGES=deu+eng
+
+# OCR-Seitensegmentierungsmodus (PSM): 11 = spärlicher Text (UI-Elemente), 6 = Textblock, 3 = vollautomatisch
+# leer lassen = Standardwert: 11
+OCR_PSM=11
+
+# OCR-Engine-Modus (OEM): 1 = LSTM (Standard), 0 = Legacy
+# leer lassen = Standardwert: 1
+OCR_OEM=1
+
+# Bild-Skalierung vor OCR (1.0 = kein Scaling, 0.5 = halbe Auflösung)
+# leer lassen = Standardwert: 1.0
+OCR_SCALE=1.0
+
+# Minimaler OCR-Konfidenzwert (0–100); Texte unterhalb werden ignoriert
+# leer lassen = Standardwert: 60
+OCR_CONFIDENCE=60
+
+# Timeouts in Sekunden
+# leer lassen = Standardwert: 3
+ADB_TIMEOUT=3
+UIA_TIMEOUT=3
+# Timeout für screencap (Screenshot-Transfer über WLAN/Emulator dauert länger als reguläre ADB-Befehle)
+# leer lassen = Standardwert: 10
+ADB_SCREENSHOT_TIMEOUT=10
+
+# Separate Timeouts für Scroll und App-Start
+# leer lassen = Standardwert: 8 (Scroll dauert länger als einfache Element-Suche)
+UIA_SCROLL_TIMEOUT=8
+# leer lassen = Standardwert: 3
+UIA_APP_START_TIMEOUT=3
+# Wartezeit nach waitForIdle in Sekunden (zu niedrig = Animationen werden noch nicht abgeschlossen)
+# leer lassen = Standardwert: 0.5
+UIA_WAIT_IDLE_TIMEOUT=0.5
+# Wartezeit nach dem Leeren eines Eingabefelds (Windows Vision Engine), bevor die Leerung
+# per Lese-Zugriff verifiziert wird
+# leer lassen = Standardwert: 0.1
+WINDOWS_CLEAR_FIELD_DELAY=0.1
+
+# Swipe-Dauer in Millisekunden (zu kurz = Gerät reagiert nicht, zu lang = langsam)
+# leer lassen = Standardwert: 300
+ADB_SWIPE_DURATION_MS=150
+# Swipe-Dauer für Vision-Scrolls (scroll_to_text) in Millisekunden, separat von ADB_SWIPE_DURATION_MS
+# leer lassen = Standardwert: 200
+VISION_SCROLL_SWIPE_DURATION_MS=200
+# Swipe-Dauer für die Nachzentrierung nach einem Scroll-Treffer in Millisekunden
+# (bewusst langsam, kein Fling-Impuls)
+# leer lassen = Standardwert: 500
+CENTERING_SWIPE_DURATION_MS=500
+
+# Scroll-Verhalten
+# Anzahl Scroll-Schritte pro Richtung (runter + hoch)
+# leer lassen = Standardwert: 3
+SCROLL_RETRIES=3
+# Schrittgröße der Vision-Scrolls als Anteil der Bildschirmhöhe (0.20 = 20%)
+# Wirkt NUR auf die Vision-Engine UIA scrollt über scroll.to() und nutzt den Wert nicht.
+# leer lassen = Standardwert: 0.20
+VISION_SCROLL_STEP_PERCENT=0.20
+# Safe-Area-Rand für die Nachzentrierung nach einem Scroll-Treffer (engine-übergreifend):
+# oberste/unterste 25 % gelten als "zu nah am Rand" und werden minimal nachzentriert.
+# Größerer Wert = Element wird weiter vom Rand zurückgeholt (mehr Tap-Puffer).
+# leer lassen = Standardwert: 0.25
+SCROLL_SAFE_MARGIN_PERCENT=0.25
+
+# Maximale Scroll-Schritte für Vision Engine (End-of-List-Schutz)
+# leer lassen = Standardwert: 30
+VISION_SCROLL_MAX=30
+# Mittlerer Pixel-Differenz-Schwellwert für End-of-List-Erkennung der Vision Engine
+# Unterschreitet die Differenz zweier aufeinanderfolgender Screenshots diesen Wert, gilt die Liste als erschöpft
+# Niedrigerer Wert = empfindlicher (mehr Falsch-Positives bei Animationen möglich)
+# leer lassen = Standardwert: 2.0
+VISION_STABLE_THRESHOLD=2.0
+# Maximale Mausrad-Schritte für Windows UIA Engine (End-of-List-Schutz)
+# leer lassen = Standardwert: 30
+UIA_SCROLL_MAX_SWIPES=30
+# Details zu den Mausrad-Werten (auflösungsabhängig, selbst zu justieren): docs/konfiguration.md
+# leer lassen = Standardwert: 10
+WINDOWS_SCROLL_NOTCHES=10
+# leer lassen = Standardwert: 0.15
+WINDOWS_SCROLL_EVENT_DELAY=0.15
+
+# Verzeichnisse
+# leer lassen = Standardwert: logs/
+SCREENSHOT_DIR=logs/
+# leer lassen = Standardwert: custom_elements/
+CUSTOM_ELEMENTS_DIR=custom_elements/
+# APK-Pfad für Install App (optional, z.B. apks/MeineApp.apk)
+APK_PATH=
+
+# Windows-App: vollständiger Pfad zur .exe für Launch App. Wird direkt per %{WINDOWS_APP_PATH}
+# in der jeweiligen .robot-Datei gelesen, kein Python-Default - beim Wechsel der Zielanwendung
+# hier umstellen oder per CLI überschreiben: robot --variable APP_PATH:"<pfad>" tests/<suite>.robot
+# ClickOnce-Pfade sind versionsabhängig - per
+# Get-CimInstance Win32_Process -Filter "Name='<exe>'" ermittelbar, solange die App bereits läuft.
+WINDOWS_APP_PATH=
+
+# Windows-App nach dem Start maximieren (true/false). Details: docs/konfiguration.md
+# leer lassen = Standardwert: false
+WINDOWS_APP_FULLSCREEN=true
+
+# JPG-Qualität für Screenshots (0–100)
+# leer lassen = Standardwert: 85
+SCREENSHOT_JPG_QUALITY=85
+
+# Caching; Details: docs/konfiguration.md
+# leer lassen = Standardwert: false
+UIA_DUMP_CACHE=false
+# leer lassen = Standardwert: logs/cache/
+UIA_CACHE_DIR=logs/cache/
+# leer lassen = Standardwert: false
+VISION_OCR_CACHE=false
+# leer lassen = Standardwert: logs/cache/vision/
+VISION_CACHE_DIR=logs/cache/vision/
+# leer lassen = Standardwert: 25
+VISION_CROP_PAD=25
+
+# Räumliche Relationen (Find Element / Tap Element); Details: docs/konfiguration.md
+# leer lassen = Standardwert: 10
+SPATIAL_OVERLAP_TOLERANCE=10
+# leer lassen = Standardwert: 0
+SPATIAL_NEAR_MAX_DISTANCE=0
+
+# Plattform-Name für Benchmark-Ordner (devcontainer | ubuntu | windows)
+# leer lassen = "unknown"
+BENCHMARK_PLATFORM=
+
+# Logging-Level für die automation-Bibliothek
+# Optionen: DEBUG | INFO | WARNING | ERROR
+# leer lassen = Standardwert: INFO
+LOG_LEVEL=INFO

dynamic_test_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aitimatic GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dynamic_test_engine-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include .env.example
+include docs/konfiguration.md
+include docs/tester_windows_poc.md

dynamic_test_engine-0.1.0/PKG-INFO

@@ -0,0 +1,405 @@
+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).