core-framework 0.12.6__py3-none-any.whl → 0.12.8__py3-none-any.whl

core/testing/assertions.py

@@ -0,0 +1,347 @@
+"""
+Custom assertions for API testing.
+
+Provides helper functions for common test assertions.
+
+Usage:
+    response = await client.get("/users/1")
+    
+    assert_status(response, 200)
+    assert_json_contains(response, {"email": "test@example.com"})
+    assert_error_code(response, "not_found")
+"""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from httpx import Response
+
+
+def assert_status(response: "Response", expected: int, msg: str = "") -> None:
+    """
+    Assert response has expected status code.
+    
+    Args:
+        response: HTTP response
+        expected: Expected status code
+        msg: Optional message
+        
+    Raises:
+        AssertionError: If status doesn't match
+        
+    Example:
+        assert_status(response, 200)
+        assert_status(response, 201, "User should be created")
+    """
+    actual = response.status_code
+    if actual != expected:
+        body = _safe_json(response)
+        error_msg = f"Expected status {expected}, got {actual}. Response: {body}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+
+
+def assert_status_ok(response: "Response", msg: str = "") -> None:
+    """Assert response is 2xx."""
+    if not 200 <= response.status_code < 300:
+        body = _safe_json(response)
+        error_msg = f"Expected 2xx status, got {response.status_code}. Response: {body}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+
+
+def assert_status_error(response: "Response", msg: str = "") -> None:
+    """Assert response is 4xx or 5xx."""
+    if response.status_code < 400:
+        body = _safe_json(response)
+        error_msg = f"Expected error status, got {response.status_code}. Response: {body}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+
+
+def assert_json_contains(
+    response: "Response",
+    expected: dict[str, Any],
+    msg: str = "",
+) -> None:
+    """
+    Assert response JSON contains expected fields.
+    
+    Args:
+        response: HTTP response
+        expected: Dict of expected fields and values
+        msg: Optional message
+        
+    Raises:
+        AssertionError: If fields don't match
+        
+    Example:
+        assert_json_contains(response, {"email": "test@example.com"})
+        assert_json_contains(response, {"status": "active", "role": "admin"})
+    """
+    actual = _safe_json(response)
+    
+    if not isinstance(actual, dict):
+        raise AssertionError(
+            f"Expected JSON object, got {type(actual).__name__}: {actual}"
+        )
+    
+    for key, value in expected.items():
+        if key not in actual:
+            error_msg = f"Missing key '{key}' in response. Response: {actual}"
+            if msg:
+                error_msg = f"{msg}. {error_msg}"
+            raise AssertionError(error_msg)
+        
+        if actual[key] != value:
+            error_msg = (
+                f"Value mismatch for '{key}': expected {value!r}, "
+                f"got {actual[key]!r}. Response: {actual}"
+            )
+            if msg:
+                error_msg = f"{msg}. {error_msg}"
+            raise AssertionError(error_msg)
+
+
+def assert_json_equals(
+    response: "Response",
+    expected: dict[str, Any] | list[Any],
+    msg: str = "",
+) -> None:
+    """
+    Assert response JSON equals expected exactly.
+    
+    Args:
+        response: HTTP response
+        expected: Expected JSON value
+        msg: Optional message
+    """
+    actual = _safe_json(response)
+    
+    if actual != expected:
+        error_msg = f"JSON mismatch. Expected: {expected}. Got: {actual}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+
+
+def assert_json_list(
+    response: "Response",
+    min_length: int = 0,
+    max_length: int | None = None,
+    msg: str = "",
+) -> list[Any]:
+    """
+    Assert response is a JSON list and return it.
+    
+    Args:
+        response: HTTP response
+        min_length: Minimum list length
+        max_length: Maximum list length (None = no limit)
+        msg: Optional message
+        
+    Returns:
+        The response JSON list
+    """
+    actual = _safe_json(response)
+    
+    if not isinstance(actual, list):
+        raise AssertionError(
+            f"Expected JSON list, got {type(actual).__name__}: {actual}"
+        )
+    
+    if len(actual) < min_length:
+        error_msg = f"List too short: expected at least {min_length}, got {len(actual)}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+    
+    if max_length is not None and len(actual) > max_length:
+        error_msg = f"List too long: expected at most {max_length}, got {len(actual)}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+    
+    return actual
+
+
+def assert_error_code(
+    response: "Response",
+    code: str,
+    msg: str = "",
+) -> None:
+    """
+    Assert response contains specific error code.
+    
+    Looks for code in: detail.code, code, error.code
+    
+    Args:
+        response: HTTP response
+        code: Expected error code
+        msg: Optional message
+        
+    Example:
+        assert_error_code(response, "not_found")
+        assert_error_code(response, "validation_error")
+    """
+    actual = _safe_json(response)
+    
+    if not isinstance(actual, dict):
+        raise AssertionError(f"Expected JSON object, got: {actual}")
+    
+    # Try different locations for error code
+    actual_code = (
+        actual.get("code") or
+        (actual.get("detail", {}).get("code") if isinstance(actual.get("detail"), dict) else None) or
+        actual.get("error", {}).get("code") if isinstance(actual.get("error"), dict) else None
+    )
+    
+    if actual_code != code:
+        error_msg = f"Expected error code '{code}', got '{actual_code}'. Response: {actual}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+
+
+def assert_validation_error(
+    response: "Response",
+    field: str | None = None,
+    msg: str = "",
+) -> None:
+    """
+    Assert response is a validation error.
+    
+    Args:
+        response: HTTP response
+        field: Optional field that should have error
+        msg: Optional message
+        
+    Example:
+        assert_validation_error(response)
+        assert_validation_error(response, field="email")
+    """
+    if response.status_code != 422:
+        raise AssertionError(
+            f"Expected 422 validation error, got {response.status_code}. "
+            f"Response: {_safe_json(response)}"
+        )
+    
+    if field is not None:
+        actual = _safe_json(response)
+        
+        # Look for field in various error formats
+        found = False
+        
+        # FastAPI format: detail[].loc
+        detail = actual.get("detail", [])
+        if isinstance(detail, list):
+            for error in detail:
+                loc = error.get("loc", [])
+                if field in loc or (len(loc) > 1 and loc[-1] == field):
+                    found = True
+                    break
+        
+        # Our format: errors[].field
+        errors = actual.get("errors", [])
+        if isinstance(errors, list):
+            for error in errors:
+                if error.get("field") == field:
+                    found = True
+                    break
+        
+        if not found:
+            error_msg = f"Expected validation error for field '{field}'. Response: {actual}"
+            if msg:
+                error_msg = f"{msg}. {error_msg}"
+            raise AssertionError(error_msg)
+
+
+def assert_header(
+    response: "Response",
+    header: str,
+    expected: str | None = None,
+    msg: str = "",
+) -> str | None:
+    """
+    Assert response has header, optionally with specific value.
+    
+    Args:
+        response: HTTP response
+        header: Header name
+        expected: Expected value (None = just check exists)
+        msg: Optional message
+        
+    Returns:
+        Header value
+    """
+    actual = response.headers.get(header)
+    
+    if actual is None:
+        error_msg = f"Missing header '{header}'. Headers: {dict(response.headers)}"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+    
+    if expected is not None and actual != expected:
+        error_msg = f"Header '{header}' mismatch: expected '{expected}', got '{actual}'"
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+    
+    return actual
+
+
+def assert_no_error(response: "Response", msg: str = "") -> None:
+    """
+    Assert response is not an error (2xx status).
+    
+    Provides detailed error message on failure.
+    """
+    if response.status_code >= 400:
+        body = _safe_json(response)
+        error_msg = (
+            f"Request failed with {response.status_code}. "
+            f"Response: {body}"
+        )
+        if msg:
+            error_msg = f"{msg}. {error_msg}"
+        raise AssertionError(error_msg)
+
+
+def assert_created(response: "Response", msg: str = "") -> dict[str, Any]:
+    """
+    Assert response is 201 Created and return JSON body.
+    
+    Returns:
+        Response JSON
+    """
+    assert_status(response, 201, msg)
+    return _safe_json(response)
+
+
+def assert_not_found(response: "Response", msg: str = "") -> None:
+    """Assert response is 404 Not Found."""
+    assert_status(response, 404, msg)
+
+
+def assert_unauthorized(response: "Response", msg: str = "") -> None:
+    """Assert response is 401 Unauthorized."""
+    assert_status(response, 401, msg)
+
+
+def assert_forbidden(response: "Response", msg: str = "") -> None:
+    """Assert response is 403 Forbidden."""
+    assert_status(response, 403, msg)
+
+
+def _safe_json(response: "Response") -> Any:
+    """Safely get JSON from response."""
+    try:
+        return response.json()
+    except Exception:
+        return response.text

core/testing/client.py

@@ -0,0 +1,247 @@
+"""
+HTTP test clients with automatic app setup.
+
+Provides TestClient and AuthenticatedClient for testing core-framework
+applications with minimal boilerplate.
+
+Usage:
+    # Basic client
+    async with TestClient(app) as client:
+        response = await client.get("/health")
+        assert response.status_code == 200
+    
+    # Authenticated client
+    async with AuthenticatedClient(app) as client:
+        response = await client.get("/auth/me")
+        assert response.status_code == 200
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+from contextlib import asynccontextmanager
+
+if TYPE_CHECKING:
+    from httpx import AsyncClient
+    from collections.abc import AsyncGenerator
+
+logger = logging.getLogger("core.testing")
+
+
+class TestClient:
+    """
+    Test client that auto-initializes the test environment.
+    
+    Features:
+    - Automatic database setup with in-memory SQLite
+    - Automatic table creation
+    - Proper cleanup on exit
+    - Full async support
+    
+    Example:
+        async with TestClient(app) as client:
+            response = await client.post(
+                "/api/v1/users",
+                json={"email": "test@example.com"}
+            )
+            assert response.status_code == 201
+    
+    Args:
+        app: FastAPI/Starlette application instance
+        database_url: Database URL for tests (default: in-memory SQLite)
+        base_url: Base URL for requests (default: "http://test")
+        auto_create_tables: Whether to create tables automatically
+    """
+    
+    def __init__(
+        self,
+        app: Any,
+        database_url: str = "sqlite+aiosqlite:///:memory:",
+        base_url: str = "http://test",
+        auto_create_tables: bool = True,
+    ) -> None:
+        self.app = app
+        self.database_url = database_url
+        self.base_url = base_url
+        self.auto_create_tables = auto_create_tables
+        self._client: "AsyncClient | None" = None
+        self._engine: Any = None
+    
+    async def __aenter__(self) -> "AsyncClient":
+        """Setup test environment and return HTTP client."""
+        from httpx import ASGITransport, AsyncClient
+        
+        # Setup database
+        await self._setup_database()
+        
+        # Create HTTP client
+        self._client = AsyncClient(
+            transport=ASGITransport(app=self.app),
+            base_url=self.base_url,
+            follow_redirects=True,
+        )
+        
+        logger.debug(f"TestClient initialized with database: {self.database_url}")
+        return self._client
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Cleanup test environment."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+        
+        await self._teardown_database()
+        logger.debug("TestClient cleaned up")
+    
+    async def _setup_database(self) -> None:
+        """Initialize test database."""
+        from core.testing.database import setup_test_db
+        self._engine = await setup_test_db(
+            self.database_url,
+            create_tables=self.auto_create_tables,
+        )
+    
+    async def _teardown_database(self) -> None:
+        """Cleanup test database."""
+        from core.testing.database import teardown_test_db
+        await teardown_test_db()
+        self._engine = None
+
+
+class AuthenticatedClient(TestClient):
+    """
+    Test client with automatic user registration and authentication.
+    
+    Creates a test user on setup and includes the authentication token
+    in all subsequent requests.
+    
+    Example:
+        async with AuthenticatedClient(app) as client:
+            # Already authenticated!
+            response = await client.get("/api/v1/auth/me")
+            assert response.status_code == 200
+            assert response.json()["email"] == "test@example.com"
+    
+    Args:
+        app: FastAPI/Starlette application instance
+        email: Email for test user (default: "test@example.com")
+        password: Password for test user (default: "TestPass123!")
+        register_url: URL for registration endpoint
+        login_url: URL for login endpoint
+        extra_register_data: Additional data for registration
+        **kwargs: Additional arguments for TestClient
+    """
+    
+    def __init__(
+        self,
+        app: Any,
+        email: str = "test@example.com",
+        password: str = "TestPass123!",
+        register_url: str = "/api/v1/auth/register",
+        login_url: str = "/api/v1/auth/login",
+        extra_register_data: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(app, **kwargs)
+        self.email = email
+        self.password = password
+        self.register_url = register_url
+        self.login_url = login_url
+        self.extra_register_data = extra_register_data or {}
+        self._user_data: dict[str, Any] | None = None
+        self._token: str | None = None
+    
+    @property
+    def user(self) -> dict[str, Any] | None:
+        """Get authenticated user data."""
+        return self._user_data
+    
+    @property
+    def token(self) -> str | None:
+        """Get authentication token."""
+        return self._token
+    
+    async def __aenter__(self) -> "AsyncClient":
+        """Setup, register user, and authenticate."""
+        client = await super().__aenter__()
+        
+        # Register user
+        register_data = {
+            "email": self.email,
+            "password": self.password,
+            **self.extra_register_data,
+        }
+        
+        register_response = await client.post(
+            self.register_url,
+            json=register_data,
+        )
+        
+        if register_response.status_code not in (200, 201):
+            # User might already exist, try login directly
+            logger.debug(f"Registration returned {register_response.status_code}, trying login")
+        
+        # Login
+        login_response = await client.post(
+            self.login_url,
+            json={"email": self.email, "password": self.password},
+        )
+        
+        if login_response.status_code != 200:
+            raise RuntimeError(
+                f"Failed to authenticate test user: {login_response.status_code} "
+                f"{login_response.text}"
+            )
+        
+        # Extract token
+        login_data = login_response.json()
+        self._token = login_data.get("access_token") or login_data.get("token")
+        self._user_data = login_data.get("user", {"email": self.email})
+        
+        if not self._token:
+            raise RuntimeError(f"No token in login response: {login_data}")
+        
+        # Set authorization header
+        client.headers["Authorization"] = f"Bearer {self._token}"
+        
+        logger.debug(f"AuthenticatedClient ready with user: {self.email}")
+        return client
+
+
+@asynccontextmanager
+async def create_test_client(
+    app: Any,
+    **kwargs,
+) -> "AsyncGenerator[AsyncClient, None]":
+    """
+    Context manager to create a test client.
+    
+    Convenience function for creating TestClient.
+    
+    Example:
+        async with create_test_client(app) as client:
+            response = await client.get("/health")
+    """
+    async with TestClient(app, **kwargs) as client:
+        yield client
+
+
+@asynccontextmanager
+async def create_auth_client(
+    app: Any,
+    email: str = "test@example.com",
+    password: str = "TestPass123!",
+    **kwargs,
+) -> "AsyncGenerator[AsyncClient, None]":
+    """
+    Context manager to create an authenticated test client.
+    
+    Convenience function for creating AuthenticatedClient.
+    
+    Example:
+        async with create_auth_client(app) as client:
+            response = await client.get("/auth/me")
+    """
+    async with AuthenticatedClient(app, email=email, password=password, **kwargs) as client:
+        yield client