Improve APIResponse JSON parse diagnostics

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

Author: cursoragent

hyperbrowser/transport/base.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping as MappingABC
 from abc import ABC, abstractmethod
 from typing import Generic, Mapping, Optional, Type, TypeVar, Union
 
@@ -16,12 +17,26 @@ def __init__(self, data: Optional[Union[dict, T]] = None, status_code: int = 200
         self.status_code = status_code
 
     @classmethod
-    def from_json(cls, json_data: dict, model: Type[T]) -> "APIResponse[T]":
+    def from_json(
+        cls, json_data: Mapping[str, object], model: Type[T]
+    ) -> "APIResponse[T]":
         """Create an APIResponse from JSON data with a specific model."""
+        model_name = getattr(model, "__name__", "response model")
+        if not isinstance(json_data, MappingABC):
+            actual_type_name = type(json_data).__name__
+            raise HyperbrowserError(
+                f"Failed to parse response data for {model_name}: "
+                f"expected a mapping but received {actual_type_name}"
+            )
         try:
             return cls(data=model(**json_data))
-        except Exception as e:
-            raise HyperbrowserError("Failed to parse response data", original_error=e)
+        except HyperbrowserError:
+            raise
+        except Exception as exc:
+            raise HyperbrowserError(
+                f"Failed to parse response data for {model_name}",
+                original_error=exc,
+            ) from exc
 
     @classmethod
     def from_status(cls, status_code: int) -> "APIResponse[None]":

tests/test_transport_base.py

@@ -0,0 +1,60 @@
+from typing import cast
+
+import pytest
+from pydantic import BaseModel
+
+from hyperbrowser.exceptions import HyperbrowserError
+from hyperbrowser.transport.base import APIResponse
+
+
+class _SampleResponseModel(BaseModel):
+    name: str
+    retries: int = 0
+
+
+class _RaisesHyperbrowserModel:
+    def __init__(self, **kwargs):
+        _ = kwargs
+        raise HyperbrowserError("model validation failed")
+
+
+def test_api_response_from_json_parses_model_data() -> None:
+    response = APIResponse.from_json(
+        {"name": "job-1", "retries": 2}, _SampleResponseModel
+    )
+
+    assert isinstance(response.data, _SampleResponseModel)
+    assert response.status_code == 200
+    assert response.data.name == "job-1"
+    assert response.data.retries == 2
+
+
+def test_api_response_from_json_rejects_non_mapping_inputs() -> None:
+    with pytest.raises(
+        HyperbrowserError,
+        match=(
+            "Failed to parse response data for _SampleResponseModel: "
+            "expected a mapping but received list"
+        ),
+    ):
+        APIResponse.from_json(
+            cast("dict[str, object]", ["not-a-mapping"]),
+            _SampleResponseModel,
+        )
+
+
+def test_api_response_from_json_wraps_non_hyperbrowser_errors() -> None:
+    with pytest.raises(
+        HyperbrowserError,
+        match="Failed to parse response data for _SampleResponseModel",
+    ) as exc_info:
+        APIResponse.from_json({"retries": 1}, _SampleResponseModel)
+
+    assert exc_info.value.original_error is not None
+
+
+def test_api_response_from_json_preserves_hyperbrowser_errors() -> None:
+    with pytest.raises(HyperbrowserError, match="model validation failed") as exc_info:
+        APIResponse.from_json({}, _RaisesHyperbrowserModel)
+
+    assert exc_info.value.original_error is None