dynamic-test-engine 0.1.0__py3-none-any.whl

dynamic_test_engine-0.1.0.dist-info/METADATA

@@ -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).

dynamic_test_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+automation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+automation/config.py,sha256=KdYFexk7wHNktkOLCRdRZavGnlJ7I9qFcztXAfGTaoY,3905
+automation/engines/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+automation/engines/engine_manager.py,sha256=PZqaGD58MdofrNdlUSOmyLBe9z92028aBEFZ2S_olkI,16907
+automation/engines/uia_engine.py,sha256=Wt8F5Wztd0F4g_x_xMbPBuAafF8axhG9CPUTAdhlgok,9581
+automation/engines/vision_base.py,sha256=TRyVJsRy9e3ZKCtBh2ijxKZ86e1Z9wQTRFrJFnZC4Tc,928
+automation/engines/vision_engine.py,sha256=vGvh_M9hBtRq8fejN6I2-R1vc7Ww0FC-ep0qbJuOc_Y,23401
+automation/engines/windows_uia_engine.py,sha256=OETJIOVassh9q4H4j3AA1qFuMtPv3-24aIqENC7Pscc,14816
+automation/keywords/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+automation/keywords/automation_keywords.py,sha256=JCebZ5fWz9bv--7Wj8N9M02TW_C1CsdfsP_BKGPZv7Y,3839
+automation/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+automation/utils/adb.py,sha256=DmXOMqayoOGGEAwktxszbA2u-KWAcn8h6DrEkj7DtqE,8651
+automation/utils/cache.py,sha256=xPT2ZLAJ5kaMTVtp68-bmltio5Pr2ozjxerZARp1BoI,5967
+automation/utils/device_interface.py,sha256=i3hCIpnQXaFi0SDuCpglDqJQWKAEgDqGvVrgWgexwso,2487
+automation/utils/image_processing.py,sha256=I_eEQHwOf_9bgoimlhqIEwlmsxB9EM0F8ngPWxfgi_c,9963
+automation/utils/scroll_centering.py,sha256=kT8_jA_PU28_NQHRQ9PEbfvoDVr-ltPkoXIO_nkJixo,1927
+automation/utils/spatial.py,sha256=Cs-CekhUsYNmHEg2TQ_IGedOqLoKKOzhsE4RAdFlTvI,2493
+automation/utils/windows_host.py,sha256=JcL-UteiWjeDn85qDlnJaZI-Ud5SN943q5NXfuR1XyM,14442
+dynamic_test_engine-0.1.0.dist-info/licenses/LICENSE,sha256=UpdA93iYE9FLHC2XEqO4MAmHguqdf3zrMMczTfp7LwY,1071
+dynamic_test_engine-0.1.0.dist-info/METADATA,sha256=eEcTNqlDqlw_KLzbzdTZ-xiiS1oYJIj0Sb2Mgno9qTg,15555
+dynamic_test_engine-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+dynamic_test_engine-0.1.0.dist-info/top_level.txt,sha256=6FPw8tX4RykuC6Wq7ti_JjKbNFsg6OSMwQB35ne8Ug0,11
+dynamic_test_engine-0.1.0.dist-info/RECORD,,

dynamic_test_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

dynamic_test_engine-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+automation