docs: added docs to util functions

Author: naasanov

backend/test/conftest.py

@@ -56,6 +56,8 @@ async def test_session():
 async def create_test_client(
     test_session: AsyncSession,
 ) -> CreateClientCallable:
+    """Fixture to create test HTTP clients with different authentication roles."""
+
     async def _create_test_client(role: StringRole | None):
         async def override_get_session():
             yield test_session
@@ -136,14 +138,12 @@ def mock_gmaps() -> MagicMock:
 
 @pytest.fixture()
 def mock_place():
-    """Mock for Google Maps places.place API."""
     with patch("src.modules.location.location_service.places.place") as mock:
         yield mock
 
 
 @pytest.fixture()
 def mock_autocomplete():
-    """Mock for Google Maps places.places_autocomplete API."""
     with patch("src.modules.location.location_service.places.places_autocomplete") as mock:
         yield mock
 

backend/test/utils/http/assertions.py

@@ -1,3 +1,5 @@
+"""Utility functions for asserting HTTP responses in tests."""
+
 from typing import Any, Optional, TypeVar, get_args, get_origin, overload
 
 from fastapi import HTTPException
@@ -26,6 +28,19 @@ def assert_res_success(
     *,
     status: Optional[int] = 200,
 ) -> T | list[T]:
+    """
+    Assert that a response is a successful response. Validates and converts to the expected model type.
+
+    Args:
+        res: The HTTP response to check
+        ExpectedModel: The expected Pydantic model type (or list of model type) of the response data
+        status: Optional expected HTTP status code (default 200)
+
+    Returns:
+        The response data converted to the expected model type
+        e.g. `assert_res_success(res, User)` returns `User`
+             `assert_res_success(res, [User])` returns `list[User]`
+    """
     if status is not None:
         assert res.status_code == status, (
             f"Expected status {status}, got {res.status_code}. Response: {res.text}"
@@ -44,14 +59,17 @@ def assert_res_success(
     assert data is not None, "Expected response data but got None"
 
     model_origin = get_origin(ExpectedModel)
+
+    # List model case
     if model_origin is list:
         assert isinstance(data, list), f"Expected list response but got {type(data).__name__}"
 
+        # Get the model type inside the list
         args = get_args(ExpectedModel)
         assert args is not None, "Expected type args for list model but got None"
         assert len(args) > 0, "Expected at least one type arg for list model but got empty args"
-
         inner_model = args[0]
+
         inner_fields = set(inner_model.model_fields.keys())
         for item in data:
             extra = set(item.keys()) - inner_fields
@@ -69,6 +87,16 @@ def assert_res_success(
 
 
 def assert_res_failure(res: Response, expected_error: HTTPException) -> dict[str, Any]:
+    """
+    Assert that a response is a failure response matching the expected HTTPException.
+
+    Args:
+        res: The HTTP response to check
+        expected_error: The expected HTTPException instance representing the error
+
+    Returns:
+        The response data dict containing the error details
+    """
     assert res.status_code == expected_error.status_code, (
         f"Expected status {expected_error.status_code}, got {res.status_code}. Response: {res.text}"
     )

backend/test/utils/http/test_templates.py

@@ -10,6 +10,19 @@
 
 
 def generate_auth_required_tests(*params: tuple[set[StringRole], str, str, dict | None]):
+    """Generate authentication and authorization tests for HTTP endpoints.
+
+    Ensures that allowed roles can access the endpoint, disallowed roles are forbidden,
+    and unauthenticated requests are unauthorized.
+
+    Args:
+        params: A variable number of tuples, each containing:
+            - allowed_roles (set[StringRole]): Roles allowed to access the endpoint.
+            - method (str): The HTTP method (e.g., "GET", "POST").
+            - path (str): The endpoint path (e.g., "/api/resource").
+            - body (dict | None): The request body for methods like POST or PUT.
+    """
+
     @pytest.mark.parametrize("allowed_roles, method, path, body", params)
     @pytest.mark.asyncio
     async def test_authentication(

backend/test/utils/resource_test_utils.py

@@ -11,7 +11,9 @@ class EntityProtocl[DtoModel: BaseModel](Protocol):
     """Protocol for entities with model translation methods for automatic conversions"""
 
     @classmethod
-    def from_model(cls, data: Any, /, *args: Any, **kwargs: Any) -> Self: ...
+    def from_model(cls, data: Any, /, *args: Any, **kwargs: Any) -> Self:
+        # Extra args to allow for entities with required fields not in the model
+        ...
 
     def to_model(self) -> DtoModel: ...