socialseed-e2e 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

socialseed_e2e/core/base_page.py

@@ -8,8 +8,7 @@ rate limiting, and comprehensive request/response logging.
 import json
 import logging
 import time
-from dataclasses import dataclass
-from functools import wraps
+from dataclasses import dataclass, field
 from typing import Any, Callable, Dict, List, Optional, Type, Union
 
 from playwright.sync_api import APIRequestContext, APIResponse, Playwright
@@ -29,17 +28,18 @@ class RetryConfig:
         max_retries: Maximum number of retry attempts (default: 3)
         backoff_factor: Exponential backoff multiplier (default: 1.0)
         max_backoff: Maximum backoff time in seconds (default: 60)
-        retry_on: List of HTTP status codes to retry on (default: [502, 503, 504])
+        retry_on: List of HTTP status codes to retry on (default: [502, 503, 504, 429])
         retry_exceptions: List of exception types to retry on
     """
 
     max_retries: int = 3
     backoff_factor: float = 1.0
     max_backoff: float = 60.0
-    retry_on: List[int] = None
-    retry_exceptions: List[Type[Exception]] = None
+    retry_on: Optional[List[int]] = None
+    retry_exceptions: Optional[List[Type[Exception]]] = None
 
     def __post_init__(self):
+        """Initialize default retry configuration values."""
         if self.retry_on is None:
             self.retry_on = [502, 503, 504, 429]  # Include 429 (rate limit)
         if self.retry_exceptions is None:
@@ -71,7 +71,7 @@ class RequestLog:
         method: HTTP method
         url: Full request URL
         headers: Request headers (may be filtered)
-        body: Request body
+        body: Request body (JSON string)
         timestamp: When the request was made
         duration_ms: Request duration in milliseconds
         status: Response status code
@@ -92,6 +92,25 @@ class RequestLog:
     error: Optional[str] = None
 
 
+@dataclass
+class ServiceHealth:
+    """Service health status.
+
+    Attributes:
+        healthy: Whether the service is healthy
+        status_code: HTTP status code from health check
+        response_time_ms: Response time in milliseconds
+        message: Health check message
+        timestamp: When the check was performed
+    """
+
+    healthy: bool
+    status_code: Optional[int] = None
+    response_time_ms: float = 0.0
+    message: str = ""
+    timestamp: float = field(default_factory=time.time)
+
+
 class BasePageError(Exception):
     """Enhanced exception with request context."""
 
@@ -104,6 +123,7 @@ class BasePageError(Exception):
         response_text: Optional[str] = None,
         request_log: Optional[RequestLog] = None,
     ):
+        """Initialize exception with request context."""
         super().__init__(message)
         self.url = url
         self.method = method
@@ -112,6 +132,7 @@ class BasePageError(Exception):
         self.request_log = request_log
 
     def __str__(self) -> str:
+        """Return formatted error message with context."""
         parts = [super().__str__()]
         if self.method and self.url:
             parts.append(f"Request: {self.method} {self.url}")
@@ -137,6 +158,7 @@ class BasePage:
     - Request timing and performance metrics
     - Enhanced error messages with full context
     - Helper methods for common assertions
+    - Service health checking
 
     Example:
         >>> page = BasePage("https://api.example.com")
@@ -179,6 +201,7 @@ class BasePage:
         rate_limit_config: Optional[RateLimitConfig] = None,
         enable_request_logging: bool = True,
         max_log_body_size: int = 10000,
+        health_endpoint: str = "/actuator/health",
     ) -> None:
         """Initialize the BasePage.
 
@@ -190,6 +213,7 @@ class BasePage:
             rate_limit_config: Configuration for rate limiting (default: disabled)
             enable_request_logging: Whether to log requests and responses
             max_log_body_size: Maximum size for logged bodies (truncated if larger)
+            health_endpoint: Endpoint for health checks (default: /actuator/health)
         """
         self.base_url: str = base_url.rstrip("/")
         self.playwright_manager: Optional[Any] = None
@@ -199,6 +223,8 @@ class BasePage:
             if default_headers is not None
             else {**DEFAULT_JSON_HEADERS, **DEFAULT_BROWSER_HEADERS}
         )
+        self.headers = self.default_headers  # Alias for easier access in tests
+        self.health_endpoint = health_endpoint
 
         # Initialize Playwright
         if playwright:
@@ -210,7 +236,7 @@ class BasePage:
         self.api_context: Optional[APIRequestContext] = None
 
         # Configuration
-        self.retry_config = retry_config or RetryConfig(max_retries=0)  # Disabled by default
+        self.retry_config = retry_config or RetryConfig(max_retries=0)
         self.rate_limit_config = rate_limit_config or RateLimitConfig(enabled=False)
         self.enable_request_logging = enable_request_logging
         self.max_log_body_size = max_log_body_size
@@ -223,26 +249,29 @@ class BasePage:
         self.request_history: List[RequestLog] = []
         self._max_history_size = 100
 
+        # Response interceptors
+        self._response_interceptors: List[Callable[[APIResponse], None]] = []
+
         logger.info(f"BasePage initialized for {self.base_url}")
 
     @classmethod
     def from_config(
         cls, config: ServiceConfig, playwright: Optional[Playwright] = None, **kwargs
     ) -> "BasePage":
-        """Factory method to create a BasePage from a ServiceConfig object.
+        """Create a BasePage from a ServiceConfig object.
 
         Args:
             config: Service configuration object
             playwright: Optional Playwright instance
             **kwargs: Additional arguments passed to BasePage constructor
-
         Returns:
             Configured BasePage instance
         """
         return cls(
             base_url=config.base_url,
             playwright=playwright,
-            default_headers=config.default_headers or None,
+            default_headers=config.default_headers,
+            health_endpoint=getattr(config, "health_endpoint", "/actuator/health"),
             **kwargs,
         )
 
@@ -253,6 +282,7 @@ class BasePage:
         automatically before making requests if not already set up.
         """
         if not self.api_context:
+            assert self.playwright is not None
             self.api_context = self.playwright.request.new_context()
             logger.debug("API context initialized")
 
@@ -280,7 +310,7 @@ class BasePage:
             self.setup()
 
     def _prepare_headers(self, headers: Optional[Dict[str, str]]) -> Dict[str, str]:
-        """Combine default headers with request-specific headers.
+        """Combine active headers with request-specific headers.
 
         Args:
             headers: Request-specific headers to merge with defaults
@@ -288,7 +318,7 @@ class BasePage:
         Returns:
             Merged headers dictionary
         """
-        request_headers = self.default_headers.copy()
+        request_headers = self.headers.copy()
         if headers:
             request_headers.update(headers)
         return request_headers
@@ -339,7 +369,7 @@ class BasePage:
             Sleep time in seconds
         """
         backoff = self.retry_config.backoff_factor * (2**attempt)
-        return min(backoff, self.retry_config.max_backoff)
+        return float(min(backoff, self.retry_config.max_backoff))
 
     def _should_retry(
         self, response: Optional[APIResponse], exception: Optional[Exception]
@@ -359,11 +389,12 @@ class BasePage:
         # Check if exception type is in retry list
         if exception:
             return any(
-                isinstance(exception, exc_type) for exc_type in self.retry_config.retry_exceptions
+                isinstance(exception, exc_type)
+                for exc_type in (self.retry_config.retry_exceptions or [])
             )
 
         # Check if status code is in retry list
-        if response and response.status in self.retry_config.retry_on:
+        if response and response.status in (self.retry_config.retry_on or []):
             return True
 
         return False
@@ -409,6 +440,24 @@ class BasePage:
             )
         return body
 
+    def _serialize_body(self, data: Any) -> Optional[str]:
+        """Serialize request body for logging.
+
+        Args:
+            data: The data to serialize (dict, list, or string)
+
+        Returns:
+            JSON string representation or None
+        """
+        if data is None:
+            return None
+        if isinstance(data, str):
+            return data
+        try:
+            return json.dumps(data, indent=2)
+        except (TypeError, ValueError):
+            return str(data)
+
     def _make_request(self, method: str, endpoint: str, **kwargs) -> APIResponse:
         """Make an HTTP request with retry logic and logging.
 
@@ -422,6 +471,10 @@ class BasePage:
             method: HTTP method (GET, POST, PUT, DELETE, PATCH)
             endpoint: API endpoint (e.g., "/users/123")
             **kwargs: Additional arguments for the Playwright request
+                - data: Form data or dict to send
+                - json: JSON payload (alternative to data)
+                - headers: Request-specific headers
+                - params: Query parameters (GET only)
 
         Returns:
             APIResponse object
@@ -430,18 +483,21 @@ class BasePage:
             BasePageError: If the request fails after all retries
         """
         self._ensure_setup()
+        assert self.api_context is not None
         self._apply_rate_limit()
 
         full_url = f"{self.base_url}{endpoint}"
-        last_exception: Optional[Exception] = None
         last_response: Optional[APIResponse] = None
 
+        # Prepare body - handle both 'data' and 'json' parameters
+        request_body = kwargs.get("json") or kwargs.get("data")
+
         # Prepare request log
         request_log = RequestLog(
             method=method,
             url=full_url,
             headers=self._prepare_headers(kwargs.get("headers")),
-            body=self._truncate_body(str(kwargs.get("data") or kwargs.get("json"))),
+            body=self._truncate_body(self._serialize_body(request_body)),
             timestamp=time.time(),
         )
 
@@ -452,25 +508,48 @@ class BasePage:
                 # Make the request
                 if method == "GET":
                     last_response = self.api_context.get(
-                        full_url, headers=request_log.headers, params=kwargs.get("params")
+                        full_url,
+                        headers=request_log.headers,
+                        params=kwargs.get("params"),
                     )
                 elif method == "POST":
                     last_response = self.api_context.post(
-                        full_url, data=kwargs.get("data"), headers=request_log.headers
+                        full_url, data=request_body, headers=request_log.headers
                     )
                 elif method == "PUT":
                     last_response = self.api_context.put(
-                        full_url, data=kwargs.get("data"), headers=request_log.headers
+                        full_url, data=request_body, headers=request_log.headers
                     )
                 elif method == "DELETE":
-                    last_response = self.api_context.delete(full_url, headers=request_log.headers)
+                    # DELETE with body support
+                    if request_body:
+                        # Use fetch with DELETE method for body support
+                        last_response = self.api_context.fetch(
+                            full_url,
+                            method="DELETE",
+                            data=request_body
+                            if isinstance(request_body, str)
+                            else json.dumps(request_body),
+                            headers=request_log.headers,
+                        )
+                    else:
+                        last_response = self.api_context.delete(
+                            full_url, headers=request_log.headers
+                        )
                 elif method == "PATCH":
                     last_response = self.api_context.patch(
-                        full_url, data=kwargs.get("data"), headers=request_log.headers
+                        full_url, data=request_body, headers=request_log.headers
                     )
                 else:
                     raise ValueError(f"Unsupported HTTP method: {method}")
 
+                # Apply response interceptors
+                for interceptor in self._response_interceptors:
+                    try:
+                        interceptor(last_response)
+                    except Exception as e:
+                        logger.warning(f"Response interceptor failed: {e}")
+
                 # Update log with response info
                 request_log.duration_ms = (time.time() - start_time) * 1000
                 request_log.status = last_response.status
@@ -491,7 +570,8 @@ class BasePage:
                 ):
                     backoff = self._calculate_backoff(attempt)
                     logger.warning(
-                        f"Retry {attempt + 1}/{self.retry_config.max_retries} for {method} {endpoint} "
+                        f"Retry {attempt + 1}/{self.retry_config.max_retries} "
+                        f"for {method} {endpoint} "
                         f"(status: {last_response.status}, backoff: {backoff:.2f}s)"
                     )
                     time.sleep(backoff)
@@ -502,14 +582,14 @@ class BasePage:
                 return last_response
 
             except Exception as e:
-                last_exception = e
                 request_log.duration_ms = (time.time() - start_time) * 1000
 
                 # Check if we should retry on exception
                 if attempt < self.retry_config.max_retries and self._should_retry(None, e):
                     backoff = self._calculate_backoff(attempt)
                     logger.warning(
-                        f"Retry {attempt + 1}/{self.retry_config.max_retries} for {method} {endpoint} "
+                        f"Retry {attempt + 1}/{self.retry_config.max_retries} "
+                        f"for {method} {endpoint} "
                         f"(error: {e}, backoff: {backoff:.2f}s)"
                     )
                     time.sleep(backoff)
@@ -554,7 +634,7 @@ class BasePage:
     def post(
         self,
         endpoint: str,
-        data: Optional[Dict[str, Any]] = None,
+        data: Optional[Union[Dict[str, Any], str]] = None,
         json: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
     ) -> APIResponse:
@@ -562,21 +642,20 @@ class BasePage:
 
         Args:
             endpoint: API endpoint (e.g., "/users")
-            data: Form data (use either data or json, not both)
+            data: Form data or dict (use either data or json, not both)
             json: JSON payload (use either data or json, not both)
             headers: Optional request-specific headers
 
         Returns:
             APIResponse object
         """
-        if json:
-            return self._make_request("POST", endpoint, json=json, headers=headers)
-        return self._make_request("POST", endpoint, data=data, headers=headers)
+        body = json if json is not None else data
+        return self._make_request("POST", endpoint, data=body, headers=headers)
 
     def put(
         self,
         endpoint: str,
-        data: Optional[Dict[str, Any]] = None,
+        data: Optional[Union[Dict[str, Any], str]] = None,
         json: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
     ) -> APIResponse:
@@ -584,33 +663,41 @@ class BasePage:
 
         Args:
             endpoint: API endpoint (e.g., "/users/123")
-            data: Form data (use either data or json, not both)
+            data: Form data or dict (use either data or json, not both)
             json: JSON payload (use either data or json, not both)
             headers: Optional request-specific headers
 
         Returns:
             APIResponse object
         """
-        if json:
-            return self._make_request("PUT", endpoint, json=json, headers=headers)
-        return self._make_request("PUT", endpoint, data=data, headers=headers)
+        body = json if json is not None else data
+        return self._make_request("PUT", endpoint, data=body, headers=headers)
 
-    def delete(self, endpoint: str, headers: Optional[Dict[str, str]] = None) -> APIResponse:
+    def delete(
+        self,
+        endpoint: str,
+        data: Optional[Union[Dict[str, Any], str]] = None,
+        json: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> APIResponse:
         """Perform a DELETE request.
 
         Args:
             endpoint: API endpoint (e.g., "/users/123")
+            data: Request body as dict or string (for non-standard REST APIs)
+            json: JSON payload (alternative to data)
             headers: Optional request-specific headers
 
         Returns:
             APIResponse object
         """
-        return self._make_request("DELETE", endpoint, headers=headers)
+        body = json if json is not None else data
+        return self._make_request("DELETE", endpoint, data=body, headers=headers)
 
     def patch(
         self,
         endpoint: str,
-        data: Optional[Dict[str, Any]] = None,
+        data: Optional[Union[Dict[str, Any], str]] = None,
         json: Optional[Dict[str, Any]] = None,
         headers: Optional[Dict[str, str]] = None,
     ) -> APIResponse:
@@ -618,18 +705,17 @@ class BasePage:
 
         Args:
             endpoint: API endpoint (e.g., "/users/123")
-            data: Form data (use either data or json, not both)
+            data: Form data or dict (use either data or json, not both)
             json: JSON payload (use either data or json, not both)
             headers: Optional request-specific headers
 
         Returns:
             APIResponse object
         """
-        if json:
-            return self._make_request("PATCH", endpoint, json=json, headers=headers)
-        return self._make_request("PATCH", endpoint, data=data, headers=headers)
+        body = json if json is not None else data
+        return self._make_request("PATCH", endpoint, data=body, headers=headers)
 
-    # Helper methods for assertions
+    # Assertion helpers
 
     def assert_status(
         self,
@@ -725,8 +811,11 @@ class BasePage:
                 if isinstance(value, dict) and k in value:
                     value = value[k]
                 else:
+                    keys_display = list(value.keys()) if isinstance(value, dict) else "N/A"
                     raise BasePageError(
-                        message=f"Key '{key}' not found in response. Available keys: {list(value.keys()) if isinstance(value, dict) else 'N/A'}",
+                        message=(
+                            f"Key '{key}' not found in response. " f"Available keys: {keys_display}"
+                        ),
                         url=response.url,
                         status=response.status,
                     )
@@ -735,7 +824,10 @@ class BasePage:
         return data
 
     def assert_header(
-        self, response: APIResponse, header_name: str, expected_value: Optional[str] = None
+        self,
+        response: APIResponse,
+        header_name: str,
+        expected_value: Optional[str] = None,
     ) -> str:
         """Assert that response contains a specific header.
 
@@ -754,8 +846,9 @@ class BasePage:
         header_lower = header_name.lower()
 
         if header_lower not in headers:
+            available = list(response.headers.keys())
             raise BasePageError(
-                message=f"Header '{header_name}' not found in response. Available headers: {list(response.headers.keys())}",
+                message=f"Header '{header_name}' not found. Available: {available}",
                 url=response.url,
                 status=response.status,
             )
@@ -764,12 +857,103 @@ class BasePage:
 
         if expected_value and value != expected_value:
             raise BasePageError(
-                message=f"Header '{header_name}' has value '{value}', expected '{expected_value}'",
+                message=(
+                    f"Header '{header_name}' has value '{value}', " f"expected '{expected_value}'"
+                ),
                 url=response.url,
                 status=response.status,
             )
 
-        return value
+        return str(value)
+
+    def assert_schema(
+        self,
+        response: APIResponse,
+        schema: Union[Dict[str, Any], type],
+        message: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Assert that response matches a JSON schema or Pydantic model.
+
+        Args:
+            response: The API response to validate
+            schema: JSON schema dict or Pydantic model class
+            message: Optional custom error message
+
+        Returns:
+            The parsed JSON data
+
+        Raises:
+            BasePageError: If validation fails
+        """
+        try:
+            data = response.json()
+        except Exception as e:
+            raise BasePageError(
+                message=f"Failed to parse JSON response: {e}",
+                url=response.url,
+                status=response.status,
+            ) from e
+
+        # Check if schema is a Pydantic model
+        if isinstance(schema, type) and hasattr(schema, "model_validate"):
+            try:
+                schema.model_validate(data)
+            except Exception as e:
+                raise BasePageError(
+                    message=message or f"Response does not match schema: {e}",
+                    url=response.url,
+                    status=response.status,
+                    response_text=str(data)[:200],
+                )
+        else:
+            # JSON schema validation (basic implementation)
+            if isinstance(schema, dict) and "properties" in schema:
+                required = schema.get("required", [])
+                properties = schema.get("properties", {})
+
+                for key in required:
+                    if key not in data:
+                        raise BasePageError(
+                            message=message or f"Required field '{key}' missing from response",
+                            url=response.url,
+                            status=response.status,
+                        )
+
+                for key, prop_schema in properties.items():
+                    if key in data:
+                        expected_type = prop_schema.get("type")
+                        if expected_type and not self._check_type(data[key], expected_type):
+                            raise BasePageError(
+                                message=message
+                                or f"Field '{key}' has wrong type. Expected {expected_type}",
+                                url=response.url,
+                                status=response.status,
+                            )
+
+        return data
+
+    def _check_type(self, value: Any, expected_type: str) -> bool:
+        """Check if a value matches an expected JSON schema type.
+
+        Args:
+            value: The value to check
+            expected_type: Expected type (string, integer, number, boolean, array, object)
+
+        Returns:
+            True if types match
+        """
+        type_map = {
+            "string": str,
+            "integer": int,
+            "number": (int, float),
+            "boolean": bool,
+            "array": list,
+            "object": dict,
+        }
+
+        if expected_type in type_map:
+            return isinstance(value, type_map[expected_type])
+        return True
 
     # Utility methods
 
@@ -817,7 +1001,7 @@ class BasePage:
             }
 
         total_duration = sum(r.duration_ms for r in self.request_history)
-        status_counts = {}
+        status_counts: Dict[int, int] = {}
         successful = 0
         failed = 0
 
@@ -837,3 +1021,138 @@ class BasePage:
             "average_duration_ms": total_duration / len(self.request_history),
             "status_distribution": status_counts,
         }
+
+    def add_response_interceptor(self, interceptor: Callable[[APIResponse], None]) -> None:
+        """Add a response interceptor.
+
+        Interceptors are called after each successful response.
+        They receive the APIResponse object and can be used for:
+        - Logging
+        - Token extraction
+        - Response transformation
+        - Metrics collection
+
+        Args:
+            interceptor: Callable that receives APIResponse
+        """
+        self._response_interceptors.append(interceptor)
+
+    def clear_response_interceptors(self) -> None:
+        """Remove all response interceptors."""
+        self._response_interceptors.clear()
+
+    def check_health(self, timeout: Optional[int] = None) -> ServiceHealth:
+        """Check if the service is healthy.
+
+        Makes a request to the health endpoint and returns status.
+
+        Args:
+            timeout: Request timeout in milliseconds (uses default if not specified)
+
+        Returns:
+            ServiceHealth object with health status
+        """
+        start_time = time.time()
+        try:
+            old_timeout = None
+            if timeout and self.api_context:
+                # Note: Playwright doesn't support per-request timeout easily
+                # This is a simplified implementation
+                pass
+
+            response = self.get(self.health_endpoint)
+            response_time = (time.time() - start_time) * 1000
+
+            is_healthy = 200 <= response.status < 300
+
+            try:
+                body = response.json()
+                message = body.get("status", "OK") if isinstance(body, dict) else "OK"
+            except:
+                message = "OK" if is_healthy else "Unhealthy"
+
+            return ServiceHealth(
+                healthy=is_healthy,
+                status_code=response.status,
+                response_time_ms=response_time,
+                message=message,
+            )
+        except Exception as e:
+            response_time = (time.time() - start_time) * 1000
+            return ServiceHealth(
+                healthy=False,
+                status_code=None,
+                response_time_ms=response_time,
+                message=str(e),
+            )
+
+    def wait_for_healthy(
+        self, timeout: int = 30, interval: float = 1.0, raise_on_timeout: bool = True
+    ) -> bool:
+        """Wait for the service to become healthy.
+
+        Polls the health endpoint until it returns healthy or timeout is reached.
+
+        Args:
+            timeout: Maximum time to wait in seconds
+            interval: Polling interval in seconds
+            raise_on_timeout: Whether to raise exception on timeout
+
+        Returns:
+            True if service became healthy, False if timed out
+
+        Raises:
+            BasePageError: If raise_on_timeout is True and service doesn't become healthy
+        """
+        start_time = time.time()
+        attempts = 0
+
+        while time.time() - start_time < timeout:
+            attempts += 1
+            health = self.check_health()
+
+            if health.healthy:
+                logger.info(f"Service became healthy after {attempts} attempt(s)")
+                return True
+
+            logger.debug(f"Health check failed (attempt {attempts}): {health.message}")
+            time.sleep(interval)
+
+        if raise_on_timeout:
+            raise BasePageError(
+                message=f"Service did not become healthy within {timeout}s",
+                url=f"{self.base_url}{self.health_endpoint}",
+            )
+
+        return False
+
+    @classmethod
+    def wait_for_service(
+        cls,
+        url: str,
+        health_endpoint: str = "/actuator/health",
+        timeout: int = 30,
+        interval: float = 1.0,
+    ) -> bool:
+        """Wait for a service to become healthy without creating a persistent instance.
+
+        This is a class method that creates a temporary instance just for health checking.
+
+        Args:
+            url: Service base URL
+            health_endpoint: Health check endpoint
+            timeout: Maximum wait time in seconds
+            interval: Polling interval
+
+        Returns:
+            True if service became healthy
+
+        Example:
+            >>> BasePage.wait_for_service("http://localhost:8081", timeout=60)
+        """
+        page = cls(base_url=url, health_endpoint=health_endpoint)
+        try:
+            page.setup()
+            return page.wait_for_healthy(timeout=timeout, interval=interval)
+        finally:
+            page.teardown()