fixturify 0.1.9__py3-none-any.whl

fixturify/http_d/_matcher.py

@@ -0,0 +1,372 @@
+"""Request matching logic for HTTP playback."""
+
+import json
+from typing import Any, Dict, List, Optional, Set, Tuple, TYPE_CHECKING
+from urllib.parse import parse_qs, urlparse
+
+from fixturify.http_d._models import HttpMapping, HttpRequest
+
+if TYPE_CHECKING:
+    from fixturify.http_d._config import HttpTestConfig
+
+
+class RequestMatcher:
+    """
+    Matches incoming HTTP requests against recorded requests.
+
+    Provides configurable matching for method, URL, headers, query parameters,
+    and request body.
+    """
+
+    def __init__(
+        self,
+        config: Optional["HttpTestConfig"] = None,
+        ignore_headers: Optional[List[str]] = None,
+        match_body: bool = True,
+        strict_order: bool = False,
+    ):
+        """
+        Initialize the request matcher.
+
+        Args:
+            config: HttpTestConfig instance with matching settings.
+                   If provided, other parameters are ignored.
+            ignore_headers: Additional headers to ignore during matching.
+                           These are added to the default ignored headers.
+                           (Deprecated: use config instead)
+            match_body: Whether to include body in matching.
+                       (Deprecated: use config instead)
+            strict_order: Whether requests must match in recorded order.
+                         (Deprecated: use config instead)
+        """
+        if config is not None:
+            self.ignore_headers = config.get_ignore_request_headers_set()
+            self.match_body = config.match_request_body
+            self.strict_order = config.strict_order
+            self.redact_request_body = {f for f in config.redact_request_body if f}
+        else:
+            from ._config import DEFAULT_IGNORE_REQUEST_HEADERS
+
+            self.ignore_headers = DEFAULT_IGNORE_REQUEST_HEADERS.copy()
+            if ignore_headers:
+                self.ignore_headers.update(h.lower() for h in ignore_headers)
+            self.match_body = match_body
+            self.strict_order = strict_order
+            self.redact_request_body = set()
+
+    def find_match(
+        self,
+        request: HttpRequest,
+        mappings: List[HttpMapping],
+        used_indices: Set[int],
+    ) -> Optional[Tuple[int, HttpMapping]]:
+        """
+        Find a matching mapping for the given request.
+
+        Args:
+            request: The incoming request to match.
+            mappings: List of available mappings.
+            used_indices: Set of indices that have already been used.
+
+        Returns:
+            Tuple of (index, mapping) if match found, None otherwise.
+        """
+        if self.strict_order:
+            return self._find_match_strict_order(request, mappings, used_indices)
+        return self._find_match_any_order(request, mappings, used_indices)
+
+    def _find_match_any_order(
+        self,
+        request: HttpRequest,
+        mappings: List[HttpMapping],
+        used_indices: Set[int],
+    ) -> Optional[Tuple[int, HttpMapping]]:
+        """Find match allowing any order."""
+        for i, mapping in enumerate(mappings):
+            if i in used_indices:
+                continue
+
+            if self._matches(request, mapping.request):
+                return (i, mapping)
+
+        return None
+
+    def _find_match_strict_order(
+        self,
+        request: HttpRequest,
+        mappings: List[HttpMapping],
+        used_indices: Set[int],
+    ) -> Optional[Tuple[int, HttpMapping]]:
+        """Find match requiring strict order."""
+        # Find the first unused mapping
+        for i, mapping in enumerate(mappings):
+            if i in used_indices:
+                continue
+
+            # In strict mode, must match the next unused mapping
+            if self._matches(request, mapping.request):
+                return (i, mapping)
+            else:
+                # Strict order: if first unused doesn't match, fail
+                return None
+
+        return None
+
+    def _matches(self, actual: HttpRequest, expected: HttpRequest) -> bool:
+        """
+        Check if actual request matches expected request.
+
+        Args:
+            actual: The incoming request.
+            expected: The recorded request.
+
+        Returns:
+            True if requests match, False otherwise.
+        """
+        # Method must match (case-insensitive)
+        if actual.method.upper() != expected.method.upper():
+            return False
+
+        # URL must match (normalized)
+        if not self._urls_match(actual.url, expected.url):
+            return False
+
+        # Query parameters must match
+        if not self._query_params_match(
+            actual.queryParameters,
+            expected.queryParameters,
+            actual.url,
+            expected.url,
+        ):
+            return False
+
+        # Headers must match (considering ignored headers)
+        if not self._headers_match(actual.headers, expected.headers):
+            return False
+
+        # Body must match (if enabled)
+        if self.match_body and not self._body_matches(actual.body, expected.body):
+            return False
+
+        return True
+
+    def _urls_match(self, actual_url: str, expected_url: str) -> bool:
+        """
+        Check if URLs match, ignoring query string.
+
+        Args:
+            actual_url: The actual URL.
+            expected_url: The expected URL.
+
+        Returns:
+            True if URLs match (scheme + host + path).
+        """
+        actual_parsed = urlparse(actual_url)
+        expected_parsed = urlparse(expected_url)
+
+        # Compare scheme, netloc (host:port), and path
+        return (
+            actual_parsed.scheme == expected_parsed.scheme
+            and actual_parsed.netloc == expected_parsed.netloc
+            and actual_parsed.path == expected_parsed.path
+        )
+
+    def _query_params_match(
+        self,
+        actual_params: Dict[str, str],
+        expected_params: Dict[str, str],
+        actual_url: str,
+        expected_url: str,
+    ) -> bool:
+        """
+        Check if query parameters match.
+
+        Compares both explicit queryParameters dict and URL query string.
+
+        Args:
+            actual_params: Actual query parameters dict.
+            expected_params: Expected query parameters dict.
+            actual_url: Actual URL (may contain query string).
+            expected_url: Expected URL (may contain query string).
+
+        Returns:
+            True if query parameters match.
+        """
+        # Merge URL query params with explicit params (explicit takes precedence)
+        actual_merged = self._extract_and_merge_params(actual_url, actual_params)
+        expected_merged = self._extract_and_merge_params(expected_url, expected_params)
+
+        return actual_merged == expected_merged
+
+    def _extract_and_merge_params(
+        self,
+        url: str,
+        explicit_params: Dict[str, str],
+    ) -> Dict[str, str]:
+        """
+        Extract query params from URL and merge with explicit params.
+
+        Args:
+            url: URL that may contain query string.
+            explicit_params: Explicitly provided query parameters.
+
+        Returns:
+            Merged query parameters dict.
+        """
+        parsed = urlparse(url)
+        url_params = parse_qs(parsed.query)
+
+        # Flatten parse_qs result (which returns lists)
+        result: Dict[str, str] = {}
+        for key, values in url_params.items():
+            # Take first value (most common case)
+            result[key] = values[0] if values else ""
+
+        # Explicit params override URL params
+        result.update(explicit_params)
+
+        return result
+
+    def _headers_match(
+        self,
+        actual_headers: Dict[str, str],
+        expected_headers: Dict[str, str],
+    ) -> bool:
+        """
+        Check if headers match, ignoring specified headers.
+
+        All expected headers must be present with matching values.
+        Extra headers in actual request are allowed.
+
+        Args:
+            actual_headers: Actual request headers.
+            expected_headers: Expected request headers.
+
+        Returns:
+            True if all expected headers are present with correct values.
+        """
+        # Normalize header names to lowercase
+        actual_normalized = {k.lower(): v for k, v in actual_headers.items()}
+        expected_normalized = {k.lower(): v for k, v in expected_headers.items()}
+
+        # Check each expected header
+        for key, expected_value in expected_normalized.items():
+            # Skip ignored headers
+            if key in self.ignore_headers:
+                continue
+
+            # Header must be present
+            if key not in actual_normalized:
+                return False
+
+            # Value must match
+            if actual_normalized[key] != expected_value:
+                return False
+
+        return True
+
+    def _body_matches(
+        self,
+        actual_body: Optional[str],
+        expected_body: Optional[str],
+    ) -> bool:
+        """
+        Check if request bodies match.
+
+        Attempts JSON comparison for JSON content, falls back to string comparison.
+
+        Args:
+            actual_body: Actual request body.
+            expected_body: Expected request body.
+
+        Returns:
+            True if bodies match.
+        """
+        # Handle None/empty cases
+        if not actual_body and not expected_body:
+            return True
+        if not actual_body or not expected_body:
+            return False
+
+        # Try JSON comparison (order-independent for objects)
+        try:
+            actual_json = json.loads(actual_body)
+            expected_json = json.loads(expected_body)
+            if self.redact_request_body:
+                actual_json = self._redact_json_fields(actual_json)
+                expected_json = self._redact_json_fields(expected_json)
+            return actual_json == expected_json
+        except (json.JSONDecodeError, TypeError):
+            pass
+
+        # Fall back to string comparison
+        return actual_body == expected_body
+
+    def _redact_json_fields(self, value: Any) -> Any:
+        """Redact configured JSON fields in dict/list structures."""
+        if not self.redact_request_body:
+            return value
+        if isinstance(value, dict):
+            redacted = {}
+            for key, val in value.items():
+                if key in self.redact_request_body:
+                    redacted[key] = "*******"
+                else:
+                    redacted[key] = self._redact_json_fields(val)
+            return redacted
+        if isinstance(value, list):
+            return [self._redact_json_fields(item) for item in value]
+        return value
+
+    def get_mismatch_details(
+        self,
+        actual: HttpRequest,
+        expected: HttpRequest,
+    ) -> Dict[str, Tuple[Any, Any]]:
+        """
+        Get detailed mismatch information between two requests.
+
+        Useful for error messages when a close match is found but not exact.
+
+        Args:
+            actual: The actual request.
+            expected: The expected request.
+
+        Returns:
+            Dict mapping field names to (actual_value, expected_value) tuples.
+        """
+        mismatches: Dict[str, Tuple[Any, Any]] = {}
+
+        if actual.method.upper() != expected.method.upper():
+            mismatches["method"] = (actual.method, expected.method)
+
+        if not self._urls_match(actual.url, expected.url):
+            mismatches["url"] = (actual.url, expected.url)
+
+        actual_params = self._extract_and_merge_params(
+            actual.url, actual.queryParameters
+        )
+        expected_params = self._extract_and_merge_params(
+            expected.url, expected.queryParameters
+        )
+        if actual_params != expected_params:
+            mismatches["queryParameters"] = (actual_params, expected_params)
+
+        if not self._headers_match(actual.headers, expected.headers):
+            # Filter to show only relevant header differences
+            actual_filtered = {
+                k.lower(): v
+                for k, v in actual.headers.items()
+                if k.lower() not in self.ignore_headers
+            }
+            expected_filtered = {
+                k.lower(): v
+                for k, v in expected.headers.items()
+                if k.lower() not in self.ignore_headers
+            }
+            mismatches["headers"] = (actual_filtered, expected_filtered)
+
+        if self.match_body and not self._body_matches(actual.body, expected.body):
+            mismatches["body"] = (actual.body, expected.body)
+
+        return mismatches

fixturify/http_d/_mock_context.py

@@ -0,0 +1,154 @@
+"""HTTP mock context for recording and playback."""
+
+from contextlib import ExitStack
+from pathlib import Path
+from typing import TYPE_CHECKING, Optional
+
+from ._player import HttpPlayer
+from ._recorder import HttpRecorder
+
+if TYPE_CHECKING:
+    from ._config import HttpTestConfig
+    from ._models import HttpRequest, HttpResponse
+
+
+class HttpMockContext:
+    """
+    Manages HTTP recording/playback for a single test.
+    
+    This is the main entry point for HTTP mocking. It handles:
+    - Determining record vs playback mode
+    - Installing/uninstalling patches on HTTP clients
+    - Recording request/response pairs
+    - Playing back recorded responses
+    - Verifying all recordings were used
+    
+    Usage:
+        with HttpMockContext(path, config):
+            # HTTP calls are intercepted here
+            response = requests.get("https://api.example.com")
+    """
+    
+    def __init__(self, path: Path, config: "HttpTestConfig"):
+        """
+        Initialize the mock context.
+        
+        Args:
+            path: Path to the fixture file for recording/playback
+            config: Configuration for HTTP mocking behavior
+        """
+        self.path = path
+        self.config = config
+        self.mode = "playback" if path.exists() else "record"
+        
+        # Initialize recorder or player based on mode
+        if self.mode == "record":
+            self._recorder: Optional[HttpRecorder] = HttpRecorder(
+                path,
+                exclude_request_headers=config.get_exclude_request_headers_set(),
+                exclude_response_headers=config.get_exclude_response_headers_set(),
+                redact_request_body=config.redact_request_body,
+                redact_response_body=config.redact_response_body,
+            )
+            self._player: Optional[HttpPlayer] = None
+        else:
+            self._recorder = None
+            self._player = HttpPlayer(path, config=config)
+        
+        # Patch management
+        self._exit_stack: Optional[ExitStack] = None
+    
+    def __enter__(self) -> "HttpMockContext":
+        """Start HTTP interception by installing patches."""
+        from ._patcher import PatcherBuilder
+        
+        self._exit_stack = ExitStack()
+        
+        # Build and start all patches
+        patcher = PatcherBuilder(self)
+        for patch in patcher.build():
+            self._exit_stack.enter_context(patch)
+        
+        return self
+    
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Stop HTTP interception and finalize recording/playback."""
+        # Stop all patches
+        if self._exit_stack:
+            self._exit_stack.close()
+            self._exit_stack = None
+        
+        # Handle recording/playback finalization
+        if self.mode == "record" and self._recorder is not None:
+            self._recorder.save()
+        elif self.mode == "playback" and self._player and exc_type is None:
+            # Only verify if no exception occurred (don't mask original error)
+            self._player.verify_all_used()
+        
+        return False  # Don't suppress exceptions
+    
+    def can_play_response_for(self, request: "HttpRequest") -> bool:
+        """
+        Check if a recorded response exists for the given request.
+        
+        Args:
+            request: The HTTP request to check
+            
+        Returns:
+            True if in playback mode and a matching response exists
+        """
+        if self._player is None:
+            return False
+        
+        # Try to find a match without consuming it
+        try:
+            result = self._player.matcher.find_match(
+                request, 
+                self._player.mappings, 
+                self._player.used_indices
+            )
+            return result is not None
+        except Exception:
+            return False
+    
+    def play_response(self, request: "HttpRequest") -> "HttpResponse":
+        """
+        Get the recorded response for a request.
+        
+        Args:
+            request: The HTTP request to match
+            
+        Returns:
+            The matching recorded response
+            
+        Raises:
+            NoMatchingRecordingError: If no matching recording found
+        """
+        if self._player is None:
+            from ._exceptions import NoMatchingRecordingError
+            raise NoMatchingRecordingError(request=request, available_mappings=[])
+        
+        return self._player.find_response(request)
+    
+    def record(self, request: "HttpRequest", response: "HttpResponse") -> None:
+        """
+        Record a request/response pair.
+        
+        Args:
+            request: The HTTP request
+            response: The HTTP response
+        """
+        if self._recorder is not None:
+            self._recorder.record(request, response)
+    
+    def is_host_excluded(self, url: str) -> bool:
+        """
+        Check if a URL's host is excluded from mocking.
+        
+        Args:
+            url: The URL to check
+            
+        Returns:
+            True if the host should not be mocked
+        """
+        return self.config.is_host_excluded(url)