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

automation/engines/windows_uia_engine.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import logging
+import subprocess
+import time
+from typing import TYPE_CHECKING
+
+from automation import config
+from automation.utils import spatial
+
+if TYPE_CHECKING:
+    from automation.utils.windows_host import WindowsHost
+
+logger = logging.getLogger(__name__)
+
+
+class TextNotFoundError(RuntimeError):
+    """Echter Miss: Text nach vollständiger UIA-Suche nicht gefunden, getrennt von
+    technischen Fehlern damit engine_manager.auto nur diesen Fall als Fallback behandelt."""
+
+
+class FieldNotFoundError(RuntimeError):
+    """Echter Miss: Eingabefeld oder Anker-Text nicht gefunden, oder der Treffer ist ein
+    Container ohne editierbares Child. Mehrdeutigkeit ohne anchor bleibt RuntimeError."""
+
+
+class IconNotFoundError(RuntimeError):
+    """Echter Miss: Anker-Text oder Icon-Element für Tap Icon Near Text nicht gefunden, oder
+    kein Kandidat erfüllt 'near' innerhalb von SPATIAL_NEAR_MAX_DISTANCE."""
+
+
+class WindowsUiaEngine:
+
+    def __init__(self, host: "WindowsHost") -> None:
+        """host ist die einzige Quelle des pywinauto.Application-Handles."""
+        self._host = host
+
+    def _require_connected(self) -> None:
+        if self._host.app is None:
+            raise RuntimeError("Kein Windows-Prozess verbunden. Connect Device zuerst aufrufen.")
+
+    @staticmethod
+    def _tasklist_pid(exe_name: str) -> int | None:
+        """Liest die PID von exe_name per tasklist, None wenn (noch) nicht gefunden."""
+        result = subprocess.run(
+            ["tasklist", "/fi", f"IMAGENAME eq {exe_name}", "/fo", "csv", "/nh"],
+            capture_output=True,
+            encoding="oem",
+            errors="replace",
+        )
+        matches = [ln for ln in result.stdout.strip().splitlines() if exe_name.lower() in ln.lower()]
+        return int(matches[0].split('","')[1]) if matches else None
+
+    @classmethod
+    def _poll(cls, fn, timeout: float, interval: float):
+        """Ruft fn() wiederholt auf bis ein truthy Ergebnis vorliegt oder timeout erreicht ist."""
+        deadline = time.time() + timeout
+        while True:
+            result = fn()
+            if result:
+                return result
+            if time.time() >= deadline:
+                return None
+            time.sleep(interval)
+
+    @classmethod
+    def _pid_by_name(cls, exe_name: str, timeout: float) -> int:
+        """Ermittelt die aktuelle PID eines laufenden Prozesses per tasklist, mit Retry bis
+        timeout, statt der ggf. veralteten PID von Application.start()."""
+        pid = cls._poll(lambda: cls._tasklist_pid(exe_name), timeout, interval=0.3)
+        if pid is None:
+            raise RuntimeError(f"Prozess '{exe_name}' nach dem Start nicht gefunden.")
+        return pid
+
+    def _wait_for_window(self, timeout: float):
+        """Wartet per Retry auf das erste Top-Level-Fenster des Prozesses, da top_window()
+        ohne eingebautes Polling sofort scheitert, solange noch keins existiert."""
+        def try_top_window():
+            try:
+                return self._host.app.top_window()
+            except Exception:
+                return None
+
+        window = self._poll(try_top_window, timeout, interval=0.3)
+        if window is None:
+            raise RuntimeError("Kein Fenster für den gestarteten Prozess gefunden.")
+        return window
+
+    def launch_app(self, exe_path: str, activity: str | None = None, fullscreen: bool = False) -> None:
+        """Beendet eine ggf. laufende Instanz von exe_path und startet sie neu, damit jeder
+        Testlauf von einem definierten Ausgangszustand beginnt. activity wird ignoriert."""
+        import os
+        import subprocess as sp
+        from pywinauto import Application  # lazy: nur auf Windows installierbar
+
+        exe_name = os.path.basename(exe_path)
+        sp.run(["taskkill", "/f", "/im", exe_name], capture_output=True)
+
+        Application(backend="uia").start(exe_path, work_dir=os.path.dirname(exe_path))
+        pid = self._pid_by_name(exe_name, timeout=config.UIA_APP_START_TIMEOUT)
+        self._host.connect(str(pid), process_name=exe_name)
+
+        window = self._wait_for_window(config.UIA_APP_START_TIMEOUT)
+        window.wait("ready", timeout=config.UIA_APP_START_TIMEOUT)
+        if fullscreen:
+            try:
+                window.maximize()
+            except Exception:
+                # Manche Fenster exponieren kein UIA-WindowPattern. Fallback über die
+                # native Windows-API, die nur den Fensterhandle braucht statt UIA-Patterns.
+                import win32con
+                import win32gui
+                win32gui.ShowWindow(window.handle, win32con.SW_MAXIMIZE)
+
+    def close_app(self) -> None:
+        """Beendet die aktuell verbundene App PID-scoped, siehe WindowsHost.close."""
+        self._host.close()
+
+    def _window(self):
+        """Delegiert an WindowsHost.window(), damit UIA-Suche und Vision-Crop garantiert
+        dasselbe Fenster verwenden."""
+        return self._host.window()
+
+    @staticmethod
+    def _descendants(window, **kwargs):
+        """auto_id/title sind keine gültigen build_condition()-Properties, werden deshalb
+        vorab entfernt und danach lokal gegen automation_id()/window_text() abgeglichen."""
+        auto_id = kwargs.pop("auto_id", None)
+        title = kwargs.pop("title", None)
+        matches = window.descendants(cache_enable=True, **kwargs)
+        if auto_id is not None:
+            matches = [m for m in matches if m.automation_id() == auto_id]
+        if title is not None:
+            matches = [m for m in matches if m.window_text() == title]
+        return matches
+
+    @classmethod
+    def _find_descendant(cls, window, timeout: float, **kwargs):
+        """Sucht ein Nachfahren-Element per descendants() mit Retry bis timeout, da
+        UIAWrapper-Fenster kein eingebautes child_window()/.exists()-Polling kennen."""
+        matches = cls._poll(lambda: cls._descendants(window, **kwargs), timeout, interval=0.2)
+        return matches[0] if matches else None
+
+    @classmethod
+    def _find_by_text(cls, window, timeout: float, text: str):
+        """Sucht zuerst per title, dann per auto_id, damit beide Arten sprechender
+        UIA-Properties abgedeckt sind."""
+        found = cls._find_descendant(window, timeout, title=text)
+        if found is not None:
+            return found
+        return cls._find_descendant(window, timeout, auto_id=text)
+
+    def text_exists(self, text: str) -> bool:
+        """Prüft UIA-Tree-Existenz von sichtbarem Text (title-Property), keine pixelgenaue
+        Sichtbarkeitsprüfung. Technische Fehler laufen ungefangen durch, kein stiller False."""
+        self._require_connected()
+        return self._find_descendant(self._window(), config.UIA_TIMEOUT, title=text) is not None
+
+    def tap_text(self, text: str) -> None:
+        """Klickt Text per UIA. Ein echter Miss wirft TextNotFoundError statt RuntimeError,
+        damit engine_manager im auto-Modus nur diesen Fall als Fallback behandelt."""
+        self._require_connected()
+        el = self._find_by_text(self._window(), config.UIA_TIMEOUT, text)
+        if el is None:
+            raise TextNotFoundError(f"Text nicht gefunden: '{text}'")
+        el.click_input()
+
+    @staticmethod
+    def _closest_by_point(candidates, ref_x: int, ref_y: int):
+        """Wählt aus candidates das Element mit dem geringsten 2D-Abstand zu (ref_x, ref_y).
+        Reine Y-Distanz reicht nicht bei horizontal angeordneten Elementen gleicher Höhe."""
+        def dist_sq(el) -> int:
+            rect = el.rectangle()
+            cx = (rect.left + rect.right) // 2
+            cy = (rect.top + rect.bottom) // 2
+            return (cx - ref_x) ** 2 + (cy - ref_y) ** 2
+
+        return min(candidates, key=dist_sq)
+
+    @staticmethod
+    def _rect_to_box(rect) -> dict:
+        """UIA-Rectangle in das von spatial.py erwartete Box-Format (left/top/width/height)
+        übersetzen. Keine Koordinatenumrechnung nötig, UIA liefert bereits Desktop-Pixel."""
+        return {
+            "left": rect.left,
+            "top": rect.top,
+            "width": rect.right - rect.left,
+            "height": rect.bottom - rect.top,
+        }
+
+    @classmethod
+    def _resolve_editable(cls, el, locator: str):
+        """Löst el auf das tatsächlich editierbare Element auf. Ist el bereits Edit, wird es
+        unverändert zurückgegeben, sonst gezielt nach dem einen Edit-Kind im Container gesucht."""
+        if el.element_info.control_type == "Edit":
+            return el
+        children = cls._descendants(el, control_type="Edit")
+        if not children:
+            raise FieldNotFoundError(
+                f"Kein editierbares Child (ControlType=Edit) in Container '{locator}' gefunden."
+            )
+        if len(children) > 1:
+            raise RuntimeError(
+                f"Mehrdeutig: {len(children)} editierbare Children in Container '{locator}'."
+            )
+        return children[0]
+
+    def _resolve_field_element(self, locator: str, anchor: str | None = None):
+        """Löst locator (+ optionalem anchor) auf das editierbare Zielelement auf; von
+        input_text() und field_value() geteilt, damit beide dasselbe Element treffen."""
+        window = self._window()
+        candidates = self._descendants(window, auto_id=locator)
+        if not candidates:
+            raise FieldNotFoundError(f"Eingabefeld nicht gefunden: '{locator}'")
+        if len(candidates) == 1:
+            el = candidates[0]
+        elif anchor is not None:
+            anchor_el = self._find_by_text(window, config.UIA_TIMEOUT, anchor)
+            if anchor_el is None:
+                raise FieldNotFoundError(f"Anker-Text nicht gefunden: '{anchor}'")
+            rect = anchor_el.rectangle()
+            ref_x = (rect.left + rect.right) // 2
+            ref_y = (rect.top + rect.bottom) // 2
+            el = self._closest_by_point(candidates, ref_x, ref_y)
+        else:
+            raise RuntimeError(
+                f"Mehrdeutig: {len(candidates)} Elemente mit AutomationId='{locator}'. anchor angeben."
+            )
+        return self._resolve_editable(el, locator)
+
+    def input_text(self, locator: str, text: str, anchor: str | None = None) -> None:
+        """Setzt den Wert eines per AutomationId gefundenen Feldes (ValuePattern, kein
+        Keyboard-Event)."""
+        self._require_connected()
+        el = self._resolve_field_element(locator, anchor)
+        el.set_edit_text(text)
+
+    def field_value(self, locator: str, anchor: str | None = None) -> str:
+        """Liest den aktuellen Wert eines Feldes per AutomationId. get_value() primär,
+        window_text() nur als Fallback (siehe WindowsHost.value_region())."""
+        self._require_connected()
+        el = self._resolve_field_element(locator, anchor)
+        try:
+            return el.get_value()
+        except Exception:
+            return el.window_text()
+
+    def field_value_should_be(self, locator: str, expected: str, anchor: str | None = None) -> None:
+        """Prüft den tatsächlichen UIA-Feldwert gegen expected. AssertionError mit Ist/Soll
+        bei Abweichung."""
+        actual = self.field_value(locator, anchor)
+        if actual != expected:
+            raise AssertionError(
+                f"Feldwert von '{locator}': erwartet '{expected}', tatsächlich '{actual}'"
+            )
+
+    def tap_icon_near_text(self, icon_path: str, text: str) -> None:
+        """Klickt das Element mit AutomationId==icon_path, das 'near' zum Anker-Text liegt.
+        Ein echter Miss wirft IconNotFoundError, damit engine_manager im auto-Modus nur
+        diesen Fall als Fallback behandelt."""
+        self._require_connected()
+        window = self._window()
+        text_el = self._find_by_text(window, config.UIA_TIMEOUT, text)
+        if text_el is None:
+            raise IconNotFoundError(f"Anker-Text nicht gefunden: '{text}'")
+
+        candidates = self._descendants(window, auto_id=icon_path)
+        if not candidates:
+            raise IconNotFoundError(
+                f"Kein Element mit AutomationId='{icon_path}' gefunden. "
+                "Für Apps ohne AutomationIds engine='vision' verwenden."
+            )
+
+        anchor_box = self._rect_to_box(text_el.rectangle())
+        pairs = [(self._rect_to_box(c.rectangle()), c) for c in candidates]
+        candidate_boxes = [box for box, _ in pairs]
+
+        best = spatial.resolve(
+            anchor_box,
+            candidate_boxes,
+            "near",
+            overlap_tol=config.SPATIAL_OVERLAP_TOLERANCE,
+            max_distance=config.SPATIAL_NEAR_MAX_DISTANCE,
+        )
+        if best is None:
+            raise IconNotFoundError(
+                f"Kein Element mit AutomationId='{icon_path}' erfüllt 'near' zu '{text}' "
+                f"(SPATIAL_NEAR_MAX_DISTANCE={config.SPATIAL_NEAR_MAX_DISTANCE})."
+            )
+
+        for box, el in pairs:
+            if box == best:
+                el.click_input()
+                return
+
+        raise RuntimeError("Interner Fehler: spatial-Treffer konnte keinem UIA-Element zugeordnet werden.")
+
+    def scroll_to_text(self, text: str) -> bool:
+        """Scrollt per UIA-ScrollPattern bis text sichtbar. Gibt False zurück wenn nach max. Swipes nicht gefunden."""
+        self._require_connected()
+        window = self._window()
+
+        try:
+            if self._find_by_text(window, config.UIA_TIMEOUT, text) is not None:
+                return True
+        except Exception:
+            pass
+
+        seen_rects = set()
+        candidates = []
+        for scrollbar in window.descendants(control_type="ScrollBar"):
+            try:
+                container = scrollbar.parent()
+            except Exception:
+                continue
+            rect = container.rectangle()
+            key = (rect.left, rect.top, rect.right, rect.bottom)
+            if key in seen_rects:
+                continue
+            seen_rects.add(key)
+            candidates.append(container)
+        if not candidates:
+            candidates = [window]
+
+        for candidate in candidates:
+            if self._try_scroll_candidate(candidate, window, text):
+                return True
+
+        return False
+
+    def _try_scroll_candidate(self, candidate, window, text: str) -> bool:
+        """Scrollt candidate bis zu UIA_SCROLL_MAX_SWIPES mal und sucht text nach jedem Schritt.
+        False auch wenn candidate kein ScrollPattern hat (nächster Kandidat wird dann versucht)."""
+        for _ in range(config.UIA_SCROLL_MAX_SWIPES):
+            try:
+                candidate.scroll("down", "page")
+            except Exception:
+                return False
+
+            time.sleep(0.2)
+            try:
+                if self._find_by_text(window, 1, text) is not None:
+                    return True
+            except Exception:
+                pass
+
+        return False

automation/keywords/automation_keywords.py

@@ -0,0 +1,83 @@
+from robot.api.deco import keyword
+
+from automation.engines.engine_manager import EngineManager
+
+_manager = EngineManager()
+
+
+class AutomationKeywords:
+    ROBOT_LIBRARY_SCOPE = "GLOBAL"
+
+    @keyword
+    def connect_device(self, device_id: str | None = None, platform: str = "android") -> None:
+        _manager.connect_device(device_id, platform=platform)
+
+    @keyword
+    def install_app(self, apk_path: str) -> None:
+        _manager.install_app(apk_path)
+
+    @keyword
+    def launch_app(self, package: str, activity: str | None = None, fullscreen: bool = False) -> None:
+        """fullscreen: nur auf Windows wirksam, maximiert das Fenster nach dem Start."""
+        _manager.launch_app(package, activity=activity, fullscreen=fullscreen)
+
+    @keyword
+    def close_app(self) -> None:
+        """Nur auf Windows verfügbar, beendet die aktuell verbundene App PID-scoped."""
+        _manager.close_app()
+
+    @keyword
+    def tap_text(self, text: str, engine: str = "auto") -> None:
+        _manager.tap_text(text, engine=engine)
+
+    @keyword
+    def input_text(self, locator: str, text: str, anchor: str | None = None,
+                   engine: str = "auto") -> None:
+        """anchor: optionale Disambiguierung bei mehreren Elementen mit derselben AutomationId
+        (Abstand zum Anker-Text). Gilt nur für engine=uia, bei engine=vision wird er ignoriert."""
+        _manager.input_text(locator, text, anchor=anchor, engine=engine)
+
+    @keyword
+    def tap_icon_near_text(self, icon_path: str, text: str, engine: str = "auto") -> None:
+        _manager.tap_icon_near_text(icon_path, text, engine=engine)
+
+    @keyword
+    def field_value_should_be(self, locator: str, expected: str, anchor: str | None = None,
+                              engine: str = "uia") -> None:
+        """Prüft den tatsächlichen UIA-Feldwert (ValuePattern) gegen expected. Windows-only,
+        kein Vision-Pfad, kein engine=auto."""
+        _manager.field_value_should_be(locator, expected, anchor=anchor, engine=engine)
+
+    @keyword
+    def scroll_to_text(self, text: str, anchor: str | None = None, relation: str = "near",
+                       engine: str = "auto") -> bool:
+        """anchor/relation disambiguieren bei Duplikat-Text und verschieben die Scroll-Region
+        weg von der Bildschirmmitte. Gelten nur für engine=vision, siehe Find Element."""
+        return _manager.scroll_to_text(text, anchor=anchor, relation=relation, engine=engine)
+
+    @keyword
+    def text_should_exist(self, text: str, engine: str = "auto") -> None:
+        # Kein Error-Screenshot: läuft als Poll-Primitiv (Wait Until Keyword Succeeds). Siehe BP-NEG-SCREENSHOT.
+        if not _manager.text_exists(text, engine=engine):
+            raise AssertionError(f"Text not found: '{text}'")
+
+    @keyword
+    def take_screenshot(self, name: str = "screenshot") -> str:
+        return _manager.take_screenshot(name)
+
+    @keyword
+    def move_mouse(self, x: int, y: int) -> None:
+        _manager.move_mouse(x, y)
+
+    @keyword
+    def find_element(self, target: str, anchor: str, relation: str = "near",
+                     kind: str = "auto", engine: str = "auto") -> tuple[int, int]:
+        """Lokalisiert ein Ziel live relativ zu einem Anker-Text und gibt (x, y) zurück.
+        target: Text oder .png (Custom Element) · relation: near|left_of|right_of|above|below · kind: auto|text|icon."""
+        return _manager.find_element(target, anchor, relation=relation, kind=kind, engine=engine)
+
+    @keyword
+    def tap_element(self, target: str, anchor: str, relation: str = "near",
+                    kind: str = "auto", engine: str = "auto") -> None:
+        """Tippt ein Ziel, das live relativ zu einem Anker-Text lokalisiert wird (siehe Find Element)."""
+        _manager.tap_element(target, anchor, relation=relation, kind=kind, engine=engine)

automation/utils/adb.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+import logging
+import os
+import subprocess
+import warnings
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy as np
+
+from automation import config
+from automation.utils.device_interface import DeviceInterface
+
+logger = logging.getLogger(__name__)
+
+_device_id: str | None = None
+# Session-konstante Werte memoisieren: App-Version und Geräte-Fingerprint ändern sich
+# innerhalb eines Laufs nicht, die Activity dagegen pro Aktion.
+_app_version_cache: dict[str, str] = {}
+_device_fp_cache: str | None = None
+
+def _run(cmd: list[str], timeout: int | None = None) -> subprocess.CompletedProcess:
+    prefix = ["-s", _device_id] if _device_id else []
+    return subprocess.run(
+        ["adb"] + prefix + cmd,
+        capture_output=True,
+        timeout=timeout if timeout is not None else config.ADB_TIMEOUT,
+    )
+
+def _list_devices() -> list[str]:
+    result = subprocess.run(
+        ["adb", "devices"],
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.splitlines()
+
+def connect(device_id: str | None = None) -> None:
+    global _device_id
+
+    if device_id:
+        # TCP/IP Device (z. B. 192.168.0.10:5555)
+        if ":" in device_id:
+            result = subprocess.run(
+                ["adb", "connect", device_id],
+                capture_output=True,
+                text=True,
+            )
+            if "connected" not in result.stdout:
+                raise RuntimeError(f"ADB connect failed: {result.stdout.strip()}")
+        else:
+            # USB Device prüfen
+            device_lines = [ln for ln in _list_devices() if ln.startswith(device_id + "\t")]
+            if not device_lines or not any("\tdevice" in ln for ln in device_lines):
+                status = device_lines[0].split("\t")[1] if device_lines else "not found"
+                raise RuntimeError(f"Device '{device_id}' not ready: {status}")
+
+        _device_id = device_id
+        return
+
+    lines = [
+        line for line in _list_devices()
+        if "device" in line and "List" not in line
+    ]
+
+    if not lines:
+        raise RuntimeError(f"Device not found: {device_id or '(any)'}")
+    
+    if len(lines) > 1:
+        raise RuntimeError(
+            "Multiple ADB devices detected. Please set ANDROID_DEVICE_ID explicitly."
+        )
+    
+    # Genau ein Device -> automatisch verwenden
+    detected_device = lines[0].split()[0]
+    _device_id = detected_device
+
+    warnings.warn(f"No device_id provided. Using detected device: {detected_device}")
+    logger.info("connect event=auto_detect device_id=%r", detected_device)
+
+def screenshot() -> np.ndarray:
+    import cv2
+    import numpy as np
+    result = _run(["exec-out", "screencap", "-p"], timeout=config.ADB_SCREENSHOT_TIMEOUT)
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"Screenshot failed (returncode={result.returncode}): {result.stderr.decode().strip()}"
+        )
+    arr = np.frombuffer(result.stdout, np.uint8)
+    img = cv2.imdecode(arr, cv2.IMREAD_COLOR)
+    if img is None:
+        raise RuntimeError("Screenshot failed, image decode returned None")
+    return img
+
+def tap(x: int, y: int) -> None:
+    result = _run(["shell", "input", "tap", str(x), str(y)])
+    if result.returncode != 0:
+        raise RuntimeError(f"tap({x}, {y}) failed: {result.stderr.decode().strip()}")
+
+def swipe(x1: int, y1: int, x2: int, y2: int, duration_ms: int | None = None) -> None:
+    if duration_ms is None:
+        duration_ms = config.ADB_SWIPE_DURATION_MS
+    result = _run(["shell", "input", "swipe", str(x1), str(y1), str(x2), str(y2), str(duration_ms)])
+    if result.returncode != 0:
+        raise RuntimeError(f"swipe failed: {result.stderr.decode().strip()}")
+
+def type_text(text: str) -> None:
+    # 'adb shell input text' ersetzt Leerzeichen durch %s. Nur Leerzeichen werden behandelt;
+    # Sonderzeichen-Escaping ist für den PoC bewusst nicht abgedeckt (Showcase-Strings sind kontrolliert).
+    escaped = text.replace(" ", "%s")
+    result = _run(["shell", "input", "text", escaped])
+    if result.returncode != 0:
+        raise RuntimeError(f"type_text failed: {result.stderr.decode().strip()}")
+
+def _activity_token(segment: str) -> str | None:
+    """Erstes Token in segment im Format 'com.pkg/.Activity', None wenn keins vorhanden."""
+    for tok in segment.split():
+        if "/" in tok and "." in tok:
+            return tok.strip("{}")
+    return None
+
+def current_activity() -> str:
+    """Aktuell sichtbare Activity als 'package/activity' (z. B. 'com.android.settings/.Settings'),
+    Leerstring wenn keine gefunden. Quelle: 'dumpsys activity activities', ohne uiautomator2."""
+    result = _run(["shell", "dumpsys", "activity", "activities"])
+    text = result.stdout.decode(errors="ignore")
+    # Feldname variiert je Android-Version.
+    for marker in ("topResumedActivity=", "mResumedActivity=", "ResumedActivity:"):
+        idx = text.find(marker)
+        if idx == -1:
+            continue
+        # Format: ...ActivityRecord{<hash> u0 com.pkg/.Activity tNNN}
+        token = _activity_token(text[idx:idx + 300])
+        if token is not None:
+            return token
+    return ""
+
+def app_version(package: str) -> str:
+    """versionName der installierten App. Session-konstant -> memoisiert pro Package."""
+    if package in _app_version_cache:
+        logger.debug("ADB_CACHE event=hit keyword=app_version package=%r", package)
+        return _app_version_cache[package]
+    result = _run(["shell", "dumpsys", "package", package])
+    version = ""
+    for line in result.stdout.decode(errors="ignore").splitlines():
+        line = line.strip()
+        if line.startswith("versionName="):
+            version = line.split("=", 1)[1].strip()
+            break
+    _app_version_cache[package] = version
+    logger.info("ADB_CACHE event=miss keyword=app_version package=%r version=%r", package, version)
+    return version
+
+def _first_value_after(output: str, marker: str) -> str | None:
+    """Wert der ersten Zeile, die marker enthält (Format 'marker: wert'), None wenn nicht gefunden."""
+    for line in output.splitlines():
+        if marker in line:
+            return line.split(":", 1)[1].strip()
+    return None
+
+def device_fingerprint() -> str:
+    """Geräte-Identität 'id_BxH_density_orientation' für den Screen-Key (damit der Cache nicht
+    über Geräte/Auflösungen hinweg falsch trifft). Session-konstant -> memoisiert."""
+    global _device_fp_cache
+    if _device_fp_cache is not None:
+        logger.debug("ADB_CACHE event=hit keyword=device_fingerprint")
+        return _device_fp_cache
+    size_out = _run(["shell", "wm", "size"]).stdout.decode(errors="ignore")
+    dens_out = _run(["shell", "wm", "density"]).stdout.decode(errors="ignore")
+    size_val = _first_value_after(size_out, "Physical size:")
+    w, h = (int(p) for p in size_val.split("x")[:2]) if size_val and "x" in size_val else (0, 0)
+    dens = _first_value_after(dens_out, "Physical density:") or ""
+    orientation = "portrait" if h >= w else "landscape"
+    _device_fp_cache = f"{_device_id or ''}_{w}x{h}_{dens}_{orientation}"
+    logger.info("ADB_CACHE event=miss keyword=device_fingerprint fingerprint=%r", _device_fp_cache)
+    return _device_fp_cache
+
+def install_app(apk_path: str = "") -> None:
+    if not apk_path:
+        apk_path = config.APK_PATH
+    if not os.path.exists(apk_path):
+        raise FileNotFoundError(f"APK not found: {apk_path}")
+
+    prefix = ["-s", _device_id] if _device_id else []
+    result = subprocess.run(
+        ["adb"] + prefix + ["install", "-r", apk_path],
+        capture_output=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"Installation failed: {result.stderr.decode().strip()}")
+
+
+class AdbDevice(DeviceInterface):
+    """DeviceInterface-Implementierung für Android über ADB."""
+
+    def screenshot(self) -> np.ndarray:
+        return screenshot()
+
+    def tap(self, x: int, y: int) -> None:
+        tap(x, y)
+
+    def type_text(self, text: str) -> None:
+        type_text(text)
+
+    def scroll(self, x: int, y: int, amount: int, duration_ms: int | None = None) -> None:
+        swipe(x, y + amount // 2, x, y - amount // 2, duration_ms)
+
+    def connect(self, target: str | None = None) -> None:
+        connect(target)
+
+    def screen_key(self) -> tuple[str, str, str, str] | None:
+        try:
+            activity = current_activity()
+            if not activity or "/" not in activity:
+                return None
+            package = activity.split("/", 1)[0]
+            return package, activity, app_version(package), device_fingerprint()
+        except Exception:
+            return None