Phase 5: BrowserProtocol PageProtocl for mocking mor unit tests

Author: SentienceDEV

sentience/action_executor.py

@@ -24,7 +24,12 @@ class ActionExecutor:
     - Handle action parsing errors consistently
     """
 
-    def __init__(self, browser: Union[SentienceBrowser, AsyncSentienceBrowser, BrowserProtocol, AsyncBrowserProtocol]):
+    def __init__(
+        self,
+        browser: (
+            SentienceBrowser | AsyncSentienceBrowser | BrowserProtocol | AsyncBrowserProtocol
+        ),
+    ):
         """
         Initialize action executor.
 

sentience/agent.py

@@ -15,7 +15,6 @@
 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,
@@ -26,6 +25,7 @@
     SnapshotOptions,
     TokenStats,
 )
+from .protocols import AsyncBrowserProtocol, BrowserProtocol
 from .snapshot import snapshot, snapshot_async
 from .trace_event_builder import TraceEventBuilder
 
@@ -59,7 +59,7 @@ class SentienceAgent(BaseAgent):
 
     def __init__(
         self,
-        browser: Union[SentienceBrowser, BrowserProtocol],
+        browser: SentienceBrowser | BrowserProtocol,
         llm: LLMProvider,
         default_snapshot_limit: int = 50,
         verbose: bool = True,

sentience/conversational_agent.py

@@ -5,15 +5,13 @@
 
 import json
 import time
-from typing import Any
-
-from typing import Union
+from typing import Any, 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 .protocols import BrowserProtocol
 from .snapshot import snapshot
 
 
@@ -33,7 +31,10 @@ class ConversationalAgent:
     """
 
     def __init__(
-        self, browser: Union[SentienceBrowser, BrowserProtocol], llm: LLMProvider, verbose: bool = True
+        self,
+        browser: SentienceBrowser | BrowserProtocol,
+        llm: LLMProvider,
+        verbose: bool = True,
     ):
         """
         Initialize conversational agent

sentience/protocols.py

@@ -42,7 +42,7 @@ def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
         """
         ...
 
-    def goto(self, url: str, **kwargs: Any) -> Optional[Any]:
+    def goto(self, url: str, **kwargs: Any) -> Any | None:
         """
         Navigate to a URL.
 
@@ -64,7 +64,7 @@ def wait_for_timeout(self, timeout: int) -> None:
         """
         ...
 
-    def wait_for_load_state(self, state: str = "load", timeout: Optional[int] = None) -> None:
+    def wait_for_load_state(self, state: str = "load", timeout: int | None = None) -> None:
         """
         Wait for page load state.
 
@@ -89,7 +89,7 @@ class BrowserProtocol(Protocol):
     """
 
     @property
-    def page(self) -> Optional[PageProtocol]:
+    def page(self) -> PageProtocol | None:
         """
         Current Playwright Page object.
 
@@ -102,7 +102,7 @@ def start(self) -> None:
         """Start the browser session."""
         ...
 
-    def close(self, output_path: Optional[str] = None) -> Optional[str]:
+    def close(self, output_path: str | None = None) -> str | None:
         """
         Close the browser session.
 
@@ -151,7 +151,7 @@ async def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
         """
         ...
 
-    async def goto(self, url: str, **kwargs: Any) -> Optional[Any]:
+    async def goto(self, url: str, **kwargs: Any) -> Any | None:
         """
         Navigate to a URL (async).
 
@@ -173,9 +173,7 @@ async def wait_for_timeout(self, timeout: int) -> None:
         """
         ...
 
-    async def wait_for_load_state(
-        self, state: str = "load", timeout: Optional[int] = None
-    ) -> None:
+    async def wait_for_load_state(self, state: str = "load", timeout: int | None = None) -> None:
         """
         Wait for page load state (async).
 
@@ -195,7 +193,7 @@ class AsyncBrowserProtocol(Protocol):
     """
 
     @property
-    def page(self) -> Optional[AsyncPageProtocol]:
+    def page(self) -> AsyncPageProtocol | None:
         """
         Current Playwright AsyncPage object.
 
@@ -208,7 +206,7 @@ async def start(self) -> None:
         """Start the browser session (async)."""
         ...
 
-    async def close(self, output_path: Optional[str] = None) -> Optional[str]:
+    async def close(self, output_path: str | None = None) -> str | None:
         """
         Close the browser session (async).
 
@@ -228,4 +226,3 @@ async def goto(self, url: str) -> None:
             url: URL to navigate to
         """
         ...
-

tests/integration/__init__.py

@@ -4,4 +4,3 @@
 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

@@ -4,4 +4,3 @@
 These tests use mocks and protocols to test logic in isolation,
 without requiring real browser instances.
 """
-

tests/unit/test_agent_errors.py

@@ -59,11 +59,13 @@ def url(self) -> str:
     def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
         # Return proper snapshot structure when snapshot is called
         # The script is a function that calls window.sentience.snapshot(options)
-        if "window.sentience.snapshot" in script or ("snapshot" in script.lower() and "options" in script):
+        if "window.sentience.snapshot" in script or (
+            "snapshot" in script.lower() and "options" in script
+        ):
             # Check if args contain options (for empty snapshot tests)
             options = kwargs.get("options") or (args[0] if args else {})
             limit = options.get("limit", 50) if isinstance(options, dict) else 50
-            
+
             # Return elements based on limit (0 for empty snapshot tests)
             elements = []
             if limit > 0:
@@ -84,7 +86,7 @@ def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
                         "z_index": 10,
                     }
                 ]
-            
+
             # Snapshot model expects 'elements' not 'raw_elements'
             return {
                 "status": "success",
@@ -236,9 +238,7 @@ def test_agent_handles_malformed_llm_response(self):
         llm = MockLLMProvider(responses=["INVALID_RESPONSE_FORMAT"])
         agent = SentienceAgent(browser, llm, verbose=False)
 
-        with (
-            patch("sentience.snapshot.snapshot") as mock_snapshot,
-        ):
+        with (patch("sentience.snapshot.snapshot") as mock_snapshot,):
             mock_snapshot.return_value = create_mock_snapshot()
 
             # Action executor should raise ValueError for invalid format
@@ -365,7 +365,9 @@ def test_agent_handles_unicode_in_actions(self):
             from sentience.models import ActionResult
 
             mock_snapshot.return_value = create_mock_snapshot()
-            mock_type.return_value = ActionResult(success=True, duration_ms=200, outcome="dom_updated")
+            mock_type.return_value = ActionResult(
+                success=True, duration_ms=200, outcome="dom_updated"
+            )
 
             result = agent.act("Type 你好世界", max_retries=0)
             assert result.success is True
@@ -385,7 +387,9 @@ def test_agent_handles_special_characters_in_goal(self):
             from sentience.models import ActionResult
 
             mock_snapshot.return_value = create_mock_snapshot()
-            mock_click.return_value = ActionResult(success=True, duration_ms=150, outcome="dom_updated")
+            mock_click.return_value = ActionResult(
+                success=True, duration_ms=150, outcome="dom_updated"
+            )
 
             # Test with special characters
             result = agent.act('Click the "Submit" button (with quotes)', max_retries=0)
@@ -435,9 +439,10 @@ def test_agent_handles_tracer_errors_gracefully(self):
             from sentience.models import ActionResult
 
             mock_snapshot.return_value = create_mock_snapshot()
-            mock_click.return_value = ActionResult(success=True, duration_ms=150, outcome="dom_updated")
+            mock_click.return_value = ActionResult(
+                success=True, duration_ms=150, outcome="dom_updated"
+            )
 
             # Agent should still complete action despite tracer error
             result = agent.act("Click the button", max_retries=0)
             assert result.success is True
-