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

nvda_testkit/client.py

@@ -0,0 +1,114 @@
+"""NvdaClient -- the object every test receives as the `nvda` fixture."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .errors import TestkitError
+from .namespaces.addons import AddonsNamespace
+from .namespaces.braille import BrailleNamespace
+from .namespaces.config import ConfigNamespace
+from .namespaces.keys import KeysNamespace
+from .namespaces.log import LogNamespace
+from .namespaces.speech import SpeechNamespace
+from .process import NvdaProcess
+from .rpcclient import RpcClient
+from .settings import TestkitSettings
+
+
+@dataclass(frozen=True)
+class NvdaVersion:
+    version: str
+    api_version: str | None
+    api_compat_to: str | None
+    channel: str = "unknown"
+
+
+class NvdaClient:
+    def __init__(
+        self,
+        process: NvdaProcess,
+        rpc: RpcClient,
+        settings: TestkitSettings | None = None,
+    ) -> None:
+        self._process = process
+        self._rpc = rpc
+        self._settings = settings or TestkitSettings()
+        self._attach(rpc)
+        # Taken once, at connect time, and reused by every reset(). Capturing it
+        # per-test would bake in whatever the previous test left behind.
+        self._baseline_config = self.config.snapshot()
+
+    def _attach(self, rpc: RpcClient) -> None:
+        self._rpc = rpc
+        self.addons = AddonsNamespace(rpc)
+        self.speech = SpeechNamespace(rpc)
+        self.braille = BrailleNamespace(rpc)
+        self.keys = KeysNamespace(rpc)
+        self.config = ConfigNamespace(rpc)
+        self.log = LogNamespace(rpc)
+
+    @property
+    def rpc(self) -> RpcClient:
+        return self._rpc
+
+    @property
+    def process(self) -> NvdaProcess:
+        return self._process
+
+    @property
+    def version(self) -> NvdaVersion:
+        handshake = self._process.handshake
+        if handshake is None:
+            raise TestkitError("NVDA is not running; no version information available.")
+        return NvdaVersion(
+            version=handshake.nvda_version,
+            api_version=handshake.api_version,
+            api_compat_to=handshake.api_compat_to,
+            channel=self._settings.channel,
+        )
+
+    def wait_until_idle(self, *, timeout: float = 10.0) -> None:
+        self._rpc.call("wait_until_idle", timeout)
+
+    def reset(self) -> None:
+        """Return NVDA to the state a test should start from."""
+        # Attempt every step even if one fails, then report. A partial reset is
+        # worse than a failed one: it is inherited silently by the next test.
+        failures = []
+        for label, step in (
+            ("speech", self.speech.clear),
+            ("braille", self.braille.clear),
+            ("log", self.log.clear),
+            ("config", lambda: self.config.restore(self._baseline_config)),
+        ):
+            try:
+                step()
+            except Exception as error:
+                failures.append(f"{label}: {error}")
+        if failures:
+            raise TestkitError("reset() failed for " + "; ".join(failures))
+
+    def restart(self, *, timeout: float = 60.0) -> None:
+        handshake = self._process.restart(timeout=timeout)
+        self._rpc.close()
+        self._attach(
+            RpcClient.from_handshake(
+                handshake,
+                token=self._process.token,
+                timeout_scale=self._settings.timeout_scale,
+            )
+        )
+
+    def eval(self, source: str) -> Any:
+        if not self._settings.allow_eval:
+            raise TestkitError(
+                "nvda.eval() is disabled. It runs arbitrary code inside NVDA, so it is "
+                "opt-in: pass --nvda-allow-eval, or set allow-eval = true under "
+                "[tool.nvda-testkit]."
+            )
+        return self._rpc.call("eval_in_nvda", source)
+
+    def close(self) -> None:
+        self._rpc.close()

nvda_testkit/download.py

@@ -0,0 +1,73 @@
+"""Fetch NVDA launchers, verify them against nvaccess's published SHA-1, and
+cache them on disk.
+
+The digest check is not decoration: this code downloads an executable and then
+runs it. A launcher whose digest does not match is deleted, not quarantined.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+from collections.abc import Callable
+from pathlib import Path
+
+from .errors import HashMismatchError
+from .resolve import LauncherInfo, fetch_url
+
+_UNSAFE = re.compile(r"[^A-Za-z0-9._-]")
+
+
+def default_cache_dir() -> Path:
+    override = os.environ.get("NVDA_TESTKIT_CACHE")
+    if override:
+        return Path(override)
+    return Path.home() / ".cache" / "nvda-testkit"
+
+
+def sha1_file(path: Path) -> str:
+    digest = hashlib.sha1()  # NOSONAR -- nvaccess publishes SHA-1; matches NVDA's own updater
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _cache_name(info: LauncherInfo) -> str:
+    stem = info.sha1 or f"{info.channel}-{info.version}"
+    return _UNSAFE.sub("_", stem) + ".exe"
+
+
+def ensure_launcher(
+    info: LauncherInfo,
+    cache_dir: Path | None = None,
+    *,
+    fetch: Callable[[str], bytes] = fetch_url,
+) -> Path:
+    """Return a path to a launcher for `info`, downloading it if necessary."""
+    cache_dir = Path(cache_dir) if cache_dir is not None else default_cache_dir()
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    target = cache_dir / _cache_name(info)
+
+    if target.exists():
+        if info.sha1 is None or sha1_file(target) == info.sha1:
+            return target
+        target.unlink()
+
+    partial = target.with_suffix(".part")
+    payload = fetch(info.url)
+    partial.write_bytes(payload)
+
+    actual = sha1_file(partial)
+    if info.sha1 is not None and actual != info.sha1:
+        partial.unlink()
+        raise HashMismatchError(expected=info.sha1, actual=actual, path=str(target))
+
+    os.replace(partial, target)
+    if info.sha1 is None:
+        # Nothing to check against, so record what we actually got. This ends up
+        # in the artifact bundle, which is the only way to tell after the fact
+        # which alpha build a failure came from.
+        target.with_suffix(".sha1").write_text(actual + "\n", encoding="ascii")
+    return target

nvda_testkit/errors.py

@@ -0,0 +1,59 @@
+"""Exception hierarchy. Every error the kit raises descends from TestkitError."""
+
+
+class TestkitError(Exception):
+    """Base for every error raised by nvda-addon-testkit."""
+
+
+class ProvisionError(TestkitError):
+    """Failed to obtain or prepare an NVDA to test against."""
+
+
+class LauncherResolutionError(ProvisionError):
+    """Could not work out which NVDA launcher to download."""
+
+
+class HashMismatchError(ProvisionError):
+    """A downloaded launcher did not match its published digest."""
+
+    def __init__(self, *, expected: str, actual: str, path: str) -> None:
+        self.expected = expected
+        self.actual = actual
+        self.path = path
+        super().__init__(
+            f"Launcher digest mismatch for {path}: expected {expected}, got {actual}. "
+            "Refusing to execute it."
+        )
+
+
+class UnsupportedPlatformError(TestkitError):
+    """This operation needs a real Windows host."""
+
+
+class NvdaStartupError(TestkitError):
+    """NVDA failed to start, or died before it was usable."""
+
+
+class HandshakeTimeout(NvdaStartupError):
+    """NVDA started but the spy add-on never announced itself."""
+
+
+class RpcError(TestkitError):
+    """A call into the spy add-on failed."""
+
+
+class AuthError(RpcError):
+    """The spy rejected our token. Almost always a stale NVDA from a previous run."""
+
+
+class WaitTimeout(TestkitError):
+    """A deadline-bounded poll expired before its predicate came true."""
+
+    def __init__(self, description: str, timeout: float, last_seen: object = None) -> None:
+        self.description = description
+        self.timeout = timeout
+        self.last_seen = last_seen
+        message = f"Timed out after {timeout:.1f}s waiting for {description}."
+        if last_seen is not None:
+            message += f" Last seen: {last_seen!r}"
+        super().__init__(message)

nvda_testkit/namespaces/__init__.py

@@ -0,0 +1 @@
+"""Namespaces hung off NvdaClient: nvda.speech, nvda.braille, and so on."""

nvda_testkit/namespaces/addons.py

@@ -0,0 +1,58 @@
+"""nvda.addons -- add-on install lifecycle.
+
+Installation is two-phase, and that is exposed rather than hidden: install()
+leaves the add-on PENDING_INSTALL, and only nvda.restart() makes it ENABLED.
+A test of installTasks.onInstall depends on being able to see both halves.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+from ..rpcclient import RpcClient
+
+
+class AddonState(StrEnum):
+    NOT_INSTALLED = "NOT_INSTALLED"
+    PENDING_INSTALL = "PENDING_INSTALL"
+    ENABLED = "ENABLED"
+    DISABLED = "DISABLED"
+    PENDING_REMOVE = "PENDING_REMOVE"
+    INCOMPATIBLE = "INCOMPATIBLE"
+
+
+@dataclass(frozen=True)
+class AddonInfo:
+    name: str
+    version: str
+    state: AddonState
+
+    @classmethod
+    def from_payload(cls, payload: dict) -> AddonInfo:
+        return cls(
+            name=payload["name"],
+            version=payload.get("version", "unknown"),
+            state=AddonState(payload.get("state", "NOT_INSTALLED")),
+        )
+
+
+class AddonsNamespace:
+    def __init__(self, rpc: RpcClient) -> None:
+        self._rpc = rpc
+
+    def list(self) -> list[AddonInfo]:
+        return [AddonInfo.from_payload(entry) for entry in self._rpc.call("addons_list")]
+
+    def state(self, name: str) -> AddonState:
+        return AddonState(self._rpc.call("addons_state", name))
+
+    def install(self, bundle_path: str | Path) -> AddonInfo:
+        """Install a bundle. The add-on stays PENDING_INSTALL until a restart."""
+        payload = self._rpc.call("addons_install", str(Path(bundle_path).resolve()))
+        return AddonInfo.from_payload(payload)
+
+    def remove(self, name: str) -> None:
+        """Mark for removal. Takes effect on the next restart."""
+        self._rpc.call("addons_remove", name)

nvda_testkit/namespaces/braille.py

@@ -0,0 +1,57 @@
+"""nvda.braille -- the raw text NVDA sent to the braille display."""
+
+from __future__ import annotations
+
+import re
+
+from ..rpcclient import RpcClient
+
+
+class BrailleNamespace:
+    def __init__(self, rpc: RpcClient) -> None:
+        self._rpc = rpc
+
+    def index(self) -> int:
+        return int(self._rpc.call("braille_index"))
+
+    def since(self, index: int) -> list[str]:
+        return [entry["text"] for entry in self._rpc.call("braille_since", index)]
+
+    def all(self) -> list[str]:
+        return self.since(0)
+
+    def last(self) -> str | None:
+        writes = self.all()
+        return writes[-1] if writes else None
+
+    def clear(self) -> None:
+        self._rpc.call("braille_clear")
+
+    def set_cell_count(self, count: int) -> None:
+        self._rpc.call("braille_set_cell_count", int(count))
+
+    def cell_count(self) -> int:
+        return int(self._rpc.call("braille_cell_count"))
+
+    def wait_for(
+        self,
+        pattern: str,
+        *,
+        timeout: float = 10.0,
+        since: int | None = None,
+        flags: int = re.IGNORECASE,
+    ) -> str:
+        start = self.index() if since is None else since
+
+        def find():
+            for text in self.since(start):
+                if re.search(pattern, text, flags):
+                    return text
+            return None
+
+        return self._rpc.poll_until(
+            find,
+            timeout=timeout,
+            description=f"braille matching {pattern!r}",
+            last_seen=lambda: self.since(start),
+        )

nvda_testkit/namespaces/config.py

@@ -0,0 +1,30 @@
+"""nvda.config -- read and write NVDA's configuration."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..rpcclient import RpcClient
+
+
+def _as_list(path) -> list[str]:
+    if isinstance(path, str):
+        return [path]
+    return list(path)
+
+
+class ConfigNamespace:
+    def __init__(self, rpc: RpcClient) -> None:
+        self._rpc = rpc
+
+    def get(self, path) -> Any:
+        return self._rpc.call("config_get", _as_list(path))
+
+    def set(self, path, value: Any) -> None:
+        self._rpc.call("config_set", _as_list(path), value)
+
+    def snapshot(self) -> dict:
+        return self._rpc.call("config_snapshot")
+
+    def restore(self, snapshot: dict) -> None:
+        self._rpc.call("config_restore", snapshot)

nvda_testkit/namespaces/keys.py

@@ -0,0 +1,30 @@
+"""nvda.keys -- send gestures through NVDA's own input pipeline.
+
+press() returns only once NVDA has finished reacting, so a test never needs to
+sleep between a keypress and the assertion about what it caused.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..rpcclient import RpcClient
+
+
+class KeysNamespace:
+    def __init__(self, rpc: RpcClient) -> None:
+        self._rpc = rpc
+
+    def press(self, gesture: str, *, timeout: float = 10.0) -> None:
+        self._rpc.call("keys_press", gesture, timeout)
+
+    def press_all(self, *gestures: str, timeout: float = 10.0) -> None:
+        for gesture in gestures:
+            self.press(gesture, timeout=timeout)
+
+    def type_text(self, text: str, *, timeout: float = 30.0) -> None:
+        self._rpc.call("keys_type", text, timeout)
+
+    def sent(self) -> list[dict[str, Any]]:
+        """Every gesture sent this session. Goes into the replay trace."""
+        return list(self._rpc.call("keys_sent"))

nvda_testkit/namespaces/log.py

@@ -0,0 +1,95 @@
+"""nvda.log -- NVDA's log as structured records.
+
+assert_no_errors quotes every offending record in its failure message. That
+message is frequently the only diagnostic available to a maintainer reading a
+CI log on a machine that cannot run NVDA at all.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from ..rpcclient import RpcClient
+
+_ERROR_LEVELS = frozenset({"ERROR", "CRITICAL"})
+_WARNING_LEVELS = frozenset({"WARNING", "ERROR", "CRITICAL"})
+
+
+@dataclass(frozen=True)
+class LogRecord:
+    level: str
+    message: str
+    timestamp: float = 0.0
+
+    def __repr__(self) -> str:
+        return f"{self.level}: {self.message}"
+
+
+def _parse(payloads: list[dict]) -> list[LogRecord]:
+    return [
+        LogRecord(
+            level=str(payload.get("level", "")),
+            message=str(payload.get("message", "")),
+            timestamp=float(payload.get("timestamp") or 0.0),
+        )
+        for payload in payloads
+    ]
+
+
+class LogNamespace:
+    def __init__(self, rpc: RpcClient) -> None:
+        self._rpc = rpc
+
+    def index(self) -> int:
+        return int(self._rpc.call("log_index"))
+
+    def since(self, index: int) -> list[LogRecord]:
+        return _parse(self._rpc.call("log_since", index))
+
+    def all(self) -> list[LogRecord]:
+        return self.since(0)
+
+    def clear(self) -> None:
+        self._rpc.call("log_clear")
+
+    def errors(self, *, since: int = 0) -> list[LogRecord]:
+        return [record for record in self.since(since) if record.level in _ERROR_LEVELS]
+
+    def warnings(self, *, since: int = 0) -> list[LogRecord]:
+        return [record for record in self.since(since) if record.level in _WARNING_LEVELS]
+
+    def _assert_clean(self, records: list[LogRecord], label: str) -> None:
+        if not records:
+            return
+        listing = "\n".join(f"  {record}" for record in records)
+        raise AssertionError(f"NVDA logged {len(records)} {label}:\n{listing}")
+
+    def assert_no_errors(self, *, since: int = 0) -> None:
+        self._assert_clean(self.errors(since=since), "error(s)")
+
+    def assert_no_warnings(self, *, since: int = 0) -> None:
+        self._assert_clean(self.warnings(since=since), "warning(s) or error(s)")
+
+    def wait_for(
+        self,
+        pattern: str,
+        *,
+        timeout: float = 10.0,
+        since: int | None = None,
+        flags: int = re.IGNORECASE,
+    ) -> LogRecord:
+        start = self.index() if since is None else since
+
+        def find():
+            for record in self.since(start):
+                if re.search(pattern, record.message, flags):
+                    return record
+            return None
+
+        return self._rpc.poll_until(
+            find,
+            timeout=timeout,
+            description=f"a log record matching {pattern!r}",
+            last_seen=lambda: [record.message for record in self.since(start)],
+        )

nvda_testkit/namespaces/speech.py

@@ -0,0 +1,76 @@
+"""nvda.speech -- what NVDA asked to say."""
+
+from __future__ import annotations
+
+from ..rpcclient import RpcClient
+from ..speechtypes import SpeechSequence, parse_sequences
+
+
+class SpeechNamespace:
+    def __init__(self, rpc: RpcClient) -> None:
+        self._rpc = rpc
+
+    def index(self) -> int:
+        """The current cursor. Pass it to since() to ignore everything so far."""
+        return int(self._rpc.call("speech_index"))
+
+    def since(self, index: int) -> list[SpeechSequence]:
+        return parse_sequences(self._rpc.call("speech_since", index))
+
+    def all(self) -> list[SpeechSequence]:
+        return self.since(0)
+
+    def last(self) -> SpeechSequence | None:
+        sequences = self.all()
+        return sequences[-1] if sequences else None
+
+    def clear(self) -> None:
+        self._rpc.call("speech_clear")
+
+    def speak(self, text: str) -> None:
+        self._rpc.call("speech_speak", text)
+
+    def cancel(self) -> None:
+        self._rpc.call("speech_cancel")
+
+    def cancel_count(self) -> int:
+        return int(self._rpc.call("speech_cancel_count"))
+
+    def wait_for(
+        self,
+        pattern: str,
+        *,
+        timeout: float = 10.0,
+        since: int | None = None,
+    ) -> SpeechSequence:
+        """Wait for a sequence whose text matches `pattern` (regex, case-insensitive).
+
+        By default only speech produced after this call counts. Pass since=0 to
+        search everything captured so far.
+
+        Snapshots index() when called, so it cannot see speech already
+        emitted. After a synchronous action such as press() or speak(),
+        capture index() before the action and pass it as since.
+        """
+        start = self.index() if since is None else since
+
+        def find():
+            for sequence in self.since(start):
+                if sequence.matches(pattern):
+                    return sequence
+            return None
+
+        return self._rpc.poll_until(
+            find,
+            timeout=timeout,
+            description=f"speech matching {pattern!r}",
+            last_seen=lambda: [sequence.text for sequence in self.since(start)],
+        )
+
+    def wait_for_done(self, *, timeout: float = 10.0) -> None:
+        """Wait until NVDA's event queue has drained, i.e. speech has been dispatched."""
+        self._rpc.poll_until(
+            lambda: self._rpc.call("wait_until_idle", 5.0),
+            timeout=timeout,
+            description="NVDA to finish dispatching speech",
+        )