nat-engine 1__py3-none-any.whl

mannf/core/agents/browser_coordinator_agent.py

@@ -0,0 +1,224 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""BrowserCoordinatorAgent – ECNP coordinator for browser-based functional tests.
+
+Extends :class:`CoordinatorAgent` to handle browser-specific task coordination:
+
+  * Creates browser-specific ECNP task announcements with ``url``, ``steps``,
+    and ``task_type: "browser"``.
+  * Collects ``INTERACTION_RESULT`` messages to track browser test completions.
+  * Tracks DOM snapshots and screenshots received from browser agents.
+  * Provides :meth:`dispatch_browser_task` for programmatic task submission.
+  * Provides :meth:`get_functional_results` to retrieve aggregated outcomes.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import uuid
+from typing import Any
+
+from mannf.core.agents.coordinator_agent import CoordinatorAgent
+from mannf.core.messaging.bus import MessageBus
+from mannf.core.messaging.messages import Message, MessageType
+
+logger = logging.getLogger(__name__)
+
+
+class BrowserCoordinatorAgent(CoordinatorAgent):
+    """Coordinator that handles browser-based functional testing tasks.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier.
+    bus:
+        Shared message bus.
+    service_names:
+        Services tracked by the BDI belief state.
+    bid_timeout_s:
+        ECNP bid collection window (seconds).
+    max_renegotiations:
+        Maximum re-announcements when no bids arrive.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        bus: MessageBus,
+        service_names: list[str],
+        bid_timeout_s: float = 0.05,
+        max_renegotiations: int = 2,
+    ) -> None:
+        super().__init__(
+            agent_id=agent_id,
+            bus=bus,
+            service_names=service_names,
+            bid_timeout_s=bid_timeout_s,
+            max_renegotiations=max_renegotiations,
+        )
+
+        # task_id -> {url, steps, status, result}
+        self._browser_tasks: dict[str, dict[str, Any]] = {}
+
+        # Aggregated pass/fail counters
+        self._passed_count = 0
+        self._failed_count = 0
+
+        # Collected telemetry from browser agents
+        self._dom_snapshots: list[dict[str, Any]] = []
+        self._screenshots: list[dict[str, Any]] = []
+
+    # ------------------------------------------------------------------
+    # Subscriptions
+    # ------------------------------------------------------------------
+
+    @property
+    def subscribed_types(self) -> set[MessageType]:
+        return super().subscribed_types | {
+            MessageType.INTERACTION_RESULT,
+            MessageType.DOM_SNAPSHOT,
+            MessageType.SCREENSHOT_CAPTURED,
+        }
+
+    # ------------------------------------------------------------------
+    # Message handling
+    # ------------------------------------------------------------------
+
+    async def _handle_message(self, message: Message) -> None:
+        if message.type == MessageType.INTERACTION_RESULT:
+            self._handle_interaction_result(message)
+        elif message.type == MessageType.DOM_SNAPSHOT:
+            self._dom_snapshots.append(message.payload or {})
+        elif message.type == MessageType.SCREENSHOT_CAPTURED:
+            self._screenshots.append(message.payload or {})
+        else:
+            await super()._handle_message(message)
+
+    def _handle_interaction_result(self, message: Message) -> None:
+        """Record the outcome of a completed browser task."""
+        payload: dict[str, Any] = message.payload or {}
+        task_id: str | None = payload.get("task_id")
+
+        passed: bool = bool(payload.get("passed", False))
+
+        if task_id and task_id in self._browser_tasks:
+            self._browser_tasks[task_id]["status"] = "passed" if passed else "failed"
+            self._browser_tasks[task_id]["result"] = payload
+        else:
+            # Result for a task not tracked here (e.g. ad-hoc INTERACTION_REQUEST)
+            logger.debug(
+                "BrowserCoordinatorAgent %s: INTERACTION_RESULT for unknown task_id %r",
+                self.agent_id, task_id,
+            )
+
+        if passed:
+            self._passed_count += 1
+        else:
+            self._failed_count += 1
+
+        logger.debug(
+            "BrowserCoordinatorAgent %s: task %s → %s",
+            self.agent_id, task_id, "PASS" if passed else "FAIL",
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def dispatch_browser_task(
+        self,
+        url: str,
+        steps: list[dict[str, Any]],
+        *,
+        task_id: str | None = None,
+    ) -> str:
+        """Announce a browser-based functional test task via ECNP.
+
+        Parameters
+        ----------
+        url:
+            The URL to navigate to.
+        steps:
+            List of interaction steps, e.g.
+            ``[{"action": "fill", "selector": "#email", "value": "..."}]``.
+        task_id:
+            Optional explicit task identifier; generated if not provided.
+
+        Returns
+        -------
+        str
+            The ``task_id`` assigned to this task.
+        """
+        if task_id is None:
+            task_id = str(uuid.uuid4())
+
+        task: dict[str, Any] = {
+            "task_id": task_id,
+            "task_type": "browser",
+            "target": url,   # ExecutorAgent._evaluate_and_bid uses "target"
+            "url": url,
+            "steps": steps,
+            "priority": 0.5,
+            "risk_estimate": 0.5,
+        }
+
+        self._browser_tasks[task_id] = {
+            "url": url,
+            "steps": steps,
+            "status": "pending",
+            "result": None,
+        }
+
+        # Track task_id so _handle_announcement's dedup check doesn't skip it
+        # Initialize _pending_bids for this task_id so the award phase works
+        if task_id not in self._pending_bids:
+            self._pending_bids[task_id] = []
+
+        await self._publish(
+            Message(MessageType.TASK_ANNOUNCEMENT, self.agent_id, task)
+        )
+
+        # Start bid-collection window and subsequent award (ECNP phase 3→5)
+        asyncio.get_running_loop().create_task(
+            self._award_after_timeout(task)
+        )
+
+        logger.debug(
+            "BrowserCoordinatorAgent %s: dispatched browser task %s → %s",
+            self.agent_id, task_id, url,
+        )
+        return task_id
+
+    def get_functional_results(self) -> dict[str, Any]:
+        """Return a summary of all browser test outcomes.
+
+        Returns
+        -------
+        dict
+            ``{passed, failed, total, tasks, dom_snapshots, screenshots}``
+        """
+        return {
+            "passed": self._passed_count,
+            "failed": self._failed_count,
+            "total": self._passed_count + self._failed_count,
+            "tasks": dict(self._browser_tasks),
+            "dom_snapshots": list(self._dom_snapshots),
+            "screenshots": list(self._screenshots),
+        }
+
+    # ------------------------------------------------------------------
+    # Diagnostics
+    # ------------------------------------------------------------------
+
+    @property
+    def passed_count(self) -> int:
+        return self._passed_count
+
+    @property
+    def failed_count(self) -> int:
+        return self._failed_count

mannf/core/agents/browser_executor_agent.py

@@ -0,0 +1,410 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""BrowserExecutorAgent – wraps a Playwright browser session.
+
+Extends :class:`ExecutorAgent` to drive real browser interactions (click,
+fill, navigate, screenshot, DOM snapshot) instead of raw HTTP calls.
+
+Playwright is imported **lazily** inside ``start_browser``; the module can
+therefore be imported without Playwright installed, and tests can mock the
+``async_playwright`` context manager.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from mannf.core.agents.executor_agent import ExecutorAgent
+from mannf.core.browser.dom_snapshot import DOMSnapshot, capture_dom_snapshot
+from mannf.core.messaging.bus import MessageBus
+from mannf.core.messaging.messages import Message, MessageType
+
+logger = logging.getLogger(__name__)
+
+
+class BrowserExecutorAgent(ExecutorAgent):
+    """Executor agent that drives a Playwright browser session.
+
+    Parameters
+    ----------
+    agent_id:
+        Unique identifier.
+    bus:
+        Shared message bus.
+    service_names:
+        Services tracked by the BDI belief state.
+    browser_type:
+        Playwright browser family: ``"chromium"``, ``"firefox"``, or
+        ``"webkit"``.
+    headless:
+        Run the browser in headless mode (no visible window).
+    viewport_width:
+        Browser viewport width in pixels.
+    viewport_height:
+        Browser viewport height in pixels.
+
+    Notes
+    -----
+    A dummy ``None`` value is passed for the ``sut`` parameter required by
+    :class:`ExecutorAgent`, because this agent targets URLs via Playwright
+    rather than a :class:`~mannf.core.distributed.system_under_test.SystemUnderTest`.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        bus: MessageBus,
+        service_names: list[str],
+        *,
+        browser_type: str = "chromium",
+        headless: bool = True,
+        viewport_width: int = 1280,
+        viewport_height: int = 720,
+    ) -> None:
+        super().__init__(
+            agent_id=agent_id,
+            bus=bus,
+            service_names=service_names,
+            sut=None,  # type: ignore[arg-type]
+        )
+        self._browser_type = browser_type
+        self._headless = headless
+        self._viewport_width = viewport_width
+        self._viewport_height = viewport_height
+
+        # Playwright state — populated by start_browser()
+        self._playwright: Any = None
+        self._browser: Any = None
+        self._context: Any = None
+        self._page: Any = None
+
+    # ------------------------------------------------------------------
+    # Subscription
+    # ------------------------------------------------------------------
+
+    @property
+    def subscribed_types(self) -> set[MessageType]:
+        return super().subscribed_types | {MessageType.INTERACTION_REQUEST}
+
+    # ------------------------------------------------------------------
+    # Message handling
+    # ------------------------------------------------------------------
+
+    async def _handle_message(self, message: Message) -> None:
+        if message.type == MessageType.INTERACTION_REQUEST:
+            await self._handle_interaction_request(message)
+        else:
+            await super()._handle_message(message)
+
+    async def _handle_interaction_request(self, message: Message) -> None:
+        """Dispatch an ad-hoc interaction request from the bus."""
+        payload: dict[str, Any] = message.payload or {}
+        action = payload.get("action", "")
+        try:
+            result: dict[str, Any]
+            if action == "navigate":
+                result = await self.navigate(payload["url"])
+            elif action == "click":
+                result = await self.click(payload["selector"])
+            elif action == "fill":
+                result = await self.fill(payload["selector"], payload["value"])
+            elif action == "submit_form":
+                result = await self.submit_form(payload.get("form_selector", "form"))
+            else:
+                result = {"error": f"Unknown action: {action!r}"}
+        except Exception as exc:  # noqa: BLE001
+            result = {"error": str(exc), "action": action}
+
+        await self._publish(
+            message.reply(
+                MessageType.INTERACTION_RESULT,
+                payload=result,
+                sender_id=self.agent_id,
+            )
+        )
+
+    # ------------------------------------------------------------------
+    # Browser lifecycle
+    # ------------------------------------------------------------------
+
+    async def start_browser(self) -> None:
+        """Launch Playwright and open a browser context + page.
+
+        Safe to call even if the browser is already running (idempotent).
+        """
+        if self._playwright is not None:
+            return
+
+        from playwright.async_api import async_playwright  # lazy import
+
+        self._playwright = await async_playwright().start()
+        launcher = getattr(self._playwright, self._browser_type)
+        self._browser = await launcher.launch(headless=self._headless)
+        self._context = await self._browser.new_context(
+            viewport={"width": self._viewport_width, "height": self._viewport_height}
+        )
+        self._page = await self._context.new_page()
+        logger.info(
+            "BrowserExecutorAgent %s: browser started (%s, headless=%s)",
+            self.agent_id, self._browser_type, self._headless,
+        )
+
+    async def stop_browser(self) -> None:
+        """Close the browser and Playwright instance.
+
+        Safe to call when no browser is running (idempotent).
+        """
+        if self._playwright is None:
+            return
+
+        try:
+            if self._context is not None:
+                await self._context.close()
+            if self._browser is not None:
+                await self._browser.close()
+            await self._playwright.stop()
+        except Exception:  # noqa: BLE001
+            logger.exception("BrowserExecutorAgent %s: error during stop_browser", self.agent_id)
+        finally:
+            self._page = None
+            self._context = None
+            self._browser = None
+            self._playwright = None
+            logger.info("BrowserExecutorAgent %s: browser stopped", self.agent_id)
+
+    # ------------------------------------------------------------------
+    # Browser actions
+    # ------------------------------------------------------------------
+
+    async def navigate(self, url: str) -> dict[str, Any]:
+        """Navigate to *url* and wait for the page to load.
+
+        Returns
+        -------
+        dict
+            ``{title, url, status}`` — basic page metadata.
+        """
+        try:
+            response = await self._page.goto(url, wait_until="load")
+            title = await self._page.title()
+            return {
+                "title": title,
+                "url": self._page.url,
+                "status": response.status if response else None,
+            }
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("BrowserExecutorAgent %s: navigate error: %s", self.agent_id, exc)
+            return {"error": str(exc), "url": url}
+
+    async def click(self, selector: str) -> dict[str, Any]:
+        """Click the element matched by *selector*.
+
+        Returns
+        -------
+        dict
+            ``{success, url}`` after the click, or ``{success, error}`` on failure.
+        """
+        try:
+            await self._page.click(selector)
+            return {"success": True, "url": self._page.url}
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("BrowserExecutorAgent %s: click error: %s", self.agent_id, exc)
+            return {"success": False, "error": str(exc)}
+
+    async def fill(self, selector: str, value: str) -> dict[str, Any]:
+        """Fill the input field matched by *selector* with *value*.
+
+        Returns
+        -------
+        dict
+            ``{success}`` or ``{success, error}`` on failure.
+        """
+        try:
+            await self._page.fill(selector, value)
+            return {"success": True}
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("BrowserExecutorAgent %s: fill error: %s", self.agent_id, exc)
+            return {"success": False, "error": str(exc)}
+
+    async def submit_form(self, form_selector: str = "form") -> dict[str, Any]:
+        """Submit the form matched by *form_selector*.
+
+        Returns
+        -------
+        dict
+            ``{success, url}`` or ``{success, error}`` on failure.
+        """
+        try:
+            await self._page.evaluate(
+                f'document.querySelector("{form_selector}").submit()'
+            )
+            return {"success": True, "url": self._page.url}
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("BrowserExecutorAgent %s: submit_form error: %s", self.agent_id, exc)
+            return {"success": False, "error": str(exc)}
+
+    async def capture_screenshot(self, full_page: bool = False) -> bytes:
+        """Take a screenshot and publish a :attr:`~MessageType.SCREENSHOT_CAPTURED` message.
+
+        Parameters
+        ----------
+        full_page:
+            When ``True``, capture the full scrollable page instead of just
+            the visible viewport.
+
+        Returns
+        -------
+        bytes
+            Raw PNG image bytes.
+        """
+        png_bytes: bytes = await self._page.screenshot(full_page=full_page)
+        await self._publish(
+            Message(
+                MessageType.SCREENSHOT_CAPTURED,
+                sender_id=self.agent_id,
+                payload={
+                    "agent_id": self.agent_id,
+                    "url": self._page.url,
+                    "size": len(png_bytes),
+                    "full_page": full_page,
+                },
+            )
+        )
+        return png_bytes
+
+    async def capture_dom(self) -> DOMSnapshot:
+        """Capture a DOM snapshot and publish a :attr:`~MessageType.DOM_SNAPSHOT` message.
+
+        Returns
+        -------
+        DOMSnapshot
+            The full page DOM state.
+        """
+        snapshot = await capture_dom_snapshot(self._page)
+        await self._publish(
+            Message(
+                MessageType.DOM_SNAPSHOT,
+                sender_id=self.agent_id,
+                payload={
+                    "agent_id": self.agent_id,
+                    "url": snapshot.url,
+                    "title": snapshot.title,
+                    "timestamp": snapshot.timestamp,
+                    "element_count": len(snapshot.elements),
+                    "interactive_count": len(snapshot.interactive_elements),
+                    "form_count": len(snapshot.forms),
+                },
+            )
+        )
+        return snapshot
+
+    # ------------------------------------------------------------------
+    # Contract execution (override)
+    # ------------------------------------------------------------------
+
+    async def _execute_contract(self, contract: dict[str, Any]) -> None:
+        """Execute a browser-based test contract.
+
+        Expected ``contract`` payload shape::
+
+            {
+                "url": "https://example.com",
+                "steps": [
+                    {"action": "fill", "selector": "#email", "value": "..."},
+                    {"action": "click", "selector": "#submit"},
+                ],
+            }
+        """
+        target_url: str = contract.get("url", contract.get("target", ""))
+        steps: list[dict[str, Any]] = contract.get("steps", [])
+
+        results: list[dict[str, Any]] = []
+        passed = True
+        error_msg: str | None = None
+
+        try:
+            nav_result = await self.navigate(target_url)
+            results.append({"action": "navigate", **nav_result})
+            if "error" in nav_result:
+                passed = False
+                error_msg = nav_result["error"]
+
+            if passed:
+                for step in steps:
+                    action = step.get("action", "")
+                    step_result: dict[str, Any]
+
+                    if action == "click":
+                        step_result = await self.click(step["selector"])
+                    elif action == "fill":
+                        step_result = await self.fill(step["selector"], step["value"])
+                    elif action == "submit_form":
+                        step_result = await self.submit_form(
+                            step.get("form_selector", "form")
+                        )
+                    else:
+                        step_result = {"error": f"Unknown action: {action!r}"}
+
+                    step_result["action"] = action
+                    results.append(step_result)
+
+                    # Capture DOM snapshot after each step
+                    try:
+                        await self.capture_dom()
+                    except Exception:  # noqa: BLE001
+                        logger.debug(
+                            "BrowserExecutorAgent %s: DOM capture skipped after step %r",
+                            self.agent_id, action,
+                        )
+
+                    if not step_result.get("success", True) or "error" in step_result:
+                        passed = False
+                        error_msg = step_result.get("error")
+                        break
+
+            # Capture final screenshot
+            try:
+                await self.capture_screenshot()
+            except Exception:  # noqa: BLE001
+                logger.debug(
+                    "BrowserExecutorAgent %s: screenshot skipped at contract end",
+                    self.agent_id,
+                )
+
+        except Exception as exc:  # noqa: BLE001
+            passed = False
+            error_msg = str(exc)
+            logger.warning(
+                "BrowserExecutorAgent %s: contract execution error: %s",
+                self.agent_id, exc,
+            )
+
+        # Update BDI beliefs
+        evidence = 0.0 if passed else 1.0
+        target_service = contract.get("target", target_url)
+        self._update_belief_from_result(target_service, evidence)
+
+        # Publish interaction result
+        await self._publish(
+            Message(
+                MessageType.INTERACTION_RESULT,
+                sender_id=self.agent_id,
+                payload={
+                    "task_id": contract.get("task_id"),
+                    "url": target_url,
+                    "passed": passed,
+                    "error": error_msg,
+                    "steps": results,
+                    "executor_id": self.agent_id,
+                },
+                correlation_id=contract.get("task_id"),
+            )
+        )
+        logger.debug(
+            "BrowserExecutorAgent %s: contract %s → %s",
+            self.agent_id, target_url, "PASS" if passed else "FAIL",
+        )