argus-app-testing 0.1.1__py3-none-any.whl

argus/__init__.py

@@ -0,0 +1,17 @@
+"""Argus — universal application testing driven by multimodal LLMs.
+
+Argus watches an application the way a person would — through screenshots,
+the OS accessibility tree, terminal output — then drives it to satisfy tests
+written as a mix of natural-language steps and structured assertions.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("argus-app-testing")
+except PackageNotFoundError:
+    # Source trees that have not been installed do not have distribution
+    # metadata. Release and packaged builds always install/build the project
+    # first, so this fallback is intentionally descriptive rather than a fake
+    # release version.
+    __version__ = "0+unknown"

argus/__main__.py

@@ -0,0 +1,4 @@
+from argus.cli import main
+
+if __name__ == "__main__":
+    main()

argus/actions.py

@@ -0,0 +1,222 @@
+"""Validation and normalization for actions emitted by LLM providers.
+
+The model-facing protocol is intentionally JSON/dict based, but adapters must
+never receive arbitrary model output directly. This module defines the
+supported action vocabulary and validates executable fields before execution
+reaches an adapter or platform API.
+
+Keyboard actions deliberately use an Argus-owned canonical grammar. Model
+output is never allowed to contain pywinauto, X11/xdotool, Playwright, or other
+backend-specific key syntax; adapters translate the validated canonical chord
+to their native representation at the final execution boundary.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Dict
+
+
+class ActionValidationError(ValueError):
+    """Raised when an action is malformed or outside Argus' action schema."""
+
+
+SUPPORTED_ACTIONS = {
+    "click",
+    "double_click",
+    "right_click",
+    "type",
+    "key",
+    "scroll",
+    "menu",
+    "wait",
+    "done",
+    "navigate",
+    "run",
+    "execute",
+    "report_bug",
+}
+
+# Canonical key vocabulary. Intentionally excludes Windows/Super/Meta and any
+# raw virtual-key/X11 spelling. Additions here must be translated by every
+# adapter that advertises the ``key`` capability.
+KEY_MODIFIERS = ("ctrl", "alt", "shift")
+_KEY_MODIFIER_SET = set(KEY_MODIFIERS)
+KEY_NAMED = {
+    "enter",
+    "tab",
+    "esc",
+    "space",
+    "backspace",
+    "delete",
+    "up",
+    "down",
+    "left",
+    "right",
+    "home",
+    "end",
+    "pageup",
+    "pagedown",
+    "insert",
+    "minus",
+    "equals",
+    "comma",
+    "period",
+    "slash",
+    "semicolon",
+    "quote",
+    "backquote",
+    "bracketleft",
+    "bracketright",
+    "backslash",
+    *{f"f{i}" for i in range(1, 13)},
+}
+KEY_ALIASES = {
+    "control": "ctrl",
+    "return": "enter",
+    "escape": "esc",
+    "pgup": "pageup",
+    "pgdn": "pagedown",
+}
+_KEY_TOKEN_RE = re.compile(r"^[a-z0-9]+$")
+
+
+def canonicalize_key_chord(keys: str) -> str:
+    """Validate and normalize an Argus key chord.
+
+    Grammar: zero or more modifiers from ``ctrl|alt|shift`` plus exactly one
+    key, separated by ``+``. The key must be a single ASCII letter/digit or a
+    named key from :data:`KEY_NAMED`. Raw backend syntax such as ``{VK_LWIN}``,
+    ``Super_L``, bracketed expressions, whitespace-delimited backend commands,
+    and unknown tokens is rejected before any adapter can see it.
+    """
+    if not isinstance(keys, str) or not keys.strip():
+        raise ActionValidationError("key requires a non-empty keys string")
+
+    raw_parts = [part.strip().lower() for part in keys.split("+")]
+    if not raw_parts or any(not part for part in raw_parts):
+        raise ActionValidationError("key chord contains an empty token")
+    if len(raw_parts) > len(KEY_MODIFIERS) + 1:
+        raise ActionValidationError("key chord may contain at most three modifiers and one key")
+
+    parts: list[str] = []
+    for raw in raw_parts:
+        if not _KEY_TOKEN_RE.fullmatch(raw):
+            raise ActionValidationError(
+                f"key token {raw!r} uses unsupported/raw backend syntax"
+            )
+        part = KEY_ALIASES.get(raw, raw)
+        parts.append(part)
+
+    if len(parts) != len(set(parts)):
+        raise ActionValidationError("key chord contains duplicate tokens")
+
+    modifiers = [part for part in parts if part in _KEY_MODIFIER_SET]
+    keys_only = [part for part in parts if part not in _KEY_MODIFIER_SET]
+    if len(keys_only) != 1:
+        raise ActionValidationError("key chord must contain exactly one non-modifier key")
+
+    key = keys_only[0]
+    if not ((len(key) == 1 and key.isascii() and key.isalnum()) or key in KEY_NAMED):
+        raise ActionValidationError(f"unsupported key token {key!r}")
+
+    ordered_modifiers = [modifier for modifier in KEY_MODIFIERS if modifier in modifiers]
+    return "+".join([*ordered_modifiers, key])
+
+
+def validate_action(action: Dict[str, Any]) -> Dict[str, Any]:
+    """Return a normalized copy of *action* or raise ActionValidationError.
+
+    Extra explanatory/model metadata (for example ``why``) is intentionally
+    preserved; only executable fields are normalized and constrained here.
+    """
+    if not isinstance(action, dict):
+        raise ActionValidationError("action must be a JSON object")
+
+    normalized = dict(action)
+    kind = normalized.get("action")
+    if not isinstance(kind, str) or not kind.strip():
+        raise ActionValidationError("action field must be a non-empty string")
+    kind = kind.strip().lower()
+    normalized["action"] = kind
+    if kind not in SUPPORTED_ACTIONS:
+        raise ActionValidationError(
+            f"unknown action '{kind}' — supported: {', '.join(sorted(SUPPORTED_ACTIONS))}"
+        )
+
+    if kind in {"click", "double_click", "right_click"}:
+        has_element = "element_id" in normalized
+        has_xy = "x" in normalized or "y" in normalized
+        if not has_element and not has_xy:
+            raise ActionValidationError(f"{kind} requires element_id or x/y coordinates")
+        if has_element:
+            try:
+                normalized["element_id"] = int(normalized["element_id"])
+            except (TypeError, ValueError) as exc:
+                raise ActionValidationError("element_id must be an integer") from exc
+        if has_xy:
+            if "x" not in normalized or "y" not in normalized:
+                raise ActionValidationError("coordinate actions require both x and y")
+            try:
+                normalized["x"] = int(normalized["x"])
+                normalized["y"] = int(normalized["y"])
+            except (TypeError, ValueError) as exc:
+                raise ActionValidationError("x and y must be integers") from exc
+
+    elif kind == "type":
+        if "text" not in normalized:
+            raise ActionValidationError("type requires text")
+        normalized["text"] = str(normalized["text"])
+        if "element_id" in normalized:
+            try:
+                normalized["element_id"] = int(normalized["element_id"])
+            except (TypeError, ValueError) as exc:
+                raise ActionValidationError("element_id must be an integer") from exc
+
+    elif kind == "key":
+        normalized["keys"] = canonicalize_key_chord(normalized.get("keys"))
+
+    elif kind == "scroll":
+        direction = str(normalized.get("direction", "down")).strip().lower()
+        if direction not in {"up", "down"}:
+            raise ActionValidationError("scroll direction must be 'up' or 'down'")
+        try:
+            amount = int(normalized.get("amount", 3))
+        except (TypeError, ValueError) as exc:
+            raise ActionValidationError("scroll amount must be an integer") from exc
+        if amount < 1 or amount > 100:
+            raise ActionValidationError("scroll amount must be between 1 and 100")
+        normalized["direction"] = direction
+        normalized["amount"] = amount
+
+    elif kind == "wait":
+        try:
+            seconds = float(normalized.get("seconds", 1.0))
+        except (TypeError, ValueError) as exc:
+            raise ActionValidationError("wait seconds must be numeric") from exc
+        if seconds < 0 or seconds > 30:
+            raise ActionValidationError("wait seconds must be between 0 and 30")
+        normalized["seconds"] = seconds
+
+    elif kind == "menu":
+        path = normalized.get("path")
+        if not isinstance(path, str) or not path.strip():
+            raise ActionValidationError("menu requires a non-empty path")
+        normalized["path"] = path.strip()
+
+    elif kind == "navigate":
+        url = normalized.get("url")
+        if not isinstance(url, str) or not url.strip():
+            raise ActionValidationError("navigate requires a non-empty url")
+        normalized["url"] = url.strip()
+
+    elif kind in {"run", "execute"}:
+        command = normalized.get("command")
+        if not isinstance(command, str) or not command.strip():
+            raise ActionValidationError(f"{kind} requires a non-empty command")
+        normalized["command"] = command.strip()
+
+    elif kind == "done" and "success" in normalized:
+        if not isinstance(normalized["success"], bool):
+            raise ActionValidationError("done.success must be true or false")
+
+    return normalized

argus/adapters/__init__.py

@@ -0,0 +1,19 @@
+"""Target adapter API.
+
+``create_adapter`` is the session-level compatibility factory. It now honors the
+project's configured execution location, returning either a local environment or
+a disposable Capsule. Low-level platform adapter construction remains available
+from :mod:`argus.adapters.base` for the execution layer and guest agent.
+"""
+
+from argus.adapters.base import Adapter, AdapterError, Observation, UIElement
+
+
+def create_adapter(adapter_type: str):
+    """Create the configured execution environment for ``adapter_type``."""
+    from argus.config import load_config
+
+    return load_config().make_execution_environment(adapter_type)
+
+
+__all__ = ["Adapter", "AdapterError", "Observation", "UIElement", "create_adapter"]

argus/adapters/base.py

@@ -0,0 +1,291 @@
+"""Adapter interface — how Argus connects to a *target* application.
+
+An adapter knows how to:
+  * **launch** the target,
+  * **observe** it (screenshot + accessibility tree + window state), and
+  * **act** on it (click, type, press keys, …).
+
+Adapters created through :func:`create_adapter` are wrapped in
+:class:`PolicyAdapter`. This keeps the current engine API compatible while
+ensuring every model-generated action is schema-validated, capability-authorized,
+and policy-checked before it reaches platform input APIs.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+class AdapterError(RuntimeError):
+    """Raised when the target cannot be launched / observed / driven."""
+
+
+@dataclass
+class UIElement:
+    """One node of the accessibility (UIA) tree, with a stable id the LLM
+    can reference in actions."""
+
+    element_id: int
+    control_type: str
+    name: str
+    rect: tuple  # (left, top, right, bottom)
+    enabled: bool = True
+    depth: int = 0
+
+    def describe(self) -> str:
+        name = self.name.strip() or "(unnamed)"
+        flags = "" if self.enabled else " [disabled]"
+        return (
+            f"{'  ' * self.depth}[{self.element_id}] {self.control_type} "
+            f'"{name}"{flags} @({self.rect[0]},{self.rect[1]},{self.rect[2]},{self.rect[3]})'
+        )
+
+
+@dataclass
+class Observation:
+    """One snapshot of the target application."""
+
+    window_title: str
+    elements: List[UIElement] = field(default_factory=list)
+    screenshot_png: Optional[bytes] = None
+    process_alive: bool = True
+    dialogs: List[str] = field(default_factory=list)
+    error: Optional[str] = None
+    stdout: Optional[str] = None
+    stderr: Optional[str] = None
+    exit_code: Optional[int] = None
+    url: Optional[str] = None
+    action_capabilities: Optional[dict] = None
+
+    def tree_text(self, max_elements: int = 120) -> str:
+        lines = [el.describe() for el in self.elements[:max_elements]]
+        if len(self.elements) > max_elements:
+            lines.append(f"... ({len(self.elements) - max_elements} more elements truncated)")
+        return "\n".join(lines) or "(no accessible elements found)"
+
+    def find_text(self, needle: str) -> bool:
+        needle = needle.lower()
+        if needle in self.window_title.lower():
+            return True
+        if self.stdout and needle in self.stdout.lower():
+            return True
+        if self.stderr and needle in self.stderr.lower():
+            return True
+        return any(needle in el.name.lower() for el in self.elements)
+
+
+class Adapter(ABC):
+    """Abstract base for target adapters."""
+
+    type_name: str = "base"
+
+    @abstractmethod
+    def launch(self, target: str) -> None:
+        """Start (or attach to) the application under test."""
+
+    @abstractmethod
+    def observe(self, include_screenshot: bool = True) -> Observation:
+        """Capture the current state of the target."""
+
+    def capabilities(self) -> dict:
+        """Describe executable actions authorized for this adapter.
+
+        The base contract is intentionally minimal/fail-closed. Concrete
+        adapters must opt into every interactive capability they support so a
+        new adapter can never silently inherit mouse, keyboard, menu, or shell
+        powers that its ``act`` implementation happens to provide.
+        """
+        return {
+            "actions": {
+                "wait": {},
+                "done": {},
+            },
+            "notes": ["This adapter has not declared interactive capabilities."],
+        }
+
+    def _authorize_capability(self, action: dict) -> None:
+        """Enforce this adapter's declared capability contract.
+
+        Capabilities are authorization, not merely prompt metadata. An action
+        kind must be declared before it can dispatch, and common target-shape
+        constraints are checked centrally so an adapter cannot accidentally
+        accept a broader form than it advertised.
+        """
+        capabilities = self.capabilities() or {}
+        actions = capabilities.get("actions") or {}
+        kind = str(action.get("action") or "").lower()
+
+        if kind not in actions:
+            raise AdapterError(
+                f"action blocked: adapter '{self.type_name}' does not declare capability '{kind}'"
+            )
+
+        spec = actions.get(kind) or {}
+
+        if kind in {"click", "double_click", "right_click"}:
+            has_element = "element_id" in action
+            has_coordinates = "x" in action or "y" in action
+            element_mode = spec.get("element_id", "optional")
+
+            if element_mode == "required" and not has_element:
+                raise AdapterError(
+                    f"action blocked: adapter '{self.type_name}' requires element_id for '{kind}'"
+                )
+            if element_mode == "none" and has_element:
+                raise AdapterError(
+                    f"action blocked: adapter '{self.type_name}' forbids element_id for '{kind}'"
+                )
+            if has_coordinates and not bool(spec.get("coordinates", False)):
+                raise AdapterError(
+                    f"action blocked: adapter '{self.type_name}' forbids coordinates for '{kind}'"
+                )
+
+        if kind == "type":
+            has_element = "element_id" in action
+            element_mode = spec.get("element_id", "optional")
+            if element_mode == "required" and not has_element:
+                raise AdapterError(
+                    f"action blocked: adapter '{self.type_name}' requires element_id for 'type'"
+                )
+            if element_mode == "none" and has_element:
+                raise AdapterError(
+                    f"action blocked: adapter '{self.type_name}' forbids element_id for 'type'"
+                )
+
+        if kind in {"run", "execute"} and spec.get("command") == "required":
+            if "command" not in action:
+                raise AdapterError(
+                    f"action blocked: adapter '{self.type_name}' requires command for '{kind}'"
+                )
+
+    def prepare_action(self, action: dict) -> dict:
+        """Normalize and authorize *action* without performing its side effect.
+
+        The returned mapping is the exact action that is permitted to cross the
+        dispatch boundary. Splitting preparation from dispatch gives ATES a
+        durable commit point after all schema/policy/capability/platform checks
+        but before any target-visible mutation can begin.
+        """
+        from argus.actions import ActionValidationError, validate_action
+        from argus.policy import ActionPolicyError, enforce_action_policy
+
+        try:
+            normalized = validate_action(action)
+            enforce_action_policy(normalized)
+        except (ActionValidationError, ActionPolicyError) as exc:
+            raise AdapterError(f"action blocked: {exc}") from exc
+
+        self._authorize_capability(normalized)
+        self.validate_action(normalized)
+        return normalized
+
+    def dispatch_prepared_action(self, action: dict) -> str:
+        """Execute an action already returned by :meth:`prepare_action`.
+
+        Callers must never use this as a validation bypass for untrusted model
+        output. It exists so a durable evidence writer can commit dispatch
+        intent between authorization and the actual side effect.
+        """
+        return self.act(action)
+
+    def execute(self, action: dict) -> str:
+        """Validate, authorize and execute one model-generated action."""
+        normalized = self.prepare_action(action)
+        return self.dispatch_prepared_action(normalized)
+
+    def validate_action(self, action: dict) -> None:
+        """Platform-specific policy hook invoked immediately before dispatch."""
+
+    @abstractmethod
+    def act(self, action: dict) -> str:
+        """Execute an already validated and authorized action; returns a short note."""
+
+    @abstractmethod
+    def close(self) -> None:
+        """Tear down the target application."""
+
+
+class PolicyAdapter(Adapter):
+    """Compatibility guard around an adapter used by the current engines.
+
+    The runner and roam engine historically call ``adapter.act`` directly.
+    Wrapping adapters here means those calls still pass through the inner
+    adapter's validation/authorization boundary without a broad engine rewrite.
+    """
+
+    def __init__(self, inner: Adapter) -> None:
+        self.inner = inner
+        self.type_name = inner.type_name
+
+    def launch(self, target: str) -> None:
+        self.inner.launch(target)
+
+    def observe(self, include_screenshot: bool = True) -> Observation:
+        obs = self.inner.observe(include_screenshot=include_screenshot)
+        obs.action_capabilities = self.capabilities()
+        return obs
+
+    def capabilities(self) -> dict:
+        return self.inner.capabilities()
+
+    def prepare_action(self, action: dict) -> dict:
+        return self.inner.prepare_action(action)
+
+    def dispatch_prepared_action(self, action: dict) -> str:
+        return self.inner.dispatch_prepared_action(action)
+
+    def act(self, action: dict) -> str:
+        normalized = self.prepare_action(action)
+        return self.dispatch_prepared_action(normalized)
+
+    def validate_action(self, action: dict) -> None:
+        self.inner.validate_action(action)
+
+    def close(self) -> None:
+        self.inner.close()
+
+    def __getattr__(self, name):
+        return getattr(self.inner, name)
+
+
+def _guard(adapter: Adapter) -> Adapter:
+    return adapter if isinstance(adapter, PolicyAdapter) else PolicyAdapter(adapter)
+
+
+def create_adapter(adapter_type: str) -> Adapter:
+    adapter_type = (adapter_type or "").lower().strip()
+    if adapter_type in ("desktop-gui", "desktop", "gui"):
+        if sys.platform == "win32":
+            input_mode = (os.environ.get("ARGUS_INPUT_MODE") or "safe").lower().strip()
+            if input_mode in {"physical", "legacy"}:
+                from argus.adapters.windows_gui import WindowsGUIAdapter
+                return _guard(WindowsGUIAdapter())
+            if input_mode not in {"safe", "semantic"}:
+                raise AdapterError(
+                    "ARGUS_INPUT_MODE must be 'safe'/'semantic' or explicit 'physical'"
+                )
+            from argus.adapters.windows_safe import SafeWindowsGUIAdapter
+            return _guard(SafeWindowsGUIAdapter())
+        if sys.platform.startswith("linux"):
+            from argus.adapters.linux_gui import LinuxGUIAdapter
+            return _guard(LinuxGUIAdapter())
+        raise AdapterError(
+            "the desktop-gui adapter supports Windows and Linux "
+            f"(this is {sys.platform}). macOS support is on the roadmap."
+        )
+    if adapter_type in ("cli", "terminal", "shell"):
+        from argus.adapters.cli_adapter import CLIAdapter
+        return _guard(CLIAdapter())
+    if adapter_type in ("browser", "web", "playwright"):
+        from argus.adapters.browser_adapter import BrowserAdapter
+        return _guard(BrowserAdapter())
+    if adapter_type in ("linux-gui", "linux_gui", "x11"):
+        from argus.adapters.linux_gui import LinuxGUIAdapter
+        return _guard(LinuxGUIAdapter())
+    raise AdapterError(
+        f"unknown adapter '{adapter_type}' — available: desktop-gui, cli, browser"
+    )