fixturify 0.1.9__py3-none-any.whl

fixturify/json_assert/_assert.py

@@ -0,0 +1,173 @@
+"""Main JsonAssert class with fluent API."""
+
+import json
+from typing import Any, Dict, List, Optional
+
+from fixturify._utils._constants import ENCODING
+from fixturify._utils._path_resolver import _PathResolver
+from fixturify.json_assert._normalizer import _Normalizer
+from fixturify.json_assert._comparator import _Comparator
+from fixturify.json_assert._diff_formatter import _DiffFormatter
+from fixturify.json_assert._actual_saver import _ActualSaver
+
+
+class JsonAssert:
+    """
+    JSON comparison assertions for testing.
+
+    Provides a fluent API for comparing Python objects/data to JSON files.
+
+    Example:
+        JsonAssert(user).compare_to_file("./expected.json")
+
+        JsonAssert(response)
+            .ignore("root['id']", "root['timestamp']")
+            .options(ignore_order=True)
+            .compare_to_file("./expected.json")
+    """
+
+    def __init__(self, data: Any) -> None:
+        """
+        Initialize JsonAssert with data to compare.
+
+        Args:
+            data: The actual data to compare against expected JSON file.
+                  Can be: object, list of objects, dict, or JSON string.
+        """
+        self._data = data
+        self._normalizer = _Normalizer()
+        self._exclude_paths: List[str] = []
+        self._exclude_regex_paths: List[str] = []
+        self._ignore_order: bool = False
+        self._numeric_tolerance: Optional[float] = None
+        self._ignore_type_in_groups: Optional[List[tuple]] = None
+        self._extra_options: Dict[str, Any] = {}
+
+    def ignore(self, *paths: str) -> "JsonAssert":
+        """
+        Specify paths to ignore during comparison.
+
+        Supports both bracket notation and dot notation:
+        - "id" or "root['id']" - top-level field
+        - "user.name" or "root['user']['name']" - nested field
+        - "users[*].id" - field in all list items (wildcard)
+
+        Args:
+            *paths: Paths to ignore
+
+        Returns:
+            Self for method chaining (accumulates with previous calls)
+        """
+        self._exclude_paths.extend(paths)
+        return self
+
+    def ignore_regex(self, *patterns: str) -> "JsonAssert":
+        """
+        Specify regex patterns to ignore during comparison.
+
+        Use this for ignoring fields across all list indices with complex patterns.
+
+        Pattern syntax (regex):
+        - r"root\\[\\d+\\]\\['id'\\]" - 'id' in any list item
+        - r"root\\['users'\\]\\[\\d+\\]\\['email'\\]" - 'email' in any user
+
+        Args:
+            *patterns: Regex patterns to ignore
+
+        Returns:
+            Self for method chaining (accumulates with previous calls)
+        """
+        self._exclude_regex_paths.extend(patterns)
+        return self
+
+    def options(
+        self,
+        ignore_order: bool = False,
+        numeric_tolerance: Optional[float] = None,
+        ignore_type_in_groups: Optional[List[tuple]] = None,
+        **kwargs,
+    ) -> "JsonAssert":
+        """
+        Set comparison options.
+
+        Args:
+            ignore_order: If True, ignore order in lists/arrays
+            numeric_tolerance: Tolerance for float comparisons (e.g., 0.001)
+            ignore_type_in_groups: Type groups to treat as equal (e.g., [(int, float)])
+            **kwargs: Additional deepdiff options
+
+        Returns:
+            Self for method chaining
+        """
+        if ignore_order:
+            self._ignore_order = True
+
+        if numeric_tolerance is not None:
+            self._numeric_tolerance = numeric_tolerance
+
+        if ignore_type_in_groups is not None:
+            self._ignore_type_in_groups = ignore_type_in_groups
+
+        self._extra_options.update(kwargs)
+        return self
+
+    def compare_to_file(self, relative_path: str) -> None:
+        """
+        Compare data to JSON file. Raises AssertionError if different.
+
+        Args:
+            relative_path: Path to JSON file, relative to caller's location
+
+        Raises:
+            AssertionError: If data doesn't match file content (with diff details)
+            FileNotFoundError: If JSON file doesn't exist
+            ValueError: If data can't be converted or file can't be parsed
+        """
+        # Resolve the path relative to the caller's file
+        # Use centralized caller detection from _PathResolver
+        caller_file = _PathResolver._get_caller_file(stack_level=1)
+        expected_path = _PathResolver.resolve(relative_path, caller_file)
+
+        # Read and parse the expected JSON file
+        try:
+            content = expected_path.read_text(encoding=ENCODING)
+            expected_data = json.loads(content)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in expected file {expected_path}: {e}")
+
+        # Normalize the actual data
+        try:
+            actual_data = self._normalizer.normalize(self._data)
+        except ValueError as e:
+            raise ValueError(f"Cannot normalize actual data: {e}")
+
+        # Create comparator with accumulated options
+        comparator = _Comparator(
+            exclude_paths=self._exclude_paths,
+            exclude_regex_paths=self._exclude_regex_paths,
+            ignore_order=self._ignore_order,
+            numeric_tolerance=self._numeric_tolerance,
+            ignore_type_in_groups=self._ignore_type_in_groups,
+            extra_options=self._extra_options,
+        )
+
+        # Perform comparison
+        result = comparator.compare(actual_data, expected_data)
+
+        if not result.is_equal:
+            # Save actual data to ACTUAL folder
+            actual_saved_path, save_ok = _ActualSaver.save(actual_data, expected_path)
+
+            # Format the diff
+            formatted = _DiffFormatter.format(
+                result.diff,
+                expected_path=str(relative_path),
+                actual_saved_path=str(actual_saved_path),
+                save_failed=not save_ok,
+            )
+
+            # Print to stderr for test visibility
+            _DiffFormatter.print_diff(formatted)
+
+            # Raise AssertionError with formatted message
+            raise AssertionError(f"\n{formatted}")

fixturify/json_assert/_comparator.py

@@ -0,0 +1,183 @@
+"""Comparator using deepdiff for JSON comparison."""
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+from deepdiff import DeepDiff
+
+
+@dataclass
+class CompareResult:
+    """Result of a comparison operation."""
+
+    is_equal: bool
+    diff: Optional[DeepDiff] = None
+
+
+class _Comparator:
+    """Handles the actual comparison using deepdiff."""
+
+    def __init__(
+        self,
+        exclude_paths: List[str] = None,
+        exclude_regex_paths: List[str] = None,
+        ignore_order: bool = False,
+        numeric_tolerance: Optional[float] = None,
+        ignore_type_in_groups: Optional[List[tuple]] = None,
+        extra_options: Dict[str, Any] = None,
+    ):
+        """
+        Initialize the comparator with options.
+
+        Args:
+            exclude_paths: Exact paths to ignore (deepdiff exclude_paths)
+            exclude_regex_paths: Regex patterns to ignore (deepdiff exclude_regex_paths)
+            ignore_order: If True, ignore order in lists
+            numeric_tolerance: Tolerance for float comparisons
+            ignore_type_in_groups: Type groups to treat as equal
+            extra_options: Additional deepdiff options
+        """
+        self._exclude_paths = exclude_paths or []
+        self._exclude_regex_paths = exclude_regex_paths or []
+        self._ignore_order = ignore_order
+        self._numeric_tolerance = numeric_tolerance
+        self._ignore_type_in_groups = ignore_type_in_groups
+        self._extra_options = extra_options or {}
+
+    def compare(
+        self, actual: Union[dict, list], expected: Union[dict, list]
+    ) -> CompareResult:
+        """
+        Compare actual vs expected data using DeepDiff.
+
+        Args:
+            actual: The actual data
+            expected: The expected data
+
+        Returns:
+            CompareResult with is_equal bool and diff details
+        """
+        options = self._build_deepdiff_options()
+
+        # Use verbose_level=2 to preserve actual values for added/removed items
+        # This allows the diff formatter to show the values, not just the paths
+        diff = DeepDiff(expected, actual, verbose_level=2, **options)
+
+        return CompareResult(is_equal=not bool(diff), diff=diff if diff else None)
+
+    def _build_deepdiff_options(self) -> Dict[str, Any]:
+        """Build options dict for DeepDiff."""
+        options = {}
+
+        # Normalize and process exclude paths
+        normalized_paths = []
+        additional_regex_paths = list(self._exclude_regex_paths)
+
+        for path in self._exclude_paths:
+            normalized = self._normalize_path(path)
+            if self._has_wildcard(normalized):
+                # Convert wildcard to regex
+                regex_pattern = self._convert_wildcard_to_regex(normalized)
+                additional_regex_paths.append(regex_pattern)
+            else:
+                normalized_paths.append(normalized)
+
+        if normalized_paths:
+            options["exclude_paths"] = set(normalized_paths)
+
+        if additional_regex_paths:
+            options["exclude_regex_paths"] = [
+                re.compile(p) for p in additional_regex_paths
+            ]
+
+        if self._ignore_order:
+            options["ignore_order"] = True
+
+        if self._numeric_tolerance is not None:
+            options["math_epsilon"] = self._numeric_tolerance
+
+        if self._ignore_type_in_groups:
+            options["ignore_type_in_groups"] = self._ignore_type_in_groups
+
+        # Add any extra options
+        options.update(self._extra_options)
+
+        return options
+
+    def _normalize_path(self, path: str) -> str:
+        """
+        Normalize path to deepdiff format.
+
+        Converts:
+        - Simple field names to root['field']
+        - Dot notation to bracket notation
+        - Preserves [n] and [*] index notation
+
+        Examples:
+            "id" -> "root['id']"
+            "user.name" -> "root['user']['name']"
+            "users[0].name" -> "root['users'][0]['name']"
+            "users[*].id" -> "root['users'][*]['id']"
+            "root['users'][*].id" -> "root['users'][*]['id']"
+        """
+        # If already in pure bracket format (no dots after root), return as-is
+        if path.startswith("root[") and "." not in path:
+            return path
+
+        # If it doesn't start with root, add it
+        if not path.startswith("root"):
+            path = f"root.{path}"
+
+        # Convert dot notation to bracket notation
+        # But preserve [n] and [*] indices
+        result = ""
+        i = 0
+        while i < len(path):
+            char = path[i]
+
+            if char == ".":
+                # Start of a new segment
+                i += 1
+                # Find the end of this segment (next . or [)
+                segment_start = i
+                while i < len(path) and path[i] not in ".[]":
+                    i += 1
+                segment = path[segment_start:i]
+                if segment:
+                    result += f"['{segment}']"
+            elif char == "[":
+                # Copy the bracket notation as-is
+                bracket_start = i
+                i += 1
+                while i < len(path) and path[i] != "]":
+                    i += 1
+                i += 1  # Include the ]
+                result += path[bracket_start:i]
+            else:
+                # Part of 'root' or other text before first . or [
+                segment_start = i
+                while i < len(path) and path[i] not in ".[]":
+                    i += 1
+                segment = path[segment_start:i]
+                result += segment
+
+        return result
+
+    def _has_wildcard(self, path: str) -> bool:
+        """Check if path contains [*] wildcard."""
+        return "[*]" in path
+
+    def _convert_wildcard_to_regex(self, path: str) -> str:
+        r"""
+        Convert wildcard [*] syntax to deepdiff regex pattern.
+
+        Example:
+            "root['users'][*]['id']" -> r"root\['users'\]\[\d+\]\['id'\]"
+        """
+        # Escape special regex characters
+        escaped = re.escape(path)
+        # Convert escaped [*] back to regex pattern for any index
+        # re.escape turns [*] into \[\*\]
+        regex = escaped.replace(r"\[\*\]", r"\[\d+\]")
+        return regex

fixturify/json_assert/_diff_formatter.py

@@ -0,0 +1,265 @@
+"""Diff formatter for human-readable comparison output."""
+
+import sys
+from typing import Any, Dict, List, Set, Union
+
+from deepdiff import DeepDiff
+
+
+class _DiffFormatter:
+    """Formats DeepDiff results into human-readable tables."""
+
+    MAX_VALUE_LENGTH = 50
+
+    @staticmethod
+    def format(
+        diff: DeepDiff,
+        expected_path: str,
+        actual_saved_path: str,
+        save_failed: bool = False,
+    ) -> str:
+        """
+        Format DeepDiff result into human-readable table format.
+
+        Args:
+            diff: DeepDiff result object
+            expected_path: Path to expected JSON file
+            actual_saved_path: Path where actual JSON was saved
+            save_failed: Whether saving the actual file failed
+
+        Returns:
+            Formatted string with tables showing all differences
+        """
+        lines = []
+
+        # Header
+        lines.append("=" * 80)
+        lines.append("                           JSON COMPARISON FAILED")
+        lines.append("=" * 80)
+        lines.append("")
+        lines.append(f"Expected file: {expected_path}")
+        if save_failed:
+            lines.append(f"Actual saved:  {actual_saved_path} (SAVE FAILED)")
+        else:
+            lines.append(f"Actual saved:  {actual_saved_path}")
+        lines.append("")
+        lines.append("-" * 80)
+        lines.append("                              DIFFERENCES SUMMARY")
+        lines.append("-" * 80)
+        lines.append("")
+
+        # Process different types of differences
+        has_content = False
+
+        # Changed values
+        if "values_changed" in diff:
+            has_content = True
+            lines.append(_DiffFormatter._format_changed_values(diff["values_changed"]))
+            lines.append("")
+
+        # Type changes
+        if "type_changes" in diff:
+            has_content = True
+            lines.append(_DiffFormatter._format_type_changes(diff["type_changes"]))
+            lines.append("")
+
+        # Items added (extra in actual)
+        if "dictionary_item_added" in diff or "iterable_item_added" in diff:
+            has_content = True
+            added_paths: List[str] = []
+            if "dictionary_item_added" in diff:
+                added_paths.extend(
+                    _DiffFormatter._extract_paths(diff["dictionary_item_added"])
+                )
+            if "iterable_item_added" in diff:
+                added_paths.extend(
+                    _DiffFormatter._extract_paths(diff["iterable_item_added"])
+                )
+            lines.append(_DiffFormatter._format_added_items(added_paths, diff))
+            lines.append("")
+
+        # Items removed (missing in actual)
+        if "dictionary_item_removed" in diff or "iterable_item_removed" in diff:
+            has_content = True
+            removed_paths: List[str] = []
+            if "dictionary_item_removed" in diff:
+                removed_paths.extend(
+                    _DiffFormatter._extract_paths(diff["dictionary_item_removed"])
+                )
+            if "iterable_item_removed" in diff:
+                removed_paths.extend(
+                    _DiffFormatter._extract_paths(diff["iterable_item_removed"])
+                )
+            lines.append(_DiffFormatter._format_removed_items(removed_paths, diff))
+            lines.append("")
+
+        if not has_content:
+            lines.append("No specific differences to display.")
+            lines.append("")
+
+        lines.append("=" * 80)
+
+        return "\n".join(lines)
+
+    @staticmethod
+    def _extract_paths(items: Union[Set, Dict, Any]) -> List[str]:
+        """
+        Extract paths from DeepDiff items.
+
+        DeepDiff returns different types depending on version and diff type:
+        - Sets of path strings (e.g., SetOrdered(["root['key']"]))
+        - Dicts of path -> value
+        """
+        if items is None:
+            return []
+
+        # If it's a dict-like with items(), use keys
+        if hasattr(items, "items"):
+            return list(items.keys())
+
+        # If it's iterable (set-like), convert to list
+        try:
+            return list(items)
+        except TypeError:
+            return []
+
+    @staticmethod
+    def print_diff(formatted_output: str) -> None:
+        """
+        Print the formatted diff to stderr for test visibility.
+
+        Args:
+            formatted_output: The formatted diff string
+        """
+        print(formatted_output, file=sys.stderr)
+
+    @staticmethod
+    def _format_changed_values(changed: Dict[str, Any]) -> str:
+        """Format changed values as a table."""
+        lines = ["CHANGED VALUES:"]
+        lines.append("-" * 70)
+        lines.append(f"{'Path':<30} | {'Actual':<18} | {'Expected':<18}")
+        lines.append("-" * 70)
+
+        for path, change in changed.items():
+            # old_value = expected (from file), new_value = actual (from data)
+            expected_val = _DiffFormatter._truncate_value(
+                change.get("old_value", change)
+            )
+            actual_val = _DiffFormatter._truncate_value(change.get("new_value", change))
+            path_display = _DiffFormatter._truncate_value(path, 28)
+            lines.append(f"{path_display:<30} | {actual_val:<18} | {expected_val:<18}")
+
+        lines.append("-" * 70)
+        return "\n".join(lines)
+
+    @staticmethod
+    def _format_type_changes(changes: Dict[str, Any]) -> str:
+        """Format type changes as a table."""
+        lines = ["TYPE CHANGES:"]
+        lines.append("-" * 70)
+        lines.append(f"{'Path':<30} | {'Actual Type':<18} | {'Expected Type':<18}")
+        lines.append("-" * 70)
+
+        for path, change in changes.items():
+            # old_value = expected (from file), new_value = actual (from data)
+            expected_type = type(change.get("old_value", "")).__name__
+            actual_type = type(change.get("new_value", "")).__name__
+            path_display = _DiffFormatter._truncate_value(path, 28)
+            lines.append(
+                f"{path_display:<30} | {actual_type:<18} | {expected_type:<18}"
+            )
+
+        lines.append("-" * 70)
+        return "\n".join(lines)
+
+    @staticmethod
+    def _format_added_items(paths: List[str], diff: DeepDiff) -> str:
+        """Format items that are extra in actual (added)."""
+        lines = ["EXTRA IN ACTUAL (found but not expected):"]
+        lines.append("-" * 70)
+        lines.append(f"{'Path':<30} | {'Actual Value':<38}")
+        lines.append("-" * 70)
+
+        for path in paths:
+            path_display = _DiffFormatter._truncate_value(path, 28)
+            # Try to get the value from DeepDiff if available
+            value = _DiffFormatter._get_value_for_path(diff, path, "added")
+            val_display = _DiffFormatter._truncate_value(value, 36)
+            lines.append(f"{path_display:<30} | {val_display:<38}")
+
+        lines.append("-" * 70)
+        return "\n".join(lines)
+
+    @staticmethod
+    def _format_removed_items(paths: List[str], diff: DeepDiff) -> str:
+        """Format items that are missing in actual (removed)."""
+        lines = ["MISSING IN ACTUAL (expected but not found):"]
+        lines.append("-" * 70)
+        lines.append(f"{'Path':<30} | {'Expected Value':<38}")
+        lines.append("-" * 70)
+
+        for path in paths:
+            path_display = _DiffFormatter._truncate_value(path, 28)
+            # Try to get the value from DeepDiff if available
+            value = _DiffFormatter._get_value_for_path(diff, path, "removed")
+            val_display = _DiffFormatter._truncate_value(value, 36)
+            lines.append(f"{path_display:<30} | {val_display:<38}")
+
+        lines.append("-" * 70)
+        return "\n".join(lines)
+
+    # Sentinel value to distinguish "key not found" from "key exists with None value"
+    _NOT_FOUND = object()
+
+    @staticmethod
+    def _get_value_for_path(diff: DeepDiff, path: str, change_type: str) -> Any:
+        """
+        Try to extract the actual value for a path from DeepDiff.
+
+        Args:
+            diff: The DeepDiff object
+            path: The path string (e.g., "root['key']")
+            change_type: Either "added" or "removed"
+
+        Returns:
+            The value if found (including None), or "<value not available>" placeholder
+        """
+        # DeepDiff stores values differently depending on version
+        # Try to access via the verbose output or tree view
+        try:
+            # Check if diff has the value stored (depends on DeepDiff version/config)
+            if change_type == "added":
+                for key in ["dictionary_item_added", "iterable_item_added"]:
+                    if key in diff:
+                        items = diff[key]
+                        # If it's a dict with path->value mapping, check if path exists
+                        if hasattr(items, "get") and hasattr(items, "__contains__"):
+                            if path in items:
+                                return items[
+                                    path
+                                ]  # Returns the value, even if it's None
+            elif change_type == "removed":
+                for key in ["dictionary_item_removed", "iterable_item_removed"]:
+                    if key in diff:
+                        items = diff[key]
+                        if hasattr(items, "get") and hasattr(items, "__contains__"):
+                            if path in items:
+                                return items[
+                                    path
+                                ]  # Returns the value, even if it's None
+        except Exception:
+            pass
+
+        return "<value not available>"
+
+    @staticmethod
+    def _truncate_value(value: Any, max_length: int = None) -> str:
+        """Truncate long values for table display."""
+        if max_length is None:
+            max_length = _DiffFormatter.MAX_VALUE_LENGTH
+
+        str_val = repr(value)
+        if len(str_val) > max_length:
+            return str_val[: max_length - 3] + "..."
+        return str_val