Centralize computer-action payload serialization helper

Co-authored-by: Shri Sukhani <shrisukhani@users.noreply.github.com>

Author: cursoragent

CONTRIBUTING.md

@@ -84,6 +84,7 @@ This runs lint, format checks, compile checks, tests, and package build.
   - `tests/test_browser_use_payload_helper_usage.py` (browser-use payload helper usage enforcement),
   - `tests/test_ci_workflow_quality_gates.py` (CI guard-stage + make-target enforcement),
   - `tests/test_computer_action_endpoint_helper_usage.py` (computer-action endpoint-normalization helper usage enforcement),
+  - `tests/test_computer_action_payload_helper_usage.py` (computer-action payload helper usage enforcement),
   - `tests/test_contributing_architecture_guard_listing.py` (`CONTRIBUTING.md` architecture-guard inventory completeness enforcement),
   - `tests/test_core_type_helper_usage.py` (core transport/config/header/file/polling/session/error/parsing manager+tool module enforcement of shared plain-type helper usage),
   - `tests/test_default_serialization_helper_usage.py` (default optional-query serialization helper usage enforcement),

hyperbrowser/client/managers/async_manager/computer_action.py

@@ -1,10 +1,9 @@
-from pydantic import BaseModel
 from typing import Union, List, Optional
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.type_utils import is_plain_string, is_string_subclass_instance
 from ..computer_action_utils import normalize_computer_action_endpoint
+from ..computer_action_payload_utils import build_computer_action_payload
 from ..response_utils import parse_response_model
-from ..serialization_utils import serialize_model_dump_to_dict
 from hyperbrowser.models import (
     SessionDetail,
     ComputerActionParams,
@@ -44,15 +43,7 @@ async def _execute_request(
             session
         )
 
-        if isinstance(params, BaseModel):
-            payload = serialize_model_dump_to_dict(
-                params,
-                error_message="Failed to serialize computer action params",
-                by_alias=True,
-                exclude_none=True,
-            )
-        else:
-            payload = params
+        payload = build_computer_action_payload(params)
 
         response = await self._client.transport.post(
             normalized_computer_action_endpoint,

hyperbrowser/client/managers/computer_action_payload_utils.py

@@ -0,0 +1,16 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+from .serialization_utils import serialize_model_dump_to_dict
+
+
+def build_computer_action_payload(params: Any) -> Any:
+    if isinstance(params, BaseModel):
+        return serialize_model_dump_to_dict(
+            params,
+            error_message="Failed to serialize computer action params",
+            by_alias=True,
+            exclude_none=True,
+        )
+    return params

hyperbrowser/client/managers/sync_manager/computer_action.py

@@ -1,10 +1,9 @@
-from pydantic import BaseModel
 from typing import Union, List, Optional
 from hyperbrowser.exceptions import HyperbrowserError
 from hyperbrowser.type_utils import is_plain_string, is_string_subclass_instance
 from ..computer_action_utils import normalize_computer_action_endpoint
+from ..computer_action_payload_utils import build_computer_action_payload
 from ..response_utils import parse_response_model
-from ..serialization_utils import serialize_model_dump_to_dict
 from hyperbrowser.models import (
     SessionDetail,
     ComputerActionParams,
@@ -44,15 +43,7 @@ def _execute_request(
             session
         )
 
-        if isinstance(params, BaseModel):
-            payload = serialize_model_dump_to_dict(
-                params,
-                error_message="Failed to serialize computer action params",
-                by_alias=True,
-                exclude_none=True,
-            )
-        else:
-            payload = params
+        payload = build_computer_action_payload(params)
 
         response = self._client.transport.post(
             normalized_computer_action_endpoint,

tests/test_architecture_marker_usage.py

@@ -43,6 +43,7 @@
     "tests/test_example_sync_async_parity.py",
     "tests/test_example_run_instructions.py",
     "tests/test_computer_action_endpoint_helper_usage.py",
+    "tests/test_computer_action_payload_helper_usage.py",
     "tests/test_schema_injection_helper_usage.py",
     "tests/test_session_profile_update_helper_usage.py",
     "tests/test_session_upload_helper_usage.py",

tests/test_computer_action_payload_helper_usage.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+import pytest
+
+pytestmark = pytest.mark.architecture
+
+
+MODULES = (
+    "hyperbrowser/client/managers/sync_manager/computer_action.py",
+    "hyperbrowser/client/managers/async_manager/computer_action.py",
+)
+
+
+def test_computer_action_managers_use_shared_payload_helper():
+    for module_path in MODULES:
+        module_text = Path(module_path).read_text(encoding="utf-8")
+        assert "build_computer_action_payload(" in module_text
+        assert "serialize_model_dump_to_dict(" not in module_text

tests/test_computer_action_payload_utils.py

@@ -0,0 +1,74 @@
+from types import MappingProxyType
+
+import pytest
+from pydantic import BaseModel
+from typing import Optional
+
+from hyperbrowser.client.managers.computer_action_payload_utils import (
+    build_computer_action_payload,
+)
+from hyperbrowser.exceptions import HyperbrowserError
+
+
+class _ActionParams(BaseModel):
+    action_type: str
+    return_screenshot: Optional[bool] = None
+
+
+def test_build_computer_action_payload_serializes_pydantic_models():
+    payload = build_computer_action_payload(
+        _ActionParams(action_type="screenshot", return_screenshot=True)
+    )
+
+    assert payload == {"action_type": "screenshot", "return_screenshot": True}
+
+
+def test_build_computer_action_payload_passes_through_non_models():
+    raw_payload = {"foo": "bar"}
+
+    assert build_computer_action_payload(raw_payload) is raw_payload
+
+
+def test_build_computer_action_payload_wraps_runtime_model_dump_errors():
+    class _BrokenParams(BaseModel):
+        def model_dump(self, *args, **kwargs):  # type: ignore[override]
+            _ = args
+            _ = kwargs
+            raise RuntimeError("broken model_dump")
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to serialize computer action params"
+    ) as exc_info:
+        build_computer_action_payload(_BrokenParams())
+
+    assert isinstance(exc_info.value.original_error, RuntimeError)
+
+
+def test_build_computer_action_payload_preserves_hyperbrowser_model_dump_errors():
+    class _BrokenParams(BaseModel):
+        def model_dump(self, *args, **kwargs):  # type: ignore[override]
+            _ = args
+            _ = kwargs
+            raise HyperbrowserError("custom model_dump failure")
+
+    with pytest.raises(
+        HyperbrowserError, match="custom model_dump failure"
+    ) as exc_info:
+        build_computer_action_payload(_BrokenParams())
+
+    assert exc_info.value.original_error is None
+
+
+def test_build_computer_action_payload_rejects_non_dict_model_dump_results():
+    class _BrokenParams(BaseModel):
+        def model_dump(self, *args, **kwargs):  # type: ignore[override]
+            _ = args
+            _ = kwargs
+            return MappingProxyType({"actionType": "screenshot"})
+
+    with pytest.raises(
+        HyperbrowserError, match="Failed to serialize computer action params"
+    ) as exc_info:
+        build_computer_action_payload(_BrokenParams())
+
+    assert exc_info.value.original_error is None

tests/test_core_type_helper_usage.py

@@ -30,6 +30,7 @@
     "hyperbrowser/client/managers/sync_manager/session.py",
     "hyperbrowser/client/managers/async_manager/session.py",
     "hyperbrowser/client/managers/computer_action_utils.py",
+    "hyperbrowser/client/managers/computer_action_payload_utils.py",
     "hyperbrowser/client/managers/extension_create_utils.py",
     "hyperbrowser/client/managers/extract_payload_utils.py",
     "hyperbrowser/client/managers/job_pagination_utils.py",