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

automation/utils/windows_host.py

@@ -0,0 +1,354 @@
+from __future__ import annotations
+
+import logging
+import subprocess
+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__)
+
+
+class WindowsHost(DeviceInterface):
+    """DeviceInterface-Implementierung für Windows Desktop über pywinauto und PIL."""
+
+    def __init__(self) -> None:
+        self._process_name: str | None = None
+        self._pid: int | None = None
+        self._app = None  # pywinauto.Application
+
+    def connect(self, target: str | None = None, process_name: str | None = None) -> None:
+        """Verbindet mit einem laufenden Windows-Prozess per PID, Prozessname oder Fenstertitel.
+        Einziger Ort, der das pywinauto.Application-Handle erzeugt."""
+        from pywinauto import Application  # lazy: nur auf Windows installierbar
+
+        if target is None:
+            raise ValueError("WindowsHost.connect erwartet Prozessname, PID oder Fenstertitel.")
+
+        # DPI-Awareness setzen, damit Screenshot-Koordinaten und Tap-Koordinaten übereinstimmen.
+        # Bei Display-Scaling (z. B. 150%) weichen PIL-Pixel und pywinauto-Coords sonst ab.
+        # Muss auf Hyper-V Windows 11 verifiziert werden.
+        try:
+            import ctypes
+            ctypes.windll.shcore.SetProcessDpiAwareness(2)
+        except Exception:
+            try:
+                import ctypes
+                ctypes.windll.user32.SetProcessDPIAware()
+            except Exception:
+                pass
+
+        # PID direkt angegeben
+        try:
+            pid = int(target)
+            try:
+                self._app = Application(backend="uia").connect(process=pid)
+            except Exception as e:
+                raise RuntimeError(f"Prozess mit PID '{pid}' nicht erreichbar: {e}") from e
+            self._pid = pid
+            self._process_name = process_name or target
+            return
+        except ValueError:
+            pass
+
+        # Prozessname (*.exe) → PID via tasklist (Windows Built-in)
+        if target.lower().endswith(".exe"):
+            result = subprocess.run(
+                ["tasklist", "/fi", f"IMAGENAME eq {target}", "/fo", "csv", "/nh"],
+                capture_output=True,
+                encoding="oem",
+                errors="replace",
+            )
+            matches = [ln for ln in result.stdout.strip().splitlines() if target.lower() in ln.lower()]
+            if not matches:
+                raise RuntimeError(f"Prozess '{target}' nicht gefunden.")
+            # CSV-Spalten: "Name","PID","Session","SessionNr","Speicher"
+            pid = int(matches[0].split('","')[1])
+            try:
+                self._app = Application(backend="uia").connect(process=pid)
+            except Exception as e:
+                raise RuntimeError(f"Prozess '{target}' (PID {pid}) nicht erreichbar: {e}") from e
+            self._pid = pid
+            self._process_name = process_name or target
+            return
+
+        # Fenstertitel → best_match
+        try:
+            self._app = Application(backend="uia").connect(best_match=target)
+        except Exception as e:
+            raise RuntimeError(f"Fenster mit Titel-Match '{target}' nicht gefunden: {e}") from e
+        self._process_name = process_name or target
+        try:
+            self._pid = self._app.top_window().process_id()
+        except Exception:
+            self._pid = None
+
+    def close(self) -> None:
+        """Beendet die verbundene App PID-scoped statt per Exe-Name, damit andere laufende
+        Instanzen desselben Exe-Namens unangetastet bleiben."""
+        if self._pid is None:
+            raise RuntimeError("WindowsHost.close: keine verbundene App (keine PID bekannt).")
+        subprocess.run(["taskkill", "/f", "/pid", str(self._pid)], capture_output=True)
+        self._app = None
+        self._pid = None
+        self._process_name = None
+
+    @property
+    def app(self):
+        """Das verbundene pywinauto.Application-Handle, None wenn (noch) nicht verbunden.
+        Einzige Stelle, über die WindowsUiaEngine auf die Verbindung zugreift."""
+        return self._app
+
+    def window(self):
+        """Kanonische Fensterauswahl für UIA und Vision: das flächengrößte sichtbare
+        Top-Level-Fenster der verbundenen App, robuster als das Z-Order-basierte top_window()."""
+        windows = self._app.windows(visible_only=True)
+        if not windows:
+            return self._app.top_window()
+
+        return max(windows, key=lambda w: _rect_area(w.rectangle()))
+
+    def _window_rect(self) -> tuple[int, int, int, int]:
+        """Fensterrechteck des per window() gewählten App-Fensters in Desktop-Koordinaten.
+        Loggt nur eine Warnung, wenn das Fenster außerhalb des Primärmonitors liegt."""
+        rect = self.window().rectangle()
+        left, top, right, bottom = rect.left, rect.top, rect.right, rect.bottom
+
+        import ctypes
+        user32 = ctypes.windll.user32
+        primary_w = user32.GetSystemMetrics(0)
+        primary_h = user32.GetSystemMetrics(1)
+        if left < 0 or top < 0 or right > primary_w or bottom > primary_h:
+            logger.warning(
+                "WindowsHost: App-Fenster (%s, %s, %s, %s) liegt außerhalb des Primärmonitors "
+                "(%sx%s). Screenshot/Koordinaten-Mapping sind nur für den Primärmonitor verifiziert.",
+                left, top, right, bottom, primary_w, primary_h,
+            )
+        return left, top, right, bottom
+
+    def _to_desktop(self, x: int, y: int) -> tuple[int, int]:
+        """Rechnet Fenster-relative Koordinaten auf absolute Desktop-Koordinaten zurück, ohne
+        Verbindung unverändert (Vollbild-Fallback). Live-Lookup pro Aufruf, kein Caching."""
+        if self._app is None:
+            return x, y
+        try:
+            left, top, _, _ = self._window_rect()
+        except Exception as e:
+            raise RuntimeError(f"Fensterrechteck für Koordinaten-Mapping nicht ermittelbar: {e}") from e
+        return x + left, y + top
+
+    def screenshot(self) -> np.ndarray:
+        """Screenshot via PIL.ImageGrab, gecroppt auf das verbundene App-Fenster. Ohne Verbindung
+        oder bei nicht ermittelbarem Fensterrechteck: Vollbild-Fallback."""
+        import cv2
+        import numpy as np
+        from PIL import ImageGrab  # lazy: kein Display auf Linux-Devcontainer
+
+        bbox = None
+        if self._app is not None:
+            try:
+                bbox = self._window_rect()
+            except Exception:
+                bbox = None
+
+        img = ImageGrab.grab(bbox=bbox, all_screens=True)
+        arr = np.array(img)
+        return cv2.cvtColor(arr, cv2.COLOR_RGB2BGR)
+
+    def tap(self, x: int, y: int) -> None:
+        """Linksklick an Fenster-relativen Koordinaten (Ursprung des Screenshots), intern über
+        _to_desktop() auf absolute Bildschirmkoordinaten zurückgerechnet."""
+        from pywinauto import mouse  # lazy: Windows-only
+
+        dx, dy = self._to_desktop(x, y)
+        mouse.click(button="left", coords=(dx, dy))
+
+    def move_mouse(self, x: int, y: int) -> None:
+        """Bewegt den Mauszeiger an Fenster-relative Koordinaten (Ursprung des Screenshots),
+        intern über _to_desktop() zurückgerechnet, ohne zu klicken."""
+        from pywinauto import mouse  # lazy: Windows-only
+
+        dx, dy = self._to_desktop(x, y)
+        mouse.move(coords=(dx, dy))
+
+    def type_text(self, text: str) -> None:
+        """Tippt literalen Text in das fokussierte Element via pywinauto. Sonderzeichen der
+        send_keys-Syntax werden vor dem Senden escaped, damit sie als Literaltext ankommen."""
+        from pywinauto.keyboard import send_keys  # lazy: Windows-only
+
+        send_keys(_escape_send_keys(text), with_spaces=True)
+
+    def focused_process_id(self) -> int | None:
+        """PID des Fensters mit aktuellem Eingabefokus, None ohne Vordergrundfenster.
+        restype/argtypes explizit gesetzt, sonst schneidet ctypes das HWND auf 64-Bit ab."""
+        import ctypes
+
+        user32 = ctypes.windll.user32
+        user32.GetForegroundWindow.restype = ctypes.c_void_p
+        user32.GetWindowThreadProcessId.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_ulong)]
+
+        hwnd = user32.GetForegroundWindow()
+        if not hwnd:
+            return None
+        pid = ctypes.c_ulong()
+        user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
+        return pid.value or None
+
+    def verify_focus_in_target(self) -> bool:
+        """Prüft, ob der Eingabefokus im verbundenen Zielprozess liegt. Ohne Verbindung oder
+        bei technisch nicht ermittelbarem Foreground-Window bleibt die Rückgabe tolerant (True)."""
+        if self._app is None or self._pid is None:
+            return True
+        foreground_pid = self.focused_process_id()
+        if foreground_pid is None:
+            return True
+        return foreground_pid == self._pid
+
+    def active_region(self) -> tuple[int, int, int, int] | None:
+        """Ausdehnung des aktuell obersten (Z-Order) App-Fensters in Screenshot-relativen
+        Koordinaten, None wenn kein Overlay über dem Hauptfenster liegt oder nicht verbunden."""
+        if self._app is None:
+            return None
+        try:
+            main = self.window()
+            top = self._app.top_window()
+        except Exception:
+            return None
+        if top.handle == main.handle:
+            return None
+        main_rect = main.rectangle()
+        top_rect = top.rectangle()
+        return (
+            top_rect.left - main_rect.left,
+            top_rect.top - main_rect.top,
+            top_rect.right - main_rect.left,
+            top_rect.bottom - main_rect.top,
+        )
+
+    def value_region(self, text: str) -> tuple[int, int, int, int] | None:
+        """Ausdehnung des einen Edit-Elements im Hauptfenster, dessen aktueller Wert exakt
+        text entspricht, in window()-relativen Koordinaten. None bei 0/>1 Kandidaten."""
+        if self._app is None:
+            return None
+        try:
+            main = self.window()
+            edits = main.descendants(control_type="Edit", cache_enable=True)
+            matches = []
+            for el in edits:
+                try:
+                    value = el.get_value()
+                except Exception:
+                    value = el.window_text()
+                if value.strip() == text.strip():
+                    matches.append(el)
+        except Exception:
+            return None
+        if len(matches) != 1:
+            return None
+        main_rect = main.rectangle()
+        rect = matches[0].rectangle()
+        return (
+            rect.left - main_rect.left,
+            rect.top - main_rect.top,
+            rect.right - main_rect.left,
+            rect.bottom - main_rect.top,
+        )
+
+    def clear_focused_field(self, x: int, y: int) -> None:
+        """Leert das Feld an (x, y) und prüft anschließend, ob es wirklich leer ist."""
+        from pywinauto.keyboard import send_keys  # lazy: Windows-only
+        import time
+
+        send_keys("{HOME}+{END}{DELETE}", with_spaces=True)
+        time.sleep(config.WINDOWS_CLEAR_FIELD_DELAY)
+
+        dx, dy = self._to_desktop(x, y)
+        main = self.window()
+        candidates = [
+            el for el in main.descendants(control_type="Edit", cache_enable=True)
+            if _rect_contains(el.rectangle(), dx, dy)
+        ]
+        if not candidates:
+            raise RuntimeError(f"Kein Edit-Element an Position ({x}, {y}) für Lösch-Verifikation.")
+        el = min(candidates, key=lambda c: _rect_area(c.rectangle()))
+        try:
+            value = el.get_value()
+        except Exception:
+            value = el.window_text()
+        if value.strip():
+            raise RuntimeError(f"Feld an ({x}, {y}) nach Löschversuch nicht leer: '{value}'.")
+
+    def scroll(self, x: int, y: int, amount: int, duration_ms: int | None = None) -> None:
+        """Mausrad-Scroll an Fenster-relativen Koordinaten (x, y). Skaliert über eine Schleife
+        aus Einzel-Notches, nicht über einen großen wheel_dist-Wert."""
+        from pywinauto import mouse  # lazy: Windows-only
+        import time
+
+        dx, dy = self._to_desktop(x, y)
+        direction = -1 if amount > 0 else 1
+        for _ in range(config.WINDOWS_SCROLL_NOTCHES):
+            mouse.scroll(coords=(dx, dy), wheel_dist=direction)
+            time.sleep(config.WINDOWS_SCROLL_EVENT_DELAY)
+
+    def screen_key(self) -> tuple[str, str, str, str] | None:
+        """Stabile Screen-Identität: Prozessname, Fenstertitel, Exe-Version, Auflösung.
+        None bei Fehler → Cache wird übersprungen."""
+        try:
+            if self._app is None or self._process_name is None:
+                return None
+
+            title = self._app.top_window().window_text()
+            version = _exe_version(self._pid)
+
+            import ctypes
+            user32 = ctypes.windll.user32
+            w = user32.GetSystemMetrics(0)
+            h = user32.GetSystemMetrics(1)
+            resolution = f"{w}x{h}"
+
+            return self._process_name, title, version, resolution
+        except Exception:
+            return None
+
+
+def _rect_contains(rect, x: int, y: int) -> bool:
+    """Prüft, ob (x, y) innerhalb von rect liegt."""
+    return rect.left <= x <= rect.right and rect.top <= y <= rect.bottom
+
+
+def _rect_area(rect) -> int:
+    """Fläche von rect."""
+    return max(0, rect.right - rect.left) * max(0, rect.bottom - rect.top)
+
+
+_SEND_KEYS_SPECIAL_CHARS = "+^%~(){}"
+
+
+def _escape_send_keys(text: str) -> str:
+    """Escaped die Sonderzeichen der pywinauto-send_keys-Syntax als Literal. Zeichenweise über
+    den Original-Text, nicht per verketteten str.replace(), sonst doppeltes Escaping."""
+    return "".join(f"{{{ch}}}" if ch in _SEND_KEYS_SPECIAL_CHARS else ch for ch in text)
+
+
+def _exe_version(pid: int | None) -> str:
+    """Exe-Versionsnummer eines Prozesses via PowerShell. Leerstring bei Fehler."""
+    if pid is None:
+        return ""
+    try:
+        script = (
+            f"$p = Get-Process -Id {pid} -ErrorAction SilentlyContinue; "
+            f"if ($p) {{ $p.MainModule.FileVersionInfo.FileVersion }} else {{ '' }}"
+        )
+        result = subprocess.run(
+            ["powershell", "-NoProfile", "-Command", script],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return result.stdout.strip()
+    except Exception:
+        return ""