assertpy2 2.6.0__tar.gz → 2.8.0__tar.gz

{assertpy2-2.6.0 → assertpy2-2.8.0}/.gitignore

@@ -10,6 +10,7 @@ __pycache__
 cover
 .coverage
 htmlcov
+.hypothesis
 __snapshots
 mycustompath
 

{assertpy2-2.6.0 → assertpy2-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: assertpy2
-Version: 2.6.0
+Version: 2.8.0
 Summary: Fluent assertion library for Python with composable matchers, structural matching, and full type safety
 Project-URL: Homepage, https://github.com/Solganis/assertpy2
 Project-URL: Repository, https://github.com/Solganis/assertpy2
@@ -86,24 +86,49 @@ def test_user():
 
 ## Why fluent assertions?
 
-```py
-# bare assert - passes, but failure message is useless
-assert user["age"] >= 18
-# AssertionError
-
-# assertpy2 - same check, clear failure message
-assert_that(user["age"]).is_greater_than_or_equal_to(18)
-# AssertionError: Expected <16> to be greater than or equal to <18>, but was not.
+A fluent chain reads as one intent and replaces several bare asserts - and your IDE
+offers only the methods that fit the value's type:
 
-# bare assert - three separate statements
+```py
+# bare - three statements, no autocomplete help
 assert isinstance(items, list)
 assert len(items) == 3
 assert "admin" in items
 
-# assertpy2 - one fluent chain
+# assertpy2 - one chain, type-aware autocomplete
 assert_that(items).is_type_of(list).is_length(3).contains("admin")
 ```
 
+The real difference shows up when a test fails. Here a nested response has two wrong
+fields. Plain `assert` dumps both structures and leaves you to find them:
+
+```text
+assert response == expected
+E   AssertionError: assert {'id': 1, ...} == {'id': 1, ...}
+E     Omitting 1 identical items, use -vv to show
+E     Differing items:
+E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Alice', 'role': 'admin'}}
+E     {'status': 'active'} != {'status': 'disabled'}
+```
+
+assertpy2 reports the exact path to every difference:
+
+```text
+assert_that(response).is_equal_to(expected)
+--- Structured Diff ---
+diff (dict):
+  status:
+    - 'active'
+    + 'disabled'
+  user.role:
+    - 'superadmin'
+    + 'admin'
+```
+
+Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
+For responses with dynamic fields (IDs, timestamps), validate a subset with
+`matches_structure()` instead of exact equality.
+
 ## Type-aware autocomplete
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
@@ -124,7 +149,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 **Fluent API**
 
 - [**Composable matchers**](https://solganis.github.io/assertpy2/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
-- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation, reporting the exact path to each mismatch on failure.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
@@ -143,7 +168,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`. Group errors with `sa.group()`, or use `assert_all()`.
 - [**Async assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` with polling/retry for eventual consistency.
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
-- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models. Circular reference protection.
+- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
 
 **Type safety**

{assertpy2-2.6.0 → assertpy2-2.8.0}/README.md

@@ -48,24 +48,49 @@ def test_user():
 
 ## Why fluent assertions?
 
-```py
-# bare assert - passes, but failure message is useless
-assert user["age"] >= 18
-# AssertionError
-
-# assertpy2 - same check, clear failure message
-assert_that(user["age"]).is_greater_than_or_equal_to(18)
-# AssertionError: Expected <16> to be greater than or equal to <18>, but was not.
+A fluent chain reads as one intent and replaces several bare asserts - and your IDE
+offers only the methods that fit the value's type:
 
-# bare assert - three separate statements
+```py
+# bare - three statements, no autocomplete help
 assert isinstance(items, list)
 assert len(items) == 3
 assert "admin" in items
 
-# assertpy2 - one fluent chain
+# assertpy2 - one chain, type-aware autocomplete
 assert_that(items).is_type_of(list).is_length(3).contains("admin")
 ```
 
+The real difference shows up when a test fails. Here a nested response has two wrong
+fields. Plain `assert` dumps both structures and leaves you to find them:
+
+```text
+assert response == expected
+E   AssertionError: assert {'id': 1, ...} == {'id': 1, ...}
+E     Omitting 1 identical items, use -vv to show
+E     Differing items:
+E     {'user': {'name': 'Alice', 'role': 'superadmin'}} != {'user': {'name': 'Alice', 'role': 'admin'}}
+E     {'status': 'active'} != {'status': 'disabled'}
+```
+
+assertpy2 reports the exact path to every difference:
+
+```text
+assert_that(response).is_equal_to(expected)
+--- Structured Diff ---
+diff (dict):
+  status:
+    - 'active'
+    + 'disabled'
+  user.role:
+    - 'superadmin'
+    + 'admin'
+```
+
+Recursive diffs work for dicts, dataclasses, namedtuples, attrs, and Pydantic models.
+For responses with dynamic fields (IDs, timestamps), validate a subset with
+`matches_structure()` instead of exact equality.
+
 ## Type-aware autocomplete
 
 `assert_that()` uses `@overload` to return type-specific Protocols.
@@ -86,7 +111,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 **Fluent API**
 
 - [**Composable matchers**](https://solganis.github.io/assertpy2/matchers/): `match.greater_than(5)`, `match.is_uuid()`, combine with `&`, `|`, `~`. Also work with plain `assert ==`.
-- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation.
+- [**Structural matching**](https://solganis.github.io/assertpy2/matchers/#structural-matching): `matches_structure()` for declarative dict/API response validation, reporting the exact path to each mismatch on failure.
 - [**Universal negation**](https://solganis.github.io/assertpy2/fluent/#universal-negation): `.not_` inverts any assertion without dedicated `is_not_*` methods.
 - [**Collection pipeline**](https://solganis.github.io/assertpy2/fluent/#collection-pipeline): `filtered_on()`, `mapped()`, `flat_mapped()`, `first()`, `last()`, `element()`, `single()`.
 - [**Fluent chaining**](https://solganis.github.io/assertpy2/fluent/#chaining): write assertions as readable one-liners that chain naturally.
@@ -105,7 +130,7 @@ Your IDE shows only methods relevant to the value you're testing, not all 100+:
 - [**Soft assertions**](https://solganis.github.io/assertpy2/testing/#soft-assertions): thread-safe, async-safe via `contextvars`. Group errors with `sa.group()`, or use `assert_all()`.
 - [**Async assertions**](https://solganis.github.io/assertpy2/testing/#async-assertions): `eventually()` with polling/retry for eventual consistency.
 - [**Structured errors**](https://solganis.github.io/assertpy2/errors/#structured-errors): `AssertionFailure` with `.actual`, `.expected`, `.diff` attributes.
-- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models. Circular reference protection.
+- [**Rich pytest diffs**](https://solganis.github.io/assertpy2/errors/#rich-pytest-diffs): recursive structural diffs for lists, sets, strings, dicts, dataclasses, namedtuples, Pydantic models, and matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`). Circular reference protection.
 - [**Snapshot testing**](https://solganis.github.io/assertpy2/testing/#snapshot-testing): store and compare data structures in JSON format.
 
 **Type safety**

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/_mixin_base.py

@@ -17,6 +17,7 @@ class _MixinBase:
         logger: logging.LoggerAdapter
         _not_expected: bool
         _expected_warning: type[Warning] | None
+        _return_value: object
 
         def error(
             self,
@@ -32,7 +33,7 @@ class _MixinBase:
             val: object,
             description: str = ...,
             kind: str | None = ...,
-            expected: BaseException | None = ...,
+            expected: type[BaseException] | None = ...,
             logger: logging.LoggerAdapter | None = ...,
         ) -> Self: ...
 

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/_typing.py

@@ -215,6 +215,17 @@ if TYPE_CHECKING:
         def is_hex_equal_to(self, expected_hex: str) -> Self: ...
         def decoded_as(self, encoding: str = ...) -> _StringAssertion: ...
 
+    class _InvokedAssertion(_StringAssertion, Protocol):
+        """Assertions available after ``when_called_with()`` captured an exception/warning message.
+
+        The captured message is a ``str`` (hence the string assertions); :meth:`returned` pivots to
+        the value the callable returned.  Its static type is unknown, so ``returned()`` exposes the
+        type-agnostic core assertions (``is_equal_to``, ``is_instance_of``, ``satisfies``, ...) -
+        type-safe by construction, never advertising methods that may not apply.
+        """
+
+        def returned(self) -> _CoreAssertion: ...
+
     class _CallableAssertion(_CoreAssertion, Protocol):
         """Assertions available for callable values."""
 
@@ -222,5 +233,6 @@ if TYPE_CHECKING:
         def does_not_raise(self, ex: type) -> Self: ...
         def warns(self, warning: type[Warning] = ...) -> Self: ...
         def does_not_warn(self, warning: type[Warning] = ...) -> Self: ...
-        def when_called_with(self, *some_args: object, **some_kwargs: object) -> Self: ...
+        # captured value (exception or warning message) is a str; returned() pivots to the call result
+        def when_called_with(self, *some_args: object, **some_kwargs: object) -> _InvokedAssertion: ...
         def eventually(self, *, timeout: float = ..., interval: float = ...) -> AsyncAssertionBuilder: ...

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/assertpy.py

@@ -37,7 +37,7 @@ from .date import DateMixin
 from .dict import DictMixin
 from .dynamic import DynamicMixin
 from .errors import AssertionFailure
-from .exception import ExceptionMixin
+from .exception import _UNSET, ExceptionMixin
 from .extracting import ExtractingMixin
 from .file import FileMixin
 from .helpers import HelpersMixin
@@ -47,7 +47,7 @@ from .snapshot import SnapshotMixin
 from .string import StringMixin
 from .warning import WarningMixin
 
-__version__ = "2.6.0"
+__version__ = "2.8.0"
 
 __tracebackhide__ = True  # clean tracebacks via py.test integration
 contextlib.__tracebackhide__ = True  # ty: ignore[unresolved-attribute]  # pytest monkey-patch
@@ -589,6 +589,7 @@ class AssertionBuilder(
         self.logger = logger if logger else _default_logger
         self._not_expected = False
         self._expected_warning = None
+        self._return_value = _UNSET
 
     @property
     def not_(self) -> NegatedBuilder:

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/base.py

@@ -430,7 +430,13 @@ class BaseMixin(_MixinBase):
         """
         if isinstance(matcher, Matcher):
             if not matcher.matches(self.val):
-                return self.error(f"Expected {matcher.describe()}, but {matcher.describe_mismatch(self.val)}.")
+                description = matcher.describe()
+                return self.error(
+                    f"Expected {description}, but {matcher.describe_mismatch(self.val)}.",
+                    actual=self.val,
+                    expected=description,
+                    diff=DiffResult(kind="match", entries=[DiffEntry(path=".", actual=self.val, expected=description)]),
+                )
         elif callable(matcher):
             if not matcher(self.val):
                 return self.error(f"Expected <{self.val}> to satisfy <{matcher}>, but did not.")
@@ -466,11 +472,17 @@ class BaseMixin(_MixinBase):
         if not isinstance(self.val, collections.abc.Iterable):
             raise TypeError("val is not iterable")
         if isinstance(matcher, Matcher):
+            description = matcher.describe()
             for i, item in enumerate(self.val):
                 if not matcher.matches(item):
                     return self.error(
-                        f"Expected all items to satisfy {matcher.describe()}, but item at index {i} <{item}> did not:"
-                        f" {matcher.describe_mismatch(item)}."
+                        f"Expected all items to satisfy {description}, but item at index {i} <{item}> did not:"
+                        f" {matcher.describe_mismatch(item)}.",
+                        actual=item,
+                        expected=description,
+                        diff=DiffResult(
+                            kind="match", entries=[DiffEntry(path=f"[{i}]", actual=item, expected=description)]
+                        ),
                     )
         elif callable(matcher):
             for i, item in enumerate(self.val):
@@ -515,10 +527,17 @@ class BaseMixin(_MixinBase):
         if not isinstance(spec, dict):
             raise TypeError("given arg must be a dict")
         matcher = StructureMatcher(spec)
-        if not matcher.matches(self.val):
+        mismatches = matcher.collect_mismatches(self.val)
+        if mismatches:
+            entries = [
+                DiffEntry(path=path, actual=actual, expected=description) for path, actual, description in mismatches
+            ]
             return self.error(
                 f"Expected <{self.val}> to match structure {matcher.describe()}, but"
-                f" {matcher.describe_mismatch(self.val)}."
+                f" {matcher.describe_mismatch(self.val)}.",
+                actual=self.val,
+                expected=spec,
+                diff=DiffResult(kind="match", entries=entries),
             )
         return self
 

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/exception.py

@@ -9,6 +9,8 @@ if TYPE_CHECKING:
 
 __tracebackhide__ = True
 
+_UNSET = object()  # sentinel: no return value captured yet
+
 
 class _InertBuilder:
     """No-op builder returned after a failed raises/when_called_with in soft mode.
@@ -105,10 +107,34 @@ class ExceptionMixin(_MixinBase):
         )
         return cast("Self", _InertBuilder())
 
+    def returned(self) -> Self:
+        """Pivots the chain to the value ``val()`` returned during :meth:`when_called_with`.
+
+        Use after a call that completed normally (:meth:`~assertpy2.warning.WarningMixin.warns`,
+        :meth:`~assertpy2.warning.WarningMixin.does_not_warn`, or :meth:`does_not_raise`) to assert
+        on the return value in the same chain.
+
+        Examples:
+            Usage::
+
+                assert_that(make_client).warns(DeprecationWarning).when_called_with().returned().is_instance_of(Client)
+                assert_that(adder).does_not_raise(TypeError).when_called_with(1, 2).returned().is_equal_to(3)
+
+        Returns:
+            AssertionBuilder: a new instance wrapping the captured return value
+
+        Raises:
+            TypeError: if no return value was captured (the call raised, or :meth:`when_called_with`
+                was not invoked first)
+        """
+        if self._return_value is _UNSET:
+            raise TypeError("no return value captured; returned() is only valid after a call that completed normally")
+        return self.builder(self._return_value, self.description, self.kind, logger=self.logger)
+
     def _when_called_with_not_expected(self, *some_args, **some_kwargs) -> Self:
         assert self.expected is not None
         try:
-            self.val(*some_args, **some_kwargs)
+            result = self.val(*some_args, **some_kwargs)
         except BaseException as e:
             if issubclass(type(e), self.expected):
                 self.error(
@@ -117,6 +143,8 @@ class ExceptionMixin(_MixinBase):
                     f" but did raise <{type(e).__name__}>."
                 )
                 return cast("Self", _InertBuilder())
+            return self
+        self._return_value = result
         return self
 
     def does_not_raise(self, ex) -> Self:

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/matchers.py

@@ -512,6 +512,26 @@ class EachMatcher(BaseMatcher):
         return f"was <{value}>"
 
 
+class _MissingSentinel:
+    """Placeholder recorded for a spec key absent from the value during structural matching."""
+
+    def __repr__(self) -> str:
+        return "<missing>"
+
+
+_MISSING = _MissingSentinel()
+
+
+def _describe_spec_value(value: object) -> str:
+    """Describe a single structure-spec value (matcher, nested dict spec, or raw value)."""
+    if isinstance(value, Matcher):
+        return value.describe()
+    if isinstance(value, dict):
+        parts = [f"{key}: {_describe_spec_value(sub_value)}" for key, sub_value in value.items()]
+        return f"{{{', '.join(parts)}}}"
+    return f"<{value}>"
+
+
 class StructureMatcher(BaseMatcher):
     """Matches dicts against a structure spec where values are matchers, raw values, or nested dicts."""
 
@@ -559,16 +579,42 @@ class StructureMatcher(BaseMatcher):
                 return f"at <{current_path}>: expected <{expected}>, but was <{actual}>"
         return None
 
+    def collect_mismatches(self, value: dict) -> list[tuple[str, object, str]]:
+        """Collect every structural mismatch as ``(path, actual, expected_description)``.
+
+        Unlike :meth:`describe_mismatch`, this does not stop at the first failure and joins nested
+        paths, so callers can build a path-level :class:`~assertpy2.errors.DiffResult`.
+        """
+        return self._collect(value, self._spec, "", set())
+
+    def _collect(self, value: dict, spec: dict, path: str, seen: set[tuple[int, int]]) -> list[tuple[str, object, str]]:
+        pair_id = (id(value), id(spec))
+        if pair_id in seen:
+            return [(path or "root", "<circular ref>", "<circular ref>")]
+        seen = seen | {pair_id}
+        mismatches: list[tuple[str, object, str]] = []
+        for key, expected in spec.items():
+            current_path = f"{path}.{key}" if path else str(key)
+            if key not in value:
+                mismatches.append((current_path, _MISSING, _describe_spec_value(expected)))
+                continue
+            actual = value[key]
+            if isinstance(expected, StructureMatcher) and isinstance(actual, dict):
+                mismatches.extend(self._collect(actual, expected._spec, current_path, seen))
+            elif isinstance(expected, Matcher):
+                if not expected.matches(actual):
+                    mismatches.append((current_path, actual, expected.describe()))
+            elif isinstance(expected, dict):
+                if isinstance(actual, dict):
+                    mismatches.extend(self._collect(actual, expected, current_path, seen))
+                else:
+                    mismatches.append((current_path, actual, "a dict"))
+            elif actual != expected:
+                mismatches.append((current_path, actual, f"<{expected}>"))
+        return mismatches
+
     def _describe_spec(self, spec: dict) -> str:
-        parts = []
-        for key, value in spec.items():
-            if isinstance(value, Matcher):
-                parts.append(f"{key}: {value.describe()}")
-            elif isinstance(value, dict):
-                parts.append(f"{key}: {self._describe_spec(value)}")
-            else:
-                parts.append(f"{key}: <{value}>")
-        return f"{{{', '.join(parts)}}}"
+        return _describe_spec_value(spec)
 
 
 # --- Custom matcher registry ---

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/pytest_plugin.py

@@ -121,6 +121,11 @@ def _format_diff(diff, *, color: bool = False, max_entries: int = 50) -> str:
                 lines.append(f"  {path}:")
                 lines.append(f"    {red}- {entry.actual!r}{reset}")
                 lines.append(f"    {green}+ {entry.expected!r}{reset}")
+    elif kind == "match":
+        for entry in visible:
+            lines.append(
+                f"  {cyan}{entry.path}{reset}: expected {entry.expected}, but was {red}{entry.actual!r}{reset}"
+            )
     elif kind in {"set", "contains"}:
         extra = [e for e in visible if e.path == "extra"]
         missing = [e for e in visible if e.path == "missing"]

{assertpy2-2.6.0 → assertpy2-2.8.0}/assertpy2/warning.py

@@ -89,10 +89,12 @@ class WarningMixin(_MixinBase):
     def _when_called_with_warning(self, expected: type[Warning], *some_args, **some_kwargs) -> Self:
         with warnings.catch_warnings(record=True) as caught:
             warnings.simplefilter("always")  # bypass __warningregistry__ "show once" dedup and filterwarnings=error
-            self.val(*some_args, **some_kwargs)
+            result = self.val(*some_args, **some_kwargs)
         matched = [w for w in caught if issubclass(w.category, expected)]
         if matched:
-            return self.builder(str(matched[0].message), self.description, self.kind, logger=self.logger)
+            captured = self.builder(str(matched[0].message), self.description, self.kind, logger=self.logger)
+            captured._return_value = result
+            return captured
         if caught:
             seen = ", ".join(sorted({w.category.__name__ for w in caught}))
             self.error(
@@ -110,7 +112,7 @@ class WarningMixin(_MixinBase):
     def _when_called_with_not_warning(self, expected: type[Warning], *some_args, **some_kwargs) -> Self:
         with warnings.catch_warnings(record=True) as caught:
             warnings.simplefilter("always")  # bypass __warningregistry__ "show once" dedup and filterwarnings=error
-            self.val(*some_args, **some_kwargs)
+            result = self.val(*some_args, **some_kwargs)
         matched = [w for w in caught if issubclass(w.category, expected)]
         if matched:
             seen = ", ".join(sorted({w.category.__name__ for w in matched}))
@@ -120,4 +122,5 @@ class WarningMixin(_MixinBase):
                 f" but did warn <{seen}>."
             )
             return cast("Self", _InertBuilder())
+        self._return_value = result
         return self

{assertpy2-2.6.0 → assertpy2-2.8.0}/docs/comparison.md

@@ -82,6 +82,41 @@ The same check - `id` is a positive integer and `name` is a non-empty string - i
 
 Only assertpy2 offers both the typed structural form and the `==` form from a single import.
 
+## When it fails
+
+A nested response, after `role` comes back as `"superadmin"`. What each library prints on failure:
+
+=== "assertpy2"
+
+    ```text
+    assert_that(response).matches_structure({...})
+    --- Structured Diff ---
+    diff (match):
+      user.role: expected a value in <('admin', 'user')>, but was 'superadmin'
+    ```
+
+=== "pytest assert"
+
+    ```text
+    assert response == expected
+    E   Differing items:
+    E   {'user': {'name': 'Alice', 'role': 'superadmin', 'age': 30}} !=
+    E   {'user': {'name': 'Alice', 'role': 'admin', 'age': 30}}
+    ```
+
+=== "dirty-equals"
+
+    ```text
+    assert response == {"user": {"role": IsOneOf("admin", "user"), ...}}
+    E   Differing items:
+    E   {'user': {'name': 'Alice', 'role': 'superadmin', 'age': 30}} !=
+    E   {'user': {'name': IsStr, 'role': IsOneOf('admin', 'user'), 'age': IsInt}}
+    ```
+
+Only assertpy2 prints the path (`user.role`) and the exact predicate that failed. dirty-equals and the
+assertpy2 `==` form both hand rendering to pytest, which dumps the whole differing container for you to
+scan. The fluent form trades the zero-import convenience of `==` for a path-level diff.
+
 ## Style and typing
 
 | | pytest assert | PyHamcrest | assertpy | dirty-equals | **assertpy2** |
@@ -126,7 +161,7 @@ Only assertpy2 offers both the typed structural form and the `==` form from a si
 
 | | pytest assert | PyHamcrest | assertpy | dirty-equals | **assertpy2** |
 |---|:---:|:---:|:---:|:---:|:---:|
-| Latest release | built-in | 2.1.0 | 1.1 (2020) | 0.9.0 | **2.5.0** |
+| Latest release | built-in | 2.1.0 | 1.1 (2020) | 0.9.0 | **2.8.0** |
 | Runtime dependencies | none | none | none | none | **none on 3.11+** |
 | License | MIT | BSD | BSD | MIT | BSD-3 |
 

{assertpy2-2.6.0 → assertpy2-2.8.0}/docs/errors.md

@@ -25,6 +25,9 @@ except AssertionError as e:
     # DiffResult(kind='dict', entries=[DiffEntry(path='b', actual=2, expected=99)])
 ```
 
+Matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`) attach a `DiffResult` with
+`kind='match'`, where each entry's `expected` holds the failed predicate's description.
+
 When the pytest plugin is active (auto-registered via the `pytest11` entry point, no configuration
 needed), this data is rendered as extra report sections. See [Rich pytest diffs](#rich-pytest-diffs)
 for supported types and configuration.
@@ -45,6 +48,7 @@ rendered by the plugin as colored diff sections.
 | Pydantic model | `model` | Field-by-field via `model_dump()`, recursive into nested models |
 | other | `scalar` | Single actual-vs-expected entry |
 | `contains` family | `contains` | Missing and extra items |
+| matcher mismatch | `match` | `matches_structure()` / `satisfies()` / `each()`: path + failed predicate |
 
 ```
 --- AssertionFailure ---
@@ -61,6 +65,20 @@ Nested structures are diffed recursively and report the exact path to the differ
 `[1].name`). Circular references are detected and shown as `<circular ref>` rather than recursing
 forever.
 
+Matcher-based assertions (`matches_structure()`, `satisfies()`, `each()`) emit a `match` diff that
+shows the path and the predicate that failed, for every field, not just the first:
+
+```text
+diff (match):
+  user.name: expected a non-empty string, but was ''
+  user.role: expected a value in <('admin', 'user')>, but was 'superadmin'
+  user.age: expected a value between <18> and <120>, but was 15
+```
+
+The rich `match`/`dict` diff comes from the fluent form. The `==` drop-in for matchers (for example
+`assert response == {"id": match.is_positive()}`) hands rendering to pytest instead, which prints its
+own dict comparison without the path.
+
 ### Configuration
 
 ```toml
@@ -119,6 +137,17 @@ The category defaults to `Warning` (matches any warning) and matches subclasses.
 assert_that(safe_func).does_not_warn(DeprecationWarning).when_called_with("foo")
 ```
 
+To also assert on the value the call returned (alongside the warning, or after `does_not_warn` /
+`does_not_raise`), pivot with `returned()`:
+
+```python
+assert_that(make_client).warns(DeprecationWarning).when_called_with().returned().is_instance_of(Client)
+assert_that(adder).does_not_raise(TypeError).when_called_with(1, 2).returned().is_equal_to(3)
+```
+
+`returned()` exposes the type-agnostic core assertions (`is_equal_to`, `is_instance_of`, `satisfies`,
+...); it raises `TypeError` if the call raised (there is no return value to inspect).
+
 !!! warning "Not thread-safe"
     `warns()` / `does_not_warn()` rely on `warnings.catch_warnings()`, which mutates process-global
     state. They are safe within a single thread (including multiple `asyncio` tasks on one event

{assertpy2-2.6.0 → assertpy2-2.8.0}/docs/getting-started.md

@@ -35,6 +35,21 @@ assert_that(5).is_greater_than(10)
 # AssertionError: Expected <5> to be greater than <10>, but was not.
 ```
 
+For dicts, dataclasses, and other structures, the pytest plugin renders a path-level diff that points
+straight at the differing field instead of dumping the whole value:
+
+```text
+assert_that(actual).is_equal_to(expected)
+--- Structured Diff ---
+diff (dict):
+  user.role:
+    - 'superadmin'
+    + 'admin'
+```
+
+The same path-level diff backs `matches_structure()`, `satisfies()`, and `each()`. See
+[Errors & Reporting](errors.md) for the full diff format and configuration.
+
 ## Collect multiple failures
 
 Use soft assertions to report every failure at once instead of stopping at the first:

{assertpy2-2.6.0 → assertpy2-2.8.0}/docs/index.md

@@ -12,7 +12,7 @@ rich structural diffs on failure.
   accurate autocomplete and type checkers catch misuse. This is the core advantage over `assertpy` and
   most alternatives.
 - **Composable matchers.** `match.greater_than(5)`, `match.is_uuid()`, combined with `&`, `|`, `~`.
-- **Structural matching.** Declarative validation of dicts and API responses.
+- **Structural matching.** Declarative validation of dicts and API responses, with the exact path to each mismatch on failure.
 - **Soft and async assertions.** Collect multiple failures; poll for eventual consistency with `eventually()`.
 - **Structured failures.** `AssertionFailure` exposes `.actual`, `.expected`, and `.diff`; the pytest plugin
   renders recursive diffs for lists, dicts, dataclasses, namedtuples, and Pydantic models.
@@ -37,5 +37,14 @@ assert_that({"id": 1, "name": "Alice"}).matches_structure(
 )
 ```
 
+When a check fails, the pytest plugin points at the exact field instead of dumping both structures:
+
+```text
+assert_that(response).matches_structure({...})
+--- Structured Diff ---
+diff (match):
+  user.role: expected a value in <('admin', 'user')>, but was 'superadmin'
+```
+
 See [Getting Started](getting-started.md) to dive in, or browse [Type Assertions](assertions.md),
 [Matchers](matchers.md), and the rest of the navigation for the full set of assertions and integrations.