nvda-addon-testkit 0.1.0__py3-none-any.whl

nvda_testkit/resolve.py

@@ -0,0 +1,126 @@
+"""Work out which NVDA launcher to download for a given channel.
+
+Stable and beta come from nvaccess's update-check endpoint, which returns
+`key: value` lines and always reports the newest build regardless of the
+version we claim to be running. Alpha has no such endpoint -- passing
+versionType=alpha returns a 404 -- so it is resolved by scraping the snapshot
+directory index.
+"""
+
+from __future__ import annotations
+
+import re
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from .errors import LauncherResolutionError
+
+CHANNELS: tuple[str, ...] = ("stable", "beta", "alpha")
+
+_UPDATE_CHECK_URL = (
+    "https://download.nvaccess.org/nvdaUpdateCheck"
+    "?autoCheck=false&versionType={channel}&version=2019.1"
+)
+_SNAPSHOT_INDEX_URL = "https://download.nvaccess.org/snapshots/alpha/"
+_RELEASE_URL = "https://download.nvaccess.org/releases/{version}/nvda_{version}.exe"
+
+_SNAPSHOT_RE = re.compile(r"nvda_snapshot_alpha-(\d+),([0-9a-f]+)\.exe")
+_PINNED_RE = re.compile(r"^\d{4}\.\d+(\.\d+)?(beta\d+|rc\d+)?$")
+
+_USER_AGENT = "nvda-addon-testkit"
+
+
+@dataclass(frozen=True)
+class LauncherInfo:
+    """Everything needed to fetch and verify one NVDA launcher.
+
+    `sha1` is None for alpha snapshots and pinned versions, which publish no
+    digest. Callers must treat None as "unverifiable", never as "verified".
+    """
+
+    channel: str
+    version: str
+    url: str
+    sha1: str | None
+    api_version: str | None
+    api_compat_to: str | None
+
+
+def fetch_url(url: str) -> bytes:
+    request = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+    with urllib.request.urlopen(request, timeout=60) as response:
+        return response.read()
+
+
+def _parse_update_check(body: str) -> dict[str, str]:
+    fields: dict[str, str] = {}
+    for line in body.splitlines():
+        key, separator, value = line.partition(":")
+        if separator:
+            fields[key.strip()] = value.strip()
+    return fields
+
+
+def _resolve_released(channel: str, fetch: Callable[[str], bytes]) -> LauncherInfo:
+    url = _UPDATE_CHECK_URL.format(channel=channel)
+    fields = _parse_update_check(fetch(url).decode("utf-8", errors="replace"))
+    launcher_url = fields.get("launcherUrl")
+    if not launcher_url:
+        raise LauncherResolutionError(
+            f"The update-check endpoint returned no launcherUrl for channel {channel!r}. "
+            f"Got fields: {sorted(fields)}"
+        )
+    return LauncherInfo(
+        channel=channel,
+        version=fields.get("version", "unknown"),
+        url=launcher_url,
+        sha1=fields.get("launcherHash"),
+        api_version=fields.get("apiVersion"),
+        api_compat_to=fields.get("apiCompatTo"),
+    )
+
+
+def _resolve_alpha(fetch: Callable[[str], bytes]) -> LauncherInfo:
+    html = fetch(_SNAPSHOT_INDEX_URL).decode("utf-8", errors="replace")
+    matches = _SNAPSHOT_RE.findall(html)
+    if not matches:
+        raise LauncherResolutionError(
+            f"Found no alpha snapshot filenames at {_SNAPSHOT_INDEX_URL}. "
+            "The directory layout may have changed."
+        )
+    revision, commit = max(matches, key=lambda pair: int(pair[0]))
+    filename = f"nvda_snapshot_alpha-{revision},{commit}.exe"
+    return LauncherInfo(
+        channel="alpha",
+        version=f"alpha-{revision},{commit}",
+        url=_SNAPSHOT_INDEX_URL + filename,
+        sha1=None,
+        api_version=None,
+        api_compat_to=None,
+    )
+
+
+def resolve_launcher(
+    channel: str = "stable",
+    *,
+    fetch: Callable[[str], bytes] = fetch_url,
+) -> LauncherInfo:
+    """Resolve a channel name, or a pinned version like "2026.1.1", to a launcher."""
+    if channel in ("stable", "beta"):
+        return _resolve_released(channel, fetch)
+    if channel == "alpha":
+        return _resolve_alpha(fetch)
+    if _PINNED_RE.match(channel):
+        return LauncherInfo(
+            channel="pinned",
+            version=channel,
+            url=_RELEASE_URL.format(version=channel),
+            sha1=None,
+            api_version=None,
+            api_compat_to=None,
+        )
+    raise LauncherResolutionError(
+        f"{channel!r} is not a known channel. Expected one of {CHANNELS} "
+        "or a pinned version such as '2026.1.1'."
+    )

nvda_testkit/rpcclient.py

@@ -0,0 +1,122 @@
+"""XML-RPC transport to the spy add-on.
+
+Standard library only, on both ends: NVDA's bundled Python has xmlrpc, so the
+spy add-on can be dependency-free. Every call carries the session token as its
+first argument, which is what stops a stale NVDA from a previous run quietly
+answering this run's questions.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+import xmlrpc.client
+from collections.abc import Callable
+from typing import Any
+
+from .errors import AuthError, RpcError, WaitTimeout
+from .process import Handshake
+
+_DEFAULT_INTERVAL = 0.05
+
+#: Ceiling on any single call. Must exceed the longest server-side operation
+#: (addons_install allows 120s). Finite matters more than the exact value: a
+#: wedged NVDA would otherwise block forever and hang CI with no diagnostic.
+_SOCKET_TIMEOUT = 300.0
+
+
+class _TimeoutTransport(xmlrpc.client.Transport):
+    def __init__(self, timeout: float) -> None:
+        super().__init__(use_builtin_types=True)
+        self._timeout = timeout
+
+    def make_connection(self, host):
+        connection = super().make_connection(host)
+        connection.timeout = self._timeout
+        return connection
+
+
+class RpcClient:
+    def __init__(
+        self,
+        port: int,
+        token: str,
+        *,
+        timeout_scale: float = 1.0,
+        socket_timeout: float = _SOCKET_TIMEOUT,
+    ) -> None:
+        self.port = port
+        self.token = token
+        self.timeout_scale = timeout_scale
+        self._proxy = xmlrpc.client.ServerProxy(
+            f"http://127.0.0.1:{port}",
+            allow_none=True,
+            use_builtin_types=True,
+            transport=_TimeoutTransport(socket_timeout * timeout_scale),
+        )
+        # ServerProxy reuses a single HTTP connection, which isn't safe for
+        # concurrent requests (e.g. wait_for polling while another thread emits).
+        self._lock = threading.Lock()
+
+    @classmethod
+    def from_handshake(
+        cls, handshake: Handshake, *, token: str, timeout_scale: float = 1.0
+    ) -> RpcClient:
+        return cls(handshake.port, token, timeout_scale=timeout_scale)
+
+    def call(self, method: str, *args: Any) -> Any:
+        try:
+            with self._lock:
+                return getattr(self._proxy, method)(self.token, *args)
+        except xmlrpc.client.Fault as fault:
+            message = fault.faultString
+            if "AUTH:" in message:
+                raise AuthError(
+                    f"The spy rejected our token calling {method!r}. "
+                    "A stale NVDA from a previous run is the usual cause. "
+                    f"Remote said: {message}"
+                ) from fault
+            raise RpcError(f"{method}() failed inside NVDA: {message}") from fault
+        except xmlrpc.client.ProtocolError as error:
+            # Not an OSError, so it would otherwise escape untranslated.
+            raise RpcError(
+                f"The spy answered {method!r} with HTTP {error.errcode} "
+                f"{error.errmsg} at {error.url}."
+            ) from error
+        except OSError as error:
+            raise RpcError(
+                f"Could not reach the spy on 127.0.0.1:{self.port} calling {method!r}. "
+                "NVDA has probably died. "
+                f"Transport error: {error}"
+            ) from error
+
+    def poll_until(
+        self,
+        fn: Callable[[], Any],
+        *,
+        timeout: float,
+        description: str,
+        interval: float = _DEFAULT_INTERVAL,
+        last_seen: Callable[[], Any] | None = None,
+    ) -> Any:
+        """Poll `fn` until it returns something truthy, or the deadline passes."""
+        scaled = timeout * self.timeout_scale
+        deadline = time.monotonic() + scaled
+        while True:
+            result = fn()
+            if result:
+                return result
+            if time.monotonic() >= deadline:
+                observed = None
+                if last_seen is not None:
+                    try:
+                        observed = last_seen()
+                    except RpcError:
+                        observed = "(unavailable: NVDA unreachable)"
+                raise WaitTimeout(description, scaled, observed)
+            time.sleep(interval)
+
+    def close(self) -> None:
+        transport = getattr(self._proxy, "_ServerProxy__transport", None)
+        if transport is not None:
+            transport.close()

nvda_testkit/settings.py

@@ -0,0 +1,68 @@
+"""Configuration from [tool.nvda-testkit] in pyproject.toml, plus CLI overrides.
+
+tomllib is stdlib from 3.11, which is the floor -- no external TOML dependency.
+"""
+
+from __future__ import annotations
+
+import tomllib
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import cast
+
+_KEY_MAP = {
+    "nvda-channel": "channel",
+    "addon-bundle": "addon_bundle",
+    "modules": "modules",
+    "allow-eval": "allow_eval",
+    "timeout-scale": "timeout_scale",
+    "keep-portable": "keep_portable",
+    "out-dir": "out_dir",
+}
+
+
+@dataclass(frozen=True)
+class TestkitSettings:
+    channel: str = "stable"
+    addon_bundle: str | None = None
+    modules: tuple[str, ...] = ()
+    allow_eval: bool = False
+    timeout_scale: float = 1.0
+    keep_portable: bool = False
+    out_dir: Path = Path("testOutput")
+
+
+def _coerce(field: str, value):
+    if field == "modules":
+        return tuple(value)
+    if field == "out_dir":
+        return Path(value)
+    if field == "timeout_scale":
+        return float(value)
+    if field in ("allow_eval", "keep_portable"):
+        return bool(value)
+    return value
+
+
+def load_settings(
+    pyproject: Path | None = None,
+    overrides: dict | None = None,
+) -> TestkitSettings:
+    path = Path(pyproject) if pyproject is not None else Path("pyproject.toml")
+    values: dict = {}
+
+    if path.is_file():
+        with path.open("rb") as handle:
+            document = tomllib.load(handle)
+        section = document.get("tool", {}).get("nvda-testkit", {})
+        for key, value in section.items():
+            field = _KEY_MAP.get(key)
+            if field:
+                values[field] = _coerce(field, value)
+
+    # A None override means "not specified on the command line", not "clear it".
+    for field, value in (overrides or {}).items():
+        if value is not None:
+            values[field] = _coerce(field, value)
+
+    return cast(TestkitSettings, replace(TestkitSettings(), **values))

nvda_testkit/speechtypes.py

@@ -0,0 +1,74 @@
+"""Host-side representation of a captured speech sequence.
+
+Deliberately not NVDA's own SpeechSequence: these come off the wire as plain
+dicts, and the point is that a test can assert on them without importing
+anything from NVDA.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SpeechItem:
+    kind: str
+    text: str | None = None
+    command_type: str | None = None
+    fields: dict[str, Any] = field(default_factory=dict)
+    raw: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: dict) -> SpeechItem:
+        if payload.get("kind") == "text":
+            return cls(kind="text", text=payload.get("text", ""))
+        return cls(
+            kind="command",
+            command_type=payload.get("type"),
+            fields=dict(payload.get("fields") or {}),
+            raw=payload.get("repr"),
+        )
+
+    def __repr__(self) -> str:
+        if self.kind == "text":
+            return f"text({self.text!r})"
+        return f"{self.command_type}({self.fields})"
+
+
+@dataclass(frozen=True)
+class SpeechSequence:
+    items: tuple[SpeechItem, ...]
+    timestamp: float = 0.0
+    cancelled: bool = False
+
+    @property
+    def text(self) -> str:
+        # Space-join then collapse. NVDA emits both ["Install", "button"] and
+        # ["Install", " ", "button"]; a plain " ".join doubles the space in the
+        # second shape and breaks the regex a test author would naturally write.
+        joined = " ".join(item.text for item in self.items if item.kind == "text" and item.text)
+        return re.sub(r"\s+", " ", joined).strip()
+
+    def commands(self, type_name: str) -> list[SpeechItem]:
+        return [item for item in self.items if item.command_type == type_name]
+
+    def matches(self, pattern: str, *, flags: int = re.IGNORECASE) -> bool:
+        return re.search(pattern, self.text, flags) is not None
+
+    def __repr__(self) -> str:
+        suffix = " [cancelled]" if self.cancelled else ""
+        return f"<SpeechSequence {self.text!r}{suffix}>"
+
+
+def parse_sequence(payload: dict) -> SpeechSequence:
+    return SpeechSequence(
+        items=tuple(SpeechItem.from_payload(item) for item in payload.get("items") or []),
+        timestamp=float(payload.get("timestamp") or 0.0),
+        cancelled=bool(payload.get("cancelled")),
+    )
+
+
+def parse_sequences(payloads: list[dict]) -> list[SpeechSequence]:
+    return [parse_sequence(payload) for payload in payloads]

nvda_testkit/spybundle.py

@@ -0,0 +1,24 @@
+"""Locate the spy add-on bundle shipped inside the wheel."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .errors import ProvisionError
+
+BUNDLE_NAME = "nvda-testkit-spy.nvda-addon"
+
+
+def spy_bundle_path() -> Path:
+    bundle = Path(__file__).parent / "_spy" / BUNDLE_NAME
+    return bundle
+
+
+def require_spy_bundle() -> Path:
+    bundle = spy_bundle_path()
+    if not bundle.is_file():
+        raise ProvisionError(
+            f"The spy add-on bundle is missing at {bundle}. "
+            "In a source checkout, run: python tools/build_spy.py"
+        )
+    return bundle