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

automation/config.py

@@ -0,0 +1,69 @@
+import os
+import logging
+from dotenv import load_dotenv
+
+load_dotenv()
+
+# Logging-Konfiguration: steuert Sichtbarkeit aller automation.*-Logger.
+# Werte: DEBUG | INFO | WARNING | ERROR. Details: docs/konfiguration.md
+LOG_LEVEL = getattr(logging, os.getenv("LOG_LEVEL", "INFO").upper(), logging.INFO)
+
+# Nur den eigenen Logger konfigurieren, nicht den Root-Logger des Host-Prozesses
+# (robot, pytest, ...) - eine Library soll dessen Logging-Setup nicht überschreiben.
+# Hat der Host bereits einen Root-Handler, übernimmt dessen Ausgabe per Propagation
+# (kein eigener Handler, sonst doppelte Zeilen). Sonst eigener Handler als Fallback,
+# damit Logs auch bei direktem Skriptaufruf ohne Host-Logging sichtbar sind.
+_automation_logger = logging.getLogger("automation")
+if not logging.getLogger().handlers and not _automation_logger.handlers:
+    _handler = logging.StreamHandler()
+    _handler.setFormatter(logging.Formatter(
+        "%(asctime)s %(levelname)s [%(name)s] %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    ))
+    _automation_logger.addHandler(_handler)
+_automation_logger.setLevel(LOG_LEVEL)
+
+DEVICE_ID = os.getenv("ANDROID_DEVICE_ID", "")
+DEFAULT_ENGINE = os.getenv("DEFAULT_ENGINE", "auto")
+MATCH_THRESHOLD = float(os.getenv("CUSTOM_ELEMENT_MATCH_THRESHOLD", "0.9"))
+OCR_LANG = os.getenv("OCR_LANGUAGES", "deu+eng")
+OCR_PSM = int(os.getenv("OCR_PSM", "11"))
+OCR_OEM = int(os.getenv("OCR_OEM", "1"))
+OCR_SCALE = float(os.getenv("OCR_SCALE", "1.0"))
+SCROLL_RETRIES = int(os.getenv("SCROLL_RETRIES", "3"))
+VISION_SCROLL_MAX = int(os.getenv("VISION_SCROLL_MAX", "30"))
+# Details zu den Scroll-Werten: docs/konfiguration.md
+VISION_SCROLL_STEP_PERCENT = float(os.getenv("VISION_SCROLL_STEP_PERCENT", "0.20"))
+SCROLL_SAFE_MARGIN_PERCENT = float(os.getenv("SCROLL_SAFE_MARGIN_PERCENT", "0.25"))
+ADB_TIMEOUT = int(os.getenv("ADB_TIMEOUT", "3"))
+ADB_SCREENSHOT_TIMEOUT = int(os.getenv("ADB_SCREENSHOT_TIMEOUT", "10"))
+ADB_SWIPE_DURATION_MS = int(os.getenv("ADB_SWIPE_DURATION_MS", "300"))
+CENTERING_SWIPE_DURATION_MS = int(os.getenv("CENTERING_SWIPE_DURATION_MS", "500"))
+VISION_SCROLL_SWIPE_DURATION_MS = int(os.getenv("VISION_SCROLL_SWIPE_DURATION_MS", "200"))
+OCR_CONFIDENCE = int(os.getenv("OCR_CONFIDENCE", "60"))
+UIA_TIMEOUT = int(os.getenv("UIA_TIMEOUT", "3"))
+UIA_SCROLL_TIMEOUT = int(os.getenv("UIA_SCROLL_TIMEOUT", "8"))
+# Maximale Anzahl diskreter Swipes in der Lernschleife (scroll_to_text).
+UIA_SCROLL_MAX_SWIPES = int(os.getenv("UIA_SCROLL_MAX_SWIPES", "30"))
+UIA_WAIT_IDLE_TIMEOUT = float(os.getenv("UIA_WAIT_IDLE_TIMEOUT", "0.5"))
+UIA_APP_START_TIMEOUT = int(os.getenv("UIA_APP_START_TIMEOUT", "3"))
+# Details zu den Mausrad-Werten (auflösungsabhängig, selbst zu justieren): docs/konfiguration.md
+WINDOWS_SCROLL_NOTCHES = int(os.getenv("WINDOWS_SCROLL_NOTCHES", "10"))
+WINDOWS_SCROLL_EVENT_DELAY = float(os.getenv("WINDOWS_SCROLL_EVENT_DELAY", "0.15"))
+WINDOWS_CLEAR_FIELD_DELAY = float(os.getenv("WINDOWS_CLEAR_FIELD_DELAY", "0.1"))
+SCREENSHOT_DIR = os.getenv("SCREENSHOT_DIR", "logs/")
+CUSTOM_ELEMENTS_DIR = os.getenv("CUSTOM_ELEMENTS_DIR", "custom_elements/")
+APK_PATH = os.getenv("APK_PATH", "")
+JPG_QUALITY = int(os.getenv("SCREENSHOT_JPG_QUALITY", "85"))
+VISION_STABLE_THRESHOLD = float(os.getenv("VISION_STABLE_THRESHOLD", "2.0"))
+
+# Caching (Details: docs/konfiguration.md, docs/recherche_caching.md)
+UIA_DUMP_CACHE = os.getenv("UIA_DUMP_CACHE", "false").lower() == "true"
+UIA_CACHE_DIR = os.getenv("UIA_CACHE_DIR", "logs/cache/")
+VISION_OCR_CACHE = os.getenv("VISION_OCR_CACHE", "false").lower() == "true"
+VISION_CACHE_DIR = os.getenv("VISION_CACHE_DIR", "logs/cache/vision/")
+VISION_CROP_PAD = int(os.getenv("VISION_CROP_PAD", "25"))
+
+# Räumliche Relationen (Find/Tap Element), Details: docs/konfiguration.md
+SPATIAL_OVERLAP_TOLERANCE = int(os.getenv("SPATIAL_OVERLAP_TOLERANCE", "10"))
+SPATIAL_NEAR_MAX_DISTANCE = int(os.getenv("SPATIAL_NEAR_MAX_DISTANCE", "0"))

automation/engines/engine_manager.py

@@ -0,0 +1,382 @@
+from __future__ import annotations
+
+import logging
+import os
+import time
+from datetime import datetime
+from http.client import RemoteDisconnected
+from typing import Any, Callable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy as np
+
+from automation import config
+from automation.engines.uia_engine import UiaEngine
+from automation.engines.vision_base import VisionEngineBase
+from automation.engines.vision_engine import VisionEngine
+from automation.utils import adb
+from automation.utils.device_interface import DeviceInterface
+
+logger = logging.getLogger(__name__)
+
+_uia = UiaEngine()
+_device: DeviceInterface = adb.AdbDevice()
+_vision: VisionEngineBase = VisionEngine(_device)
+_platform: str = "android"
+
+def _uia_relation_not_impl() -> Any:
+    raise NotImplementedError(
+        "Find/Tap Element ist für UIA noch nicht implementiert (DOM-Resolver folgt). "
+        "engine='vision' verwenden."
+    )
+
+
+class EngineManager:
+
+    def _run_explicit(self, action: str, fn: Callable[[], Any], log_label: str, error_label: str) -> Any:
+        logger.info("%s: engine=%s", action, log_label)
+        try:
+            return fn()
+        except Exception as e:
+            path = self._save_error_screenshot(e)
+            raise RuntimeError(f"{action} failed ({error_label}): {e}. Screenshot: {path}") from e
+
+    def _run(self, action: str, uia_fn: Callable[[], Any], vision_fn: Callable[[], Any], engine: str = "auto") -> Any:
+        if engine == "uia":
+            return self._run_explicit(action, uia_fn, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+        # auto
+        try:
+            result = uia_fn()
+            logger.info("%s: engine=uia", action)
+            return result
+        except Exception as uia_error:
+            logger.warning("%s: uia failed (%s), fallback to vision", action, uia_error)
+            return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")
+
+    def _uia_bool_attempt(self, action: str, uia_fn: Callable[[], Any]) -> bool:
+        try:
+            found = uia_fn()
+        except Exception as uia_error:
+            logger.warning("%s: uia failed (%s), fallback to vision", action, uia_error)
+            return False
+        logger.info("%s: engine=uia", action)
+        return found
+
+    def _run_bool(self, action: str, uia_fn: Callable[[], Any], vision_fn: Callable[[], Any], engine: str = "auto") -> bool:
+        if engine == "uia":
+            return self._run_explicit(action, uia_fn, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+        if self._uia_bool_attempt(action, uia_fn):
+            return True
+        return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")
+
+    def _write_screenshot(self, img: np.ndarray, prefix: str) -> str:
+        import cv2
+        os.makedirs(config.SCREENSHOT_DIR, exist_ok=True)
+        ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+        path = os.path.join(config.SCREENSHOT_DIR, f"{prefix}_{ts}.jpg")
+        if not cv2.imwrite(path, img, [cv2.IMWRITE_JPEG_QUALITY, config.JPG_QUALITY]):
+            raise RuntimeError(f"Screenshot write failed: {path}")
+        return path
+
+    def _save_error_screenshot(self, error: Exception | None = None) -> str:
+        try:
+            img = getattr(error, "screenshot", None)
+            if img is None:
+                img = _device.screenshot()
+            path = self._write_screenshot(img, "error")
+            return path
+        except Exception as e:
+            logger.debug("Error screenshot failed: %s", e, exc_info=True)
+            os.makedirs(config.SCREENSHOT_DIR, exist_ok=True)
+            ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+            return os.path.join(config.SCREENSHOT_DIR, f"error_{ts}.jpg (screenshot failed)")
+
+    def connect_device(self, device_id: str | None = None, platform: str = "android") -> None:
+        global _uia, _device, _vision, _platform
+        _platform = platform
+        if platform == "windows":
+            from automation.engines.windows_uia_engine import WindowsUiaEngine  # lazy: Windows-only
+            from automation.utils.windows_host import WindowsHost  # lazy: Windows-only
+            _device = WindowsHost()
+            _uia = WindowsUiaEngine(_device)
+            try:
+                _device.connect(device_id)
+            except RuntimeError as e:
+                # Verbindung fehlgeschlagen (z. B. Prozess läuft noch nicht). Kein Fehler an
+                # sich, wenn direkt danach Launch App aufgerufen wird, das startet den Prozess
+                # frisch und verbindet neu. UIA bleibt bis dahin nachweislich getrennt
+                # (WindowsHost.app is None), nachfolgende Aufrufe fallen im auto-Modus auf
+                # Vision zurück statt unauffällig einen falschen Verbindungsstatus vorzutäuschen.
+                logger.warning(
+                    "connect_device: Windows-Verbindung zu '%s' fehlgeschlagen (%s). "
+                    "UIA bleibt getrennt bis Launch App neu verbindet.", device_id, e
+                )
+            _vision = VisionEngine(_device)
+        else:
+            effective_id = device_id or config.DEVICE_ID or None
+            _uia.connect(effective_id)
+            _device.connect(effective_id)
+
+    def install_app(self, apk_path: str) -> None:
+        if _platform == "windows":
+            raise NotImplementedError(
+                "Install App ist auf Windows nicht verfügbar. App manuell starten."
+            )
+        adb.install_app(apk_path)
+
+    def launch_app(self, package: str, activity: str | None = None, fullscreen: bool = False) -> None:
+        if _platform == "windows":
+            # _uia.launch_app aktualisiert die zentrale Host-Verbindung selbst
+            # (WindowsHost.connect mit stabilem process_name), kein zweiter Connect hier nötig.
+            _uia.launch_app(package, activity=activity, fullscreen=fullscreen)
+            return
+        try:
+            _uia.launch_app(package, activity=activity)
+        except RemoteDisconnected:
+            logger.warning("launch_app: RemoteDisconnected, retry nach 1s")
+            time.sleep(1)
+            _uia.launch_app(package, activity=activity)
+
+    def close_app(self) -> None:
+        if _platform == "windows":
+            _uia.close_app()
+            return
+        raise NotImplementedError(
+            "Close App ist auf Android nicht verfügbar. Launch App stoppt die App bereits vor dem Neustart."
+        )
+
+    def tap_text(self, text: str, engine: str = "auto") -> None:
+        if _platform == "windows":
+            return self._tap_text_windows(text, engine)
+        self._run(
+            f"tap_text('{text}')",
+            lambda: _uia.tap_text(text),
+            lambda: _vision.tap_text(text),
+            engine,
+        )
+
+    def _tap_text_windows(self, text: str, engine: str) -> None:
+        """Windows-Sonderpfad für Tap Text: im auto-Modus fällt nur ein echter Miss
+        (TextNotFoundError) auf Vision zurück, technische UIA-Fehler werden sichtbar."""
+        from automation.engines.windows_uia_engine import TextNotFoundError
+
+        action = f"tap_text('{text}')"
+
+        def uia_fn():
+            return _uia.tap_text(text)
+
+        def vision_fn():
+            return _vision.tap_text(text)
+
+        if engine == "uia":
+            return self._run_explicit(action, uia_fn, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+
+        try:
+            uia_fn()
+            logger.info("%s: engine=uia", action)
+            return
+        except TextNotFoundError as e:
+            logger.info("%s: uia miss (%s), fallback to vision", action, e)
+
+        return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")
+
+    def tap_icon_near_text(self, icon_path: str, text: str, engine: str = "auto") -> None:
+        if _platform == "windows":
+            return self._tap_icon_near_text_windows(icon_path, text, engine)
+        self._run(
+            f"tap_icon_near_text('{text}')",
+            lambda: _uia.tap_icon_near_text(icon_path, text),
+            lambda: _vision.tap_icon_near_text(icon_path, text),
+            engine,
+        )
+
+    def _tap_icon_near_text_windows(self, icon_path: str, text: str, engine: str) -> None:
+        """Windows-Sonderpfad für Tap Icon Near Text: im auto-Modus fällt nur ein echter Miss
+        (IconNotFoundError) auf Vision zurück, technische UIA-Fehler werden sichtbar."""
+        from automation.engines.windows_uia_engine import IconNotFoundError
+
+        action = f"tap_icon_near_text('{text}')"
+
+        def uia_fn():
+            return _uia.tap_icon_near_text(icon_path, text)
+
+        def vision_fn():
+            return _vision.tap_icon_near_text(icon_path, text)
+
+        if engine == "uia":
+            return self._run_explicit(action, uia_fn, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+
+        try:
+            uia_fn()
+            logger.info("%s: engine=uia", action)
+            return
+        except IconNotFoundError as e:
+            logger.info("%s: uia miss (%s), fallback to vision", action, e)
+            return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")
+        except Exception as e:
+            logger.warning("%s: uia technical error (%s), no fallback", action, e)
+            path = self._save_error_screenshot(e)
+            raise RuntimeError(f"{action} failed (uia): {e}. Screenshot: {path}") from e
+
+    def input_text(self, locator: str, text: str, anchor: str | None = None,
+                   engine: str = "auto") -> None:
+        if _platform == "windows":
+            return self._input_text_windows(locator, text, anchor, engine)
+        self._run(
+            f"input_text('{locator}')",
+            lambda: _uia.input_text(locator, text, anchor=anchor),
+            lambda: _vision.input_text(locator, text),
+            engine,
+        )
+
+    def _input_text_windows(self, locator: str, text: str, anchor: str | None, engine: str) -> None:
+        """Windows-Sonderpfad für Input Text: im auto-Modus fällt nur ein echter Miss
+        (FieldNotFoundError) auf Vision zurück, technische Fehler und Mehrdeutigkeit
+        werden sichtbar statt roh durchgereicht."""
+        from automation.engines.windows_uia_engine import FieldNotFoundError
+
+        action = f"input_text('{locator}')"
+
+        def uia_fn():
+            return _uia.input_text(locator, text, anchor=anchor)
+
+        def vision_fn():
+            return _vision.input_text(locator, text)
+
+        if engine == "uia":
+            return self._run_explicit(action, uia_fn, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+
+        try:
+            uia_fn()
+            logger.info("%s: engine=uia", action)
+            return
+        except FieldNotFoundError as e:
+            logger.info("%s: uia miss (%s), fallback to vision", action, e)
+            return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")
+        except Exception as e:
+            logger.warning("%s: uia technical error (%s), no fallback", action, e)
+            path = self._save_error_screenshot(e)
+            raise RuntimeError(f"{action} failed (uia): {e}. Screenshot: {path}") from e
+
+    def field_value_should_be(self, locator: str, expected: str, anchor: str | None = None,
+                              engine: str = "uia") -> None:
+        """Windows-only, kein Vision-Pfad, kein auto, kein Fallback: prüft den tatsächlichen
+        UIA-Feldwert (ValuePattern) gegen expected."""
+        if _platform != "windows":
+            raise NotImplementedError("Field Value Should Be ist nur auf Windows verfügbar.")
+        if engine != "uia":
+            raise ValueError(f"Field Value Should Be unterstützt nur engine='uia', nicht '{engine}'.")
+        action = f"field_value_should_be('{locator}')"
+        self._run_explicit(
+            action, lambda: _uia.field_value_should_be(locator, expected, anchor=anchor), "uia", "uia"
+        )
+
+    def scroll_to_text(self, text: str, anchor: str | None = None, relation: str = "near",
+                       engine: str = "auto") -> bool:
+        return self._run_bool(
+            f"scroll_to_text('{text}')",
+            lambda: _uia.scroll_to_text(text),
+            lambda: _vision.scroll_to_text(text, anchor=anchor, relation=relation),
+            engine,
+        )
+
+    def text_exists(self, text: str, engine: str = "auto") -> bool:
+        if _platform == "windows":
+            return self._text_exists_windows(text, engine)
+        return self._run_bool(
+            f"text_exists('{text}')",
+            lambda: _uia.text_exists(text),
+            lambda: _vision.text_exists(text),
+            engine,
+        )
+
+    def _text_exists_windows(self, text: str, engine: str) -> bool:
+        """Windows-Sonderpfad für Text Should Exist: im auto-Modus fällt nur ein echter
+        UIA-Miss (False) auf Vision zurück, technische UIA-Fehler werden sichtbar."""
+        action = f"text_exists('{text}')"
+
+        def uia_fn():
+            return _uia.text_exists(text)
+
+        def vision_fn():
+            return _vision.text_exists(text)
+        if engine == "uia":
+            return self._run_explicit(action, uia_fn, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+        found = self._run_explicit(action, uia_fn, "uia", "uia")
+        if found:
+            return True
+        logger.info("%s: uia miss, fallback to vision", action)
+        return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")
+
+    def take_screenshot(self, name: str = "screenshot") -> str:
+        img = _device.screenshot()
+        return self._write_screenshot(img, name)
+
+    def move_mouse(self, x: int, y: int) -> None:
+        _device.move_mouse(x, y)
+
+    def find_element(self, target: str, anchor: str, relation: str = "near",
+                     kind: str = "auto", engine: str = "auto") -> tuple[int, int]:
+        if _platform == "windows":
+            return self._find_element_windows(target, anchor, relation, kind, engine)
+        return self._run(
+            f"find_element('{target}' {relation} '{anchor}')",
+            _uia_relation_not_impl,
+            lambda: _vision.find_element(target, anchor, relation=relation, kind=kind),
+            engine,
+        )
+
+    def _find_element_windows(self, target: str, anchor: str, relation: str, kind: str,
+                              engine: str) -> tuple[int, int]:
+        """Windows-Dispatch für Find Element: UIA hat noch keinen echten Pfad, loggt das
+        deshalb als 'nicht implementiert' statt fälschlich als Fallback-Fehlschlag."""
+        action = f"find_element('{target}' {relation} '{anchor}')"
+
+        def vision_fn():
+            return _vision.find_element(target, anchor, relation=relation, kind=kind)
+
+        if engine == "uia":
+            return self._run_explicit(action, _uia_relation_not_impl, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+        logger.info("%s: uia not implemented (DOM-Resolver folgt), using vision", action)
+        return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")
+
+    def tap_element(self, target: str, anchor: str, relation: str = "near",
+                    kind: str = "auto", engine: str = "auto") -> None:
+        if _platform == "windows":
+            return self._tap_element_windows(target, anchor, relation, kind, engine)
+        self._run(
+            f"tap_element('{target}' {relation} '{anchor}')",
+            _uia_relation_not_impl,
+            lambda: _vision.tap_element(target, anchor, relation=relation, kind=kind),
+            engine,
+        )
+
+    def _tap_element_windows(self, target: str, anchor: str, relation: str, kind: str,
+                             engine: str) -> None:
+        """Windows-Dispatch für Tap Element (Cluster F), Gegenstück zu _find_element_windows,
+        gleiche Begründung."""
+        action = f"tap_element('{target}' {relation} '{anchor}')"
+
+        def vision_fn():
+            return _vision.tap_element(target, anchor, relation=relation, kind=kind)
+
+        if engine == "uia":
+            return self._run_explicit(action, _uia_relation_not_impl, "uia", "uia")
+        if engine == "vision":
+            return self._run_explicit(action, vision_fn, "vision", "vision")
+        logger.info("%s: uia not implemented (DOM-Resolver folgt), using vision", action)
+        return self._run_explicit(action, vision_fn, "vision (fallback)", "both engines")

automation/engines/uia_engine.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import logging
+import re
+import time
+import xml.etree.ElementTree as ET
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import uiautomator2 as u2
+
+from automation import config
+from automation.utils import adb, scroll_centering
+from automation.utils.cache import JsonFileCache
+
+logger = logging.getLogger(__name__)
+
+_d: u2.Device | None = None
+_cache = JsonFileCache(config.UIA_CACHE_DIR)
+_adb_device = adb.AdbDevice()
+
+
+def _screen_key() -> tuple[str, str, str, str] | None:
+    """Stabile Screen-Identität für den UIA-Cache. None bei Fehler → Cache übersprungen."""
+    try:
+        activity = adb.current_activity()
+        if not activity or "/" not in activity:
+            return None
+        package = activity.split("/", 1)[0]
+        return package, activity, adb.app_version(package), adb.device_fingerprint()
+    except Exception:
+        return None
+
+
+def _parse_bounds_str(bounds_str: str) -> dict:
+    """'[l,t][r,b]' → {'left':l, 'top':t, 'right':r, 'bottom':b} oder {} bei Parse-Fehler."""
+    nums = list(map(int, re.findall(r"-?\d+", bounds_str)))
+    if len(nums) < 4:
+        return {}
+    return {"left": nums[0], "top": nums[1], "right": nums[2], "bottom": nums[3]}
+
+def _snapshot_text_y_and_icon_bounds(resource_id: str, text: str) -> tuple[int, list[dict]]:
+    """Ein einziger dump_hierarchy-RPC statt N+1 .info-Roundtrips; eliminiert die Race-Condition."""
+    xml_str = _d.dump_hierarchy(compressed=True)
+    root = ET.fromstring(xml_str)
+    text_y = None
+    for node in root.iter():
+        if node.get("text") == text:
+            b = _parse_bounds_str(node.get("bounds", ""))
+            if b:
+                text_y = (b["top"] + b["bottom"]) // 2
+                break
+    if text_y is None:
+        raise RuntimeError(f"Text not found in hierarchy snapshot: '{text}'")
+    bounds_list = [
+        b for node in root.iter()
+        if node.get("resource-id") == resource_id
+        for b in [_parse_bounds_str(node.get("bounds", ""))]
+        if b
+    ]
+    return text_y, bounds_list
+
+
+class UiaEngine:
+
+    def connect(self, device_id: str | None = None) -> None:
+        import uiautomator2 as u2
+        global _d
+        _d = u2.connect(device_id)
+
+    def _require_connected(self) -> None:
+        if _d is None:
+            raise RuntimeError("Device not connected. Call Connect Device first.")
+
+    def launch_app(self, package: str, activity: str | None = None) -> None:
+        self._require_connected()
+        try:
+            current_pkg = _d.app_current().get("package", "")
+            if current_pkg and current_pkg != package:
+                _d.app_stop(current_pkg)
+        except Exception:
+            pass
+        _d.app_stop(package)
+        _d.press("home")
+        _d.app_start(package, activity=activity, wait=True)
+        _d(packageName=package).wait(timeout=config.UIA_APP_START_TIMEOUT)
+
+    def text_exists(self, text: str) -> bool:
+        self._require_connected()
+        return _d(text=text).exists(timeout=config.UIA_TIMEOUT)
+
+    def tap_text(self, text: str) -> None:
+        self._require_connected()
+        el = _d(text=text)
+        if not el.exists(timeout=config.UIA_TIMEOUT):
+            raise RuntimeError(f"Text not found: '{text}'")
+        el.click()
+
+    def input_text(self, locator: str, text: str) -> None:
+        """Feld per UIA-Locator (resourceId oder text) finden und Text setzen."""
+        self._require_connected()
+        el = _d(resourceId=locator) if ":" in locator else _d(text=locator)
+        if not el.exists(timeout=config.UIA_TIMEOUT):
+            raise RuntimeError(f"Eingabefeld nicht gefunden: '{locator}'")
+        el.set_text(text)
+
+    def tap_icon_near_text(self, icon_path: str, text: str) -> None:
+        self._require_connected()
+        resource_id = (
+            icon_path
+            if ":" in icon_path and not icon_path.endswith(".png")
+            else "android:id/icon"
+        )
+        if not _d(text=text).exists(timeout=config.UIA_TIMEOUT):
+            raise RuntimeError(f"Text not found: '{text}'")
+        text_y, bounds_list = _snapshot_text_y_and_icon_bounds(resource_id, text)
+        if not bounds_list:
+            raise RuntimeError(
+                f"No icons found via resource-id='{resource_id}'. "
+                "For apps without system icon IDs use engine='vision'."
+            )
+        icon_count = len(bounds_list)
+        closest = min(
+            range(icon_count),
+            key=lambda i: abs(
+                (bounds_list[i]["top"] + bounds_list[i]["bottom"]) // 2 - text_y
+            ),
+        )
+        b = bounds_list[closest]
+        _d.click((b["left"] + b["right"]) // 2, (b["top"] + b["bottom"]) // 2)
+
+    def _center_after_scroll(self, text: str) -> bool:
+        try:
+            bounds = _d(text=text).info.get("bounds", {})
+            screen_h = _d.info.get("displayHeight", 1920)
+            screen_w = _d.info.get("displayWidth", 1080)
+            if not bounds:
+                logger.warning("_center_after_scroll: keine bounds für '%s' — Zentrierung übersprungen", text)
+                return False
+            el_center_y = (bounds.get("top", 0) + bounds.get("bottom", screen_h)) // 2
+            logger.info("_center_after_scroll el_center_y=%s screen_h=%s", el_center_y, screen_h)
+            return scroll_centering.center_in_safe_area(_adb_device, screen_w // 2, screen_h, el_center_y)
+        except Exception as e:
+            logger.warning("_center_after_scroll failed: %s: %s", type(e).__name__, e)
+            return False
+
+    def scroll_to_text(self, text: str) -> bool:
+        self._require_connected()
+
+        # Kein Scroll nötig wenn Text bereits sichtbar (schützt auch gegen Cache-Vergiftung mit k=0)
+        if _d(text=text).exists(timeout=config.UIA_TIMEOUT):
+            return True
+
+        # Pfad 1: Cache-Hit (nur wenn UIA_DUMP_CACHE)
+        if config.UIA_DUMP_CACHE:
+            try:
+                key = _screen_key()
+                if key:
+                    package, activity, version, device_fp = key
+                    action_key = f"scroll_to_text|text={text}|direction=down"
+                    hint = _cache.get_uia_hint(package, activity, version, device_fp, action_key)
+                    if hint is not None:
+                        k = hint.get("swipes_k", 0)
+                        scroller = _d(scrollable=True)
+                        for _ in range(k):
+                            scroller.scroll.forward()
+                        # bis zu 2 Extra-Swipes für Off-by-One
+                        for extra in range(3):
+                            if _d(text=text).exists(timeout=config.UIA_TIMEOUT):
+                                logger.info("UIA_CACHE event=hit keyword=scroll_to_text target=%r swipes_k=%d", text, k + extra)
+                                centered = self._center_after_scroll(text)
+                                if not centered:
+                                    _d.jsonrpc.waitForIdle(int(config.UIA_WAIT_IDLE_TIMEOUT * 1000))
+                                return True
+                            scroller.scroll.forward()
+                        logger.info("UIA_CACHE event=verify_fail keyword=scroll_to_text target=%r swipes_k=%d", text, k)
+            except Exception as e:
+                logger.warning("UIA cache lookup failed: %s", e)
+
+        # Pfad 2: Diskrete Lernschleife (primär, Cache-Miss)
+        scroller = _d(scrollable=True)
+        for swipe_idx in range(1, config.UIA_SCROLL_MAX_SWIPES + 1):
+            try:
+                scroller.scroll.forward()
+            except Exception:
+                break
+            if _d(text=text).exists(timeout=1):
+                if config.UIA_DUMP_CACHE:
+                    try:
+                        key = _screen_key()
+                        if key:
+                            package, activity, version, device_fp = key
+                            action_key = f"scroll_to_text|text={text}|direction=down"
+                            _cache.put_uia_hint(package, activity, version, device_fp, action_key,
+                                                {"swipes_k": swipe_idx})
+                            logger.info("UIA_CACHE event=miss keyword=scroll_to_text target=%r swipes_k=%d", text, swipe_idx)
+                    except Exception as e:
+                        logger.warning("UIA cache write failed: %s", e)
+                centered = self._center_after_scroll(text)
+                if not centered:
+                    _d.jsonrpc.waitForIdle(int(config.UIA_WAIT_IDLE_TIMEOUT * 1000))
+                return True
+
+        # Pfad 3: Letzter Notausgang — original scroll.to
+        for attempt in range(1, config.SCROLL_RETRIES + 1):
+            try:
+                t0 = time.monotonic()
+                result = _d(scrollable=True).scroll.to(text=text)
+                elapsed_ms = int((time.monotonic() - t0) * 1000)
+                logger.info("scroll attempt=%s result=%s elapsed_ms=%s", attempt, result, elapsed_ms)
+                if result:
+                    centered = self._center_after_scroll(text)
+                    if not centered:
+                        _d.jsonrpc.waitForIdle(int(config.UIA_WAIT_IDLE_TIMEOUT * 1000))
+                    return True
+            except Exception as e:
+                elapsed_ms = int((time.monotonic() - t0) * 1000)
+                logger.warning("scroll attempt=%s failed after %sms: %s: %s",
+                               attempt, elapsed_ms, type(e).__name__, e)
+        return _d(text=text).exists(timeout=config.UIA_SCROLL_TIMEOUT)