Phase 5: BrowserProtocol PageProtocl for mocking mor unit tests

Author: SentienceDEV

sentience/action_executor.py

@@ -6,11 +6,12 @@
 """
 
 import re
-from typing import Any
+from typing import Any, Union
 
 from .actions import click, click_async, press, press_async, type_text, type_text_async
 from .browser import AsyncSentienceBrowser, SentienceBrowser
 from .models import Snapshot
+from .protocols import AsyncBrowserProtocol, BrowserProtocol
 
 
 class ActionExecutor:
@@ -23,15 +24,17 @@ class ActionExecutor:
     - Handle action parsing errors consistently
     """
 
-    def __init__(self, browser: SentienceBrowser | AsyncSentienceBrowser):
+    def __init__(self, browser: Union[SentienceBrowser, AsyncSentienceBrowser, BrowserProtocol, AsyncBrowserProtocol]):
         """
         Initialize action executor.
 
         Args:
-            browser: SentienceBrowser or AsyncSentienceBrowser instance
+            browser: SentienceBrowser, AsyncSentienceBrowser, or protocol-compatible instance
+                    (for testing, can use mock objects that implement BrowserProtocol)
         """
         self.browser = browser
-        self._is_async = isinstance(browser, AsyncSentienceBrowser)
+        # Check if browser is async - support both concrete types and protocols
+        self._is_async = isinstance(browser, (AsyncSentienceBrowser, AsyncBrowserProtocol))
 
     def execute(self, action_str: str, snap: Snapshot) -> dict[str, Any]:
         """

sentience/agent.py

@@ -6,7 +6,7 @@
 import asyncio
 import hashlib
 import time
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 from .action_executor import ActionExecutor
 from .agent_config import AgentConfig
@@ -15,6 +15,7 @@
 from .element_filter import ElementFilter
 from .llm_interaction_handler import LLMInteractionHandler
 from .llm_provider import LLMProvider, LLMResponse
+from .protocols import AsyncBrowserProtocol, BrowserProtocol
 from .models import (
     ActionHistory,
     ActionTokenUsage,
@@ -58,7 +59,7 @@ class SentienceAgent(BaseAgent):
 
     def __init__(
         self,
-        browser: SentienceBrowser,
+        browser: Union[SentienceBrowser, BrowserProtocol],
         llm: LLMProvider,
         default_snapshot_limit: int = 50,
         verbose: bool = True,
@@ -69,7 +70,8 @@ def __init__(
         Initialize Sentience Agent
 
         Args:
-            browser: SentienceBrowser instance
+            browser: SentienceBrowser instance or BrowserProtocol-compatible object
+                    (for testing, can use mock objects that implement BrowserProtocol)
             llm: LLM provider (OpenAIProvider, AnthropicProvider, etc.)
             default_snapshot_limit: Default maximum elements to include in context (default: 50)
             verbose: Print execution logs (default: True)

sentience/conversational_agent.py

@@ -7,9 +7,12 @@
 import time
 from typing import Any
 
+from typing import Union
+
 from .agent import SentienceAgent
 from .browser import SentienceBrowser
 from .llm_provider import LLMProvider
+from .protocols import BrowserProtocol
 from .models import ExtractionResult, Snapshot, SnapshotOptions, StepExecutionResult
 from .snapshot import snapshot
 
@@ -29,12 +32,15 @@ class ConversationalAgent:
          The top result is from amazon.com selling the Apple Magic Mouse 2 for $79."
     """
 
-    def __init__(self, browser: SentienceBrowser, llm: LLMProvider, verbose: bool = True):
+    def __init__(
+        self, browser: Union[SentienceBrowser, BrowserProtocol], llm: LLMProvider, verbose: bool = True
+    ):
         """
         Initialize conversational agent
 
         Args:
-            browser: SentienceBrowser instance
+            browser: SentienceBrowser instance or BrowserProtocol-compatible object
+                    (for testing, can use mock objects that implement BrowserProtocol)
             llm: LLM provider (OpenAI, Anthropic, LocalLLM, etc.)
             verbose: Print step-by-step execution logs (default: True)
         """

sentience/element_filter.py

@@ -65,7 +65,7 @@ def filter_by_importance(
     def filter_by_goal(
         snapshot: Snapshot,
         goal: str | None,
-        max_elements: int = 50,
+        max_elements: int = 100,
     ) -> list[Element]:
         """
         Filter elements from snapshot based on goal context.

sentience/protocols.py

@@ -0,0 +1,231 @@
+"""
+Protocol definitions for testability and dependency injection.
+
+These protocols define the minimal interface required by agent classes,
+enabling better testability through mocking while maintaining type safety.
+"""
+
+from typing import TYPE_CHECKING, Any, Optional, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page as AsyncPage
+    from playwright.sync_api import Page
+
+    from .models import Snapshot
+
+
+@runtime_checkable
+class PageProtocol(Protocol):
+    """
+    Protocol for Playwright Page operations used by agents.
+
+    This protocol defines the minimal interface required from Playwright's Page object.
+    Agents use this interface to interact with the browser page.
+    """
+
+    @property
+    def url(self) -> str:
+        """Current page URL."""
+        ...
+
+    def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
+        """
+        Evaluate JavaScript in the page context.
+
+        Args:
+            script: JavaScript code to evaluate
+            *args: Arguments to pass to the script
+            **kwargs: Keyword arguments to pass to the script
+
+        Returns:
+            Result of the JavaScript evaluation
+        """
+        ...
+
+    def goto(self, url: str, **kwargs: Any) -> Optional[Any]:
+        """
+        Navigate to a URL.
+
+        Args:
+            url: URL to navigate to
+            **kwargs: Additional navigation options
+
+        Returns:
+            Response object or None
+        """
+        ...
+
+    def wait_for_timeout(self, timeout: int) -> None:
+        """
+        Wait for a specified timeout.
+
+        Args:
+            timeout: Timeout in milliseconds
+        """
+        ...
+
+    def wait_for_load_state(self, state: str = "load", timeout: Optional[int] = None) -> None:
+        """
+        Wait for page load state.
+
+        Args:
+            state: Load state to wait for (e.g., "load", "domcontentloaded", "networkidle")
+            timeout: Optional timeout in milliseconds
+        """
+        ...
+
+
+@runtime_checkable
+class BrowserProtocol(Protocol):
+    """
+    Protocol for browser operations used by agents.
+
+    This protocol defines the minimal interface required from SentienceBrowser.
+    Agents use this interface to interact with the browser and take snapshots.
+
+    Note: SentienceBrowser naturally implements this protocol, so no changes
+    are required to existing code. This protocol enables better testability
+    through mocking.
+    """
+
+    @property
+    def page(self) -> Optional[PageProtocol]:
+        """
+        Current Playwright Page object.
+
+        Returns:
+            Page object if browser is started, None otherwise
+        """
+        ...
+
+    def start(self) -> None:
+        """Start the browser session."""
+        ...
+
+    def close(self, output_path: Optional[str] = None) -> Optional[str]:
+        """
+        Close the browser session.
+
+        Args:
+            output_path: Optional path to save browser state/output
+
+        Returns:
+            Path to saved output or None
+        """
+        ...
+
+    def goto(self, url: str) -> None:
+        """
+        Navigate to a URL.
+
+        Args:
+            url: URL to navigate to
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncPageProtocol(Protocol):
+    """
+    Protocol for async Playwright Page operations.
+
+    Similar to PageProtocol but for async operations.
+    """
+
+    @property
+    def url(self) -> str:
+        """Current page URL."""
+        ...
+
+    async def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
+        """
+        Evaluate JavaScript in the page context (async).
+
+        Args:
+            script: JavaScript code to evaluate
+            *args: Arguments to pass to the script
+            **kwargs: Keyword arguments to pass to the script
+
+        Returns:
+            Result of the JavaScript evaluation
+        """
+        ...
+
+    async def goto(self, url: str, **kwargs: Any) -> Optional[Any]:
+        """
+        Navigate to a URL (async).
+
+        Args:
+            url: URL to navigate to
+            **kwargs: Additional navigation options
+
+        Returns:
+            Response object or None
+        """
+        ...
+
+    async def wait_for_timeout(self, timeout: int) -> None:
+        """
+        Wait for a specified timeout (async).
+
+        Args:
+            timeout: Timeout in milliseconds
+        """
+        ...
+
+    async def wait_for_load_state(
+        self, state: str = "load", timeout: Optional[int] = None
+    ) -> None:
+        """
+        Wait for page load state (async).
+
+        Args:
+            state: Load state to wait for (e.g., "load", "domcontentloaded", "networkidle")
+            timeout: Optional timeout in milliseconds
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncBrowserProtocol(Protocol):
+    """
+    Protocol for async browser operations.
+
+    Similar to BrowserProtocol but for async operations.
+    """
+
+    @property
+    def page(self) -> Optional[AsyncPageProtocol]:
+        """
+        Current Playwright AsyncPage object.
+
+        Returns:
+            AsyncPage object if browser is started, None otherwise
+        """
+        ...
+
+    async def start(self) -> None:
+        """Start the browser session (async)."""
+        ...
+
+    async def close(self, output_path: Optional[str] = None) -> Optional[str]:
+        """
+        Close the browser session (async).
+
+        Args:
+            output_path: Optional path to save browser state/output
+
+        Returns:
+            Path to saved output or None
+        """
+        ...
+
+    async def goto(self, url: str) -> None:
+        """
+        Navigate to a URL (async).
+
+        Args:
+            url: URL to navigate to
+        """
+        ...
+

tests/integration/__init__.py

@@ -0,0 +1,7 @@
+"""
+Integration tests for Sentience SDK.
+
+These tests use real browser instances to test end-to-end functionality
+and catch real-world bugs that mocks might miss.
+"""
+

tests/unit/__init__.py

@@ -0,0 +1,7 @@
+"""
+Unit tests for Sentience SDK.
+
+These tests use mocks and protocols to test logic in isolation,
+without requiring real browser instances.
+"""
+