Add robust session recording response parsing

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

Author: cursoragent

hyperbrowser/client/managers/async_manager/session.py

@@ -4,6 +4,7 @@
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
 from ...file_utils import ensure_existing_file_path
+from ..session_utils import parse_session_recordings_response_data
 from ....models.session import (
     BasicResponse,
     CreateSessionParams,
@@ -89,7 +90,7 @@ async def get_recording(self, id: str) -> List[SessionRecording]:
         response = await self._client.transport.get(
             self._client._build_url(f"/session/{id}/recording"), None, True
         )
-        return [SessionRecording(**recording) for recording in response.data]
+        return parse_session_recordings_response_data(response.data)
 
     async def get_recording_url(self, id: str) -> GetSessionRecordingUrlResponse:
         response = await self._client.transport.get(

hyperbrowser/client/managers/session_utils.py

@@ -0,0 +1,29 @@
+from collections.abc import Mapping
+from typing import Any, List
+
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.models.session import SessionRecording
+
+
+def parse_session_recordings_response_data(response_data: Any) -> List[SessionRecording]:
+    if not isinstance(response_data, list):
+        raise HyperbrowserError(
+            "Expected session recording response to be a list of objects"
+        )
+    parsed_recordings: List[SessionRecording] = []
+    for index, recording in enumerate(response_data):
+        if not isinstance(recording, Mapping):
+            raise HyperbrowserError(
+                "Expected session recording object at index "
+                f"{index} but got {type(recording).__name__}"
+            )
+        try:
+            parsed_recordings.append(SessionRecording(**dict(recording)))
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            raise HyperbrowserError(
+                f"Failed to parse session recording at index {index}",
+                original_error=exc,
+            ) from exc
+    return parsed_recordings

hyperbrowser/client/managers/sync_manager/session.py

@@ -4,6 +4,7 @@
 import warnings
 from hyperbrowser.exceptions import HyperbrowserError
 from ...file_utils import ensure_existing_file_path
+from ..session_utils import parse_session_recordings_response_data
 from ....models.session import (
     BasicResponse,
     CreateSessionParams,
@@ -83,7 +84,7 @@ def get_recording(self, id: str) -> List[SessionRecording]:
         response = self._client.transport.get(
             self._client._build_url(f"/session/{id}/recording"), None, True
         )
-        return [SessionRecording(**recording) for recording in response.data]
+        return parse_session_recordings_response_data(response.data)
 
     def get_recording_url(self, id: str) -> GetSessionRecordingUrlResponse:
         response = self._client.transport.get(

tests/test_session_recording_utils.py

@@ -0,0 +1,183 @@
+import asyncio
+from types import MappingProxyType
+
+import pytest
+
+from hyperbrowser.client.managers.async_manager.session import (
+    SessionManager as AsyncSessionManager,
+)
+from hyperbrowser.client.managers.session_utils import (
+    parse_session_recordings_response_data,
+)
+from hyperbrowser.client.managers.sync_manager.session import (
+    SessionManager as SyncSessionManager,
+)
+from hyperbrowser.exceptions import HyperbrowserError
+
+
+class _FakeResponse:
+    def __init__(self, data):
+        self.data = data
+
+
+class _SyncTransport:
+    def __init__(self, response_data):
+        self._response_data = response_data
+
+    def get(self, url, params=None, follow_redirects=False):
+        _ = params
+        _ = follow_redirects
+        assert url.endswith("/session/session_123/recording")
+        return _FakeResponse(self._response_data)
+
+
+class _AsyncTransport:
+    def __init__(self, response_data):
+        self._response_data = response_data
+
+    async def get(self, url, params=None, follow_redirects=False):
+        _ = params
+        _ = follow_redirects
+        assert url.endswith("/session/session_123/recording")
+        return _FakeResponse(self._response_data)
+
+
+class _FakeClient:
+    def __init__(self, transport):
+        self.transport = transport
+
+    def _build_url(self, path: str) -> str:
+        return f"https://api.hyperbrowser.ai/api{path}"
+
+
+def test_parse_session_recordings_response_data_parses_list_payloads():
+    recordings = parse_session_recordings_response_data(
+        [
+            {
+                "type": 1,
+                "data": {"event": "click"},
+                "timestamp": 123,
+            }
+        ]
+    )
+
+    assert len(recordings) == 1
+    assert recordings[0].type == 1
+    assert recordings[0].timestamp == 123
+
+
+def test_parse_session_recordings_response_data_accepts_mapping_proxy_items():
+    recordings = parse_session_recordings_response_data(
+        [
+            MappingProxyType(
+                {
+                    "type": 1,
+                    "data": {"event": "scroll"},
+                    "timestamp": 321,
+                }
+            )
+        ]
+    )
+
+    assert len(recordings) == 1
+    assert recordings[0].timestamp == 321
+
+
+def test_parse_session_recordings_response_data_rejects_non_list_payloads():
+    with pytest.raises(
+        HyperbrowserError,
+        match="Expected session recording response to be a list of objects",
+    ):
+        parse_session_recordings_response_data({"type": 1})  # type: ignore[arg-type]
+
+
+def test_parse_session_recordings_response_data_rejects_non_mapping_items():
+    with pytest.raises(
+        HyperbrowserError,
+        match="Expected session recording object at index 0 but got str",
+    ):
+        parse_session_recordings_response_data(["invalid-item"])
+
+
+def test_parse_session_recordings_response_data_wraps_invalid_items():
+    with pytest.raises(
+        HyperbrowserError, match="Failed to parse session recording at index 0"
+    ) as exc_info:
+        parse_session_recordings_response_data(
+            [
+                {
+                    "type": 1,
+                    # missing required fields
+                }
+            ]
+        )
+
+    assert exc_info.value.original_error is not None
+
+
+def test_sync_session_manager_get_recording_uses_recording_parser():
+    manager = SyncSessionManager(
+        _FakeClient(
+            _SyncTransport(
+                [
+                    {
+                        "type": 1,
+                        "data": {"event": "click"},
+                        "timestamp": 123,
+                    }
+                ]
+            )
+        )
+    )
+
+    recordings = manager.get_recording("session_123")
+
+    assert len(recordings) == 1
+    assert recordings[0].timestamp == 123
+
+
+def test_async_session_manager_get_recording_uses_recording_parser():
+    manager = AsyncSessionManager(
+        _FakeClient(
+            _AsyncTransport(
+                [
+                    {
+                        "type": 1,
+                        "data": {"event": "click"},
+                        "timestamp": 123,
+                    }
+                ]
+            )
+        )
+    )
+
+    async def run():
+        return await manager.get_recording("session_123")
+
+    recordings = asyncio.run(run())
+
+    assert len(recordings) == 1
+    assert recordings[0].timestamp == 123
+
+
+def test_sync_session_manager_get_recording_rejects_invalid_payload_shapes():
+    manager = SyncSessionManager(_FakeClient(_SyncTransport({"bad": "payload"})))
+
+    with pytest.raises(
+        HyperbrowserError,
+        match="Expected session recording response to be a list of objects",
+    ):
+        manager.get_recording("session_123")
+
+
+def test_async_session_manager_get_recording_rejects_invalid_payload_shapes():
+    manager = AsyncSessionManager(_FakeClient(_AsyncTransport({"bad": "payload"})))
+
+    async def run():
+        with pytest.raises(
+            HyperbrowserError,
+            match="Expected session recording response to be a list of objects",
+        ):
+            await manager.get_recording("session_123")
+
+    asyncio.run(run())