pytest-uia 0.7.1__py3-none-any.whl

pytest_uia/__init__.py

@@ -0,0 +1,48 @@
+"""pytest-uia: Windows GUI acceptance testing through the accessibility tree.
+
+The names re-exported here are the whole public surface. Everything they are
+built from — locators, adapters, retry policies — is an implementation detail
+that a test should never have to name. Importing this module pulls in no
+Windows-only dependency: the UIA adapter is loaded when a session is first
+wired to a real desktop, not before.
+"""
+
+from pytest_uia.application.driver import App, Dialog, UIElement
+from pytest_uia.application.session import GuiSession
+from pytest_uia.domain.dump import Dump
+from pytest_uia.domain.errors import (
+    DialogNotFound,
+    DialogStillOpen,
+    ElementNotFound,
+    InputRefused,
+    LaunchFailed,
+    ProcessStillRunning,
+    TextNeverSettled,
+    WindowNotFound,
+)
+from pytest_uia.domain.query import Query, Role
+from pytest_uia.domain.tree import DumpLimits, TreeNode, WalkEnded
+
+__version__ = "0.7.1"
+
+__all__ = [
+    "App",
+    "Dialog",
+    "DialogNotFound",
+    "DialogStillOpen",
+    "Dump",
+    "DumpLimits",
+    "ElementNotFound",
+    "GuiSession",
+    "InputRefused",
+    "LaunchFailed",
+    "ProcessStillRunning",
+    "Query",
+    "Role",
+    "TextNeverSettled",
+    "TreeNode",
+    "UIElement",
+    "WalkEnded",
+    "WindowNotFound",
+    "__version__",
+]

pytest_uia/__main__.py

@@ -0,0 +1,171 @@
+"""`python -m pytest_uia --title "..."`: dump a window that is already on screen.
+
+Where it plugs in: a thin shell over the same `attach` and `dump` a test makes.
+It exists because the person this feature is for has an application in front of
+them and no test yet, and "first write a test" is the wall the dump was built
+to remove.
+
+Imports pytest nowhere, and reaches Windows only through the composition root
+at the bottom, so parsing and running are both specified with no desktop.
+
+No console-script entry point on purpose: `python -m` always runs in the
+virtual environment the user is already in, and a `pytest-uia` script would be
+one more thing that can be on the wrong PATH.
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Protocol
+
+from pytest_uia.application.session import session_on_this_desktop
+from pytest_uia.domain.dump import Dump
+from pytest_uia.domain.errors import WindowNotFound
+from pytest_uia.domain.tree import DEFAULT_LIMITS, DumpLimits
+
+_A_TEST_WOULD_WAIT_THIS_LONG = 10.0
+_FINE = 0
+_NO_SUCH_WINDOW = 1
+
+
+@dataclass(frozen=True)
+class Request:
+    """What one run of the command line was asked for."""
+
+    title: str
+    limits: DumpLimits = DEFAULT_LIMITS
+    attach_timeout: float = _A_TEST_WOULD_WAIT_THIS_LONG
+    everything: bool = False
+
+    def rendering_of(self, dump: Dump) -> str:
+        """Which of the dump's two renderings this run asked for.
+
+        Asked of the request rather than passed as a flag to a function: the
+        choice is data about what was typed, and the caller that renders should
+        not have to know there are two.
+        """
+        if self.everything:
+            return dump.with_window_chrome()
+        return str(dump)
+
+
+class Screen(Protocol):
+    """As much of the desktop as a command line needs.
+
+    A port rather than a direct call so that both halves of the run — the
+    window that was found and the window that was not — are specified with no
+    desktop at all.
+    """
+
+    def attach(self, title: str, timeout: float) -> Dumpable: ...
+
+    def captions(self) -> tuple[str, ...]: ...
+
+
+class Dumpable(Protocol):
+    """The one thing the command line does with what it attached to."""
+
+    def dump(self, *, limits: DumpLimits) -> Dump: ...
+
+
+def run(request: Request, screen: Screen) -> int:
+    """Dump the window that was asked for, or say what is on screen instead."""
+    try:
+        app = screen.attach(request.title, request.attach_timeout)
+    except WindowNotFound:
+        print(_nothing_is_called_that(request.title, screen.captions()))
+        return _NO_SUCH_WINDOW
+    # The one place the dump prints itself: there is no failing test to attach
+    # it to here, and no captured output for it to disappear into.
+    print(request.rendering_of(app.dump(limits=request.limits)))
+    return _FINE
+
+
+def _nothing_is_called_that(title: str, on_screen: Sequence[str]) -> str:
+    # The captions are listed because titles are matched exactly, so the
+    # overwhelmingly likely cause of a miss is one that is nearly right — and
+    # "no such window" on its own leaves the reader nothing to correct.
+    return "\n".join(
+        [
+            f"no visible top-level window titled {title!r}. On screen right now:",
+            *(f"  {caption!r}" for caption in on_screen),
+        ]
+    )
+
+
+def parsed(argv: Sequence[str] | None = None) -> Request:
+    """Read the command line, or exit the way argparse exits on a bad one."""
+    read = _the_arguments().parse_args(argv)
+    return Request(
+        title=read.title,
+        limits=DumpLimits(max_nodes=read.max_nodes, budget=read.budget),
+        attach_timeout=read.attach_timeout,
+        everything=read.all,
+    )
+
+
+class ThisDesktop:
+    """Composition root: the real session, and the real list of windows.
+
+    The UIA adapter is reached only through `session_on_this_desktop`, which
+    defers its import, and through the one inside `captions` — so importing
+    this module, and `--help` with it, needs no Windows at all.
+
+    `attach` is deliberately the same call a test makes, and a session that did
+    not start a process never ends one: this command dumps applications people
+    are using.
+    """
+
+    def attach(self, title: str, timeout: float) -> Dumpable:
+        return session_on_this_desktop().attach(title=title, timeout=timeout)
+
+    def captions(self) -> tuple[str, ...]:
+        from pytest_uia.adapters.uia import the_desktop, visible_top_level_titles
+
+        return visible_top_level_titles(the_desktop())
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    return run(parsed(argv), ThisDesktop())
+
+
+def _the_arguments() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m pytest_uia",
+        description="Print the accessibility tree of a window already on screen.",
+    )
+    parser.add_argument(
+        "--title",
+        required=True,
+        help="the exact caption of the window to dump, as `gui.attach` matches it",
+    )
+    parser.add_argument(
+        "--all",
+        action="store_true",
+        help="list the window chrome the dump otherwise folds into one line",
+    )
+    parser.add_argument(
+        "--max-nodes",
+        type=int,
+        default=DEFAULT_LIMITS.max_nodes,
+        help="how many controls to read before stopping and saying there are more",
+    )
+    parser.add_argument(
+        "--budget",
+        type=float,
+        default=DEFAULT_LIMITS.budget,
+        help="how long to spend walking before stopping and saying so",
+    )
+    parser.add_argument(
+        "--attach-timeout",
+        type=float,
+        default=_A_TEST_WOULD_WAIT_THIS_LONG,
+        help="how long to wait for the window to appear",
+    )
+    return parser
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pytest_uia/adapters/capture.py

@@ -0,0 +1,65 @@
+"""Adapter over `mss`: a rectangle of the screen, as raw pixels.
+
+Where it plugs in: :mod:`pytest_uia.adapters.ocr` grabs the region a window
+occupies and hands the pixels to Windows' OCR engine. The format is chosen for
+that consumer — BGRA is what a `SoftwareBitmap` takes and what `mss` already
+produces, so no image library sits between the screen and the recogniser.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+import mss
+
+
+@dataclass(frozen=True)
+class ScreenRegion:
+    """A rectangle of the desktop, in physical pixels.
+
+    Physical, not logical: importing `uiautomation` makes this process
+    per-monitor DPI aware, so UIA's rectangles, `mss`'s grabs and the
+    coordinates a click is aimed at are all in the same units already.
+    """
+
+    left: int
+    top: int
+    width: int
+    height: int
+
+
+@dataclass(frozen=True)
+class CapturedImage:
+    """Pixels read off the screen, four bytes per pixel, blue-green-red-alpha."""
+
+    width: int
+    height: int
+    bgra: bytes
+
+
+class ScreenCapture(Protocol):
+    """Where pixels come from: the seam between OCR and the actual desktop."""
+
+    def grab(self, region: ScreenRegion) -> CapturedImage: ...
+
+
+class MssScreenCapture:
+    """Adapter presenting `mss` as the screen-capture port."""
+
+    def grab(self, region: ScreenRegion) -> CapturedImage:
+        # A fresh grabber per capture on purpose: an `mss` instance is bound to
+        # the thread and the device context it was created on, and one that
+        # outlives a display change hands back stale pixels.
+        with mss.MSS() as screen:
+            shot = screen.grab(
+                {
+                    "left": region.left,
+                    "top": region.top,
+                    "width": region.width,
+                    "height": region.height,
+                }
+            )
+        return CapturedImage(
+            width=shot.width, height=shot.height, bgra=bytes(shot.bgra)
+        )

pytest_uia/adapters/input.py

@@ -0,0 +1,177 @@
+"""Adapter over Win32 synthetic input: the mouse, and Windows' answer about it.
+
+Where it plugs in: every element with no accessibility pattern left to ask acts
+through this port instead — everything OCR finds, and any UIA control whose
+provider refuses Invoke.
+
+The motivating failure: `uiautomation.Click` throws Windows' answer away. While
+a window owned by a higher-integrity process holds the foreground, User
+Interface Privilege Isolation drops every event a medium-integrity process
+injects — `SetCursorPos` returns 0 and the cursor does not move — and a click
+that never happened is then indistinguishable from one the application ignored.
+The test fails seconds later blaming the application, which did nothing wrong.
+
+The refusal is real, routine, and almost always transient (a background service
+briefly taking the foreground is enough), which is why the driver retries an
+`InputRefused` inside the element's implicit wait rather than failing on the
+first one. Only when it lasts the whole wait does it reach the reader — by then
+naming the window responsible, because nothing else on the machine will.
+
+`ctypes.windll` is reached lazily on purpose: this module has to import on the
+platforms that never call it, so the domain-only unit specs above it run in CI
+on Linux.
+"""
+
+from __future__ import annotations
+
+import ctypes
+from typing import Protocol
+
+from pytest_uia.domain.errors import InputRefused
+
+_MOUSE_EVENT = 0
+_LEFT_BUTTON_DOWN = 0x0002
+_LEFT_BUTTON_UP = 0x0004
+_A_PRESS_AND_A_RELEASE = 2
+_LONGEST_WINDOW_CLASS_NAME = 256
+
+
+class PointerInput(Protocol):
+    """The mouse, as the only elements that need one are allowed to see it."""
+
+    def click(self, x: int, y: int) -> None: ...
+
+
+class SyntheticMouse(Protocol):
+    """Win32's mouse, kept behind a seam so refusal is testable without one."""
+
+    def click_at(self, x: int, y: int) -> bool: ...
+
+    def foreground_holder(self) -> str: ...
+
+
+class CheckedPointer:
+    """Adapter presenting a synthetic mouse as the pointer elements act through."""
+
+    def __init__(self, mouse: SyntheticMouse) -> None:
+        self._mouse = mouse
+
+    def click(self, x: int, y: int) -> None:
+        if not self._mouse.click_at(x, y):
+            raise InputRefused(self._why_windows_dropped_it())
+
+    def _why_windows_dropped_it(self) -> str:
+        # A bare reason, not a sentence: the caller that owns the deadline
+        # prefixes it with how long it kept trying before giving up.
+        return (
+            f"the foreground is held by {self._mouse.foreground_holder()}, which "
+            "runs at a higher integrity level than this process, so Windows "
+            "drops every event this process injects; close that window, stop "
+            "the service behind it, or run the suite elevated"
+        )
+
+
+class Win32Mouse:
+    """The user32 calls a click is made of, with the answers they hand back.
+
+    Humble object by design: it holds no decision worth a unit test, only the
+    ctypes plumbing that cannot exist without a desktop. What it is *for* — the
+    refusal — is specified against :class:`CheckedPointer` with doubles, and
+    proven end to end by the gui specs.
+    """
+
+    def click_at(self, x: int, y: int) -> bool:
+        if not self._cursor_moved_to(x, y):
+            # Checked on its own, and first: a refused move injects nothing, so
+            # there is no half-pressed button to undo before the next attempt.
+            return False
+        return self._left_button_pressed_and_released()
+
+    def foreground_holder(self) -> str:
+        window = _foreground_window()
+        if window is None:
+            # Windows answers NULL while no window on this desktop is active —
+            # mid-switch, or with a secure desktop (UAC, the lock screen) up.
+            return "a window this process cannot see (the workstation may be locked)"
+        return f"{_class_name_of(window)!r} (pid {_process_behind(window)})"
+
+    def _cursor_moved_to(self, x: int, y: int) -> bool:
+        return bool(_user32().SetCursorPos(int(x), int(y)))
+
+    def _left_button_pressed_and_released(self) -> bool:
+        events = (_InputEvent * _A_PRESS_AND_A_RELEASE)(
+            _button_event(_LEFT_BUTTON_DOWN),
+            _button_event(_LEFT_BUTTON_UP),
+        )
+        inserted = _user32().SendInput(
+            _A_PRESS_AND_A_RELEASE,
+            ctypes.byref(events),
+            ctypes.sizeof(_InputEvent),
+        )
+        # SendInput reports how many events reached the queue; UIPI blocks the
+        # whole batch, so anything short of both is a refusal.
+        return inserted == _A_PRESS_AND_A_RELEASE
+
+
+class _MouseEvent(ctypes.Structure):
+    """Win32's MOUSEINPUT."""
+
+    _fields_ = (
+        ("dx", ctypes.c_long),
+        ("dy", ctypes.c_long),
+        ("mouse_data", ctypes.c_ulong),
+        ("flags", ctypes.c_ulong),
+        ("time", ctypes.c_ulong),
+        # ULONG_PTR: pointer-sized, and the reason INPUT is 40 bytes on 64-bit.
+        ("extra_info", ctypes.c_size_t),
+    )
+
+
+class _InputEvent(ctypes.Structure):
+    """Win32's INPUT, in its only shape this module ever sends.
+
+    The real type holds a union of mouse, keyboard and hardware events, but
+    MOUSEINPUT is the largest member, so a struct naming it directly has the
+    same size and alignment as the union does.
+    """
+
+    _fields_ = (
+        ("type", ctypes.c_ulong),
+        ("mouse", _MouseEvent),
+    )
+
+
+def _button_event(flags: int) -> _InputEvent:
+    # No MOUSEEVENTF_MOVE and no coordinates: the button acts wherever the
+    # cursor already is, which SetCursorPos has just been told about.
+    return _InputEvent(_MOUSE_EVENT, _MouseEvent(0, 0, 0, flags, 0, 0))
+
+
+def _foreground_window() -> int | None:
+    user32 = _user32()
+    # Without this, ctypes truncates a 64-bit handle to a C int and every
+    # question asked about the window afterwards is about a different one.
+    user32.GetForegroundWindow.restype = ctypes.c_void_p
+    return user32.GetForegroundWindow() or None
+
+
+def _class_name_of(window: int) -> str:
+    name = ctypes.create_unicode_buffer(_LONGEST_WINDOW_CLASS_NAME)
+    _user32().GetClassNameW(ctypes.c_void_p(window), name, _LONGEST_WINDOW_CLASS_NAME)
+    return name.value
+
+
+def _process_behind(window: int) -> int:
+    pid = ctypes.c_ulong()
+    _user32().GetWindowThreadProcessId(ctypes.c_void_p(window), ctypes.byref(pid))
+    return pid.value
+
+
+def _user32() -> ctypes.WinDLL:
+    # Resolved per call rather than at import: `ctypes.windll` does not exist
+    # off Windows, and this module still has to import there.
+    return ctypes.windll.user32
+
+
+WINDOWS_POINTER: PointerInput = CheckedPointer(Win32Mouse())
+"""The pointer every adapter uses unless a spec hands it a double instead."""