2.12.0

TL;DR

Added	What it gives you
is_equal_to(tolerance=, comparators=)	Float tolerance and custom comparators anywhere in nested equality; ignore/include now also take re.Pattern / type
all_fields_satisfy(), has_no_none_fields()	One matcher or callable applied to every scalar leaf of an object graph
satisfies_exactly(), zip_satisfies(), contains_only_once(), has_same_size_as()	Positional, pairwise, once-only, and size-parity iterable assertions

Recursive comparison configuration on is_equal_to

is_equal_to() gains tolerance (absolute, applied to every real-number leaf at any depth) and comparators (keyed by a type or a field name, mapping to an (actual, expected) -> bool predicate); ignore/include now also accept a re.Pattern (matched against field names) and a type (matched against field values). Tolerated or comparator-equal leaves appear in neither the message nor the diff.

Guide: Recursive comparison (tolerance / comparators)

Before - nested floats never compare equal under ==, and there was no way to apply a tolerance to a leaf inside a structure:

assert_that({"point": {"x": 0.1 + 0.2}}).is_equal_to({"point": {"x": 0.3}})

Expected <{'point': {'x': 0.30000000000000004}}> to be equal to <{'point': {'x': 0.3}}>, but was not.
diff (dict):
  point.x:
    - 0.30000000000000004
    + 0.3

Now - an absolute tolerance settles float drift anywhere in the graph, comparators apply custom equality per type or field, and ignore drops volatile fields:

assert_that({"point": {"x": 0.1 + 0.2}}).is_equal_to({"point": {"x": 0.3}}, tolerance=1e-9)
assert_that(order).is_equal_to(expected, comparators={"name": lambda actual, expected: actual.lower() == expected.lower()})

import re
assert_that(payload).is_equal_to(expected, ignore=[re.compile(r"^_"), float])

Recursive leaf assertions

all_fields_satisfy() applies one matcher or callable to every scalar leaf of an object graph (mappings, dataclasses, namedtuples, Pydantic models, lists, tuples), reporting the path of each leaf that fails. has_no_none_fields() is the common special case.

Guide: Recursive field assertions

Before - no recursive leaf assertion; you walked the structure by hand and asserted field by field.

Now:

assert_that({"a": 1, "nested": {"b": 2}}).all_fields_satisfy(match.is_positive())
assert_that({"id": 1, "profile": {"name": "Alice"}}).has_no_none_fields()

assert_that({"a": 1, "b": {"c": -2}}).all_fields_satisfy(match.is_positive())

Expected all fields to satisfy a positive value, but 1 field did not.
diff (match):
  b.c: expected a positive value, but was -2

Iterable-assertion cluster

Four positional/pairwise iterable assertions: satisfies_exactly() (the i-th item satisfies the i-th matcher, lengths must match), zip_satisfies() (a two-arg predicate over items zipped with another iterable), contains_only_once() (each given item occurs exactly once), and has_same_size_as() (length parity with another sized object).

Guide: Lists & iterables

Before - none of these existed.

Now:

assert_that([1, "foo", 3.0]).satisfies_exactly(match.is_odd(), match.is_instance_of(str), match.is_positive())
assert_that([1, 2, 3]).zip_satisfies([2, 4, 6], lambda actual, other: other == actual * 2)
assert_that([1, 2, 3]).contains_only_once(1, 3)
assert_that([1, 2, 3]).has_same_size_as(("a", "b", "c"))

Every failure is reported at the element path, for example:

Expected items to satisfy the given matchers in order, but 1 item did not.
diff (match):
  [1]: expected an instance of <int>, but was 'foo'

Expected <[1, 2, 2, 3]> to contain <2> only once, but contained <2> more than once.

Documentation

• New generated API reference (mkdocstrings) covering every assertion, matcher, and entry point.
• Documentation site restructured into Introduction / Getting started / Guides / Concepts / Extending / Reference, with improved dark-mode contrast and a landing-page grid.

Internal

• Mutation-testing matrix (cosmic-ray) expanded across more modules; coverage hardened against surviving mutants.
• Dependency floors refreshed.

2.11.0

Added

• Pandas / polars / numpy data-frame and array assertions.

  Fluent equality for pandas/polars DataFrame/Series (is_frame_equal) and numpy arrays (is_array_equal, is_array_close_to), delegating comparison semantics to each library's own assert_frame_equal / assert_allclose and carrying its diff on failure. Optional extra: pip install assertpy2[pandas] (or [polars], [numpy], [data]).

  Before:

  AttributeError: assertpy has no assertion <is_frame_equal()>
  

  Now:

  assert_that(df).is_frame_equal(expected, check_dtype=False)
  assert_that(arr).is_array_close_to(expected, rtol=1e-3)

Improved

• Richer dict diffs.

  A failing is_equal_to() on a dict now decomposes nested dataclasses, models, namedtuples and nested lists to the exact differing path (matching the detail already shown for top-level values), and dicts with mixed-type keys no longer raise.

  @dataclass
  class Point:
      x: int
      y: int
  
  assert_that({"point": Point(1, 2)}).is_equal_to({"point": Point(1, 3)})

  Before - the nested object was reported as one leaf:

  point:
    - Point(x=1, y=2)
    + Point(x=1, y=3)
  

  Now - decomposed to the exact differing path:

  point.y:
    - 2
    + 3
  

Fixed

• Clear error when comparing array/frame-likes.
  is_equal_to() / is_not_equal_to() on a numpy array or pandas/polars frame now raise a clear, actionable TypeError instead of the library's cryptic "ambiguous truth value".

  assert_that(df).is_equal_to(other)

  Before:

  ValueError: The truth value of a DataFrame is ambiguous. Use a.empty, a.bool(), ...
  

  Now:

  TypeError: is_equal_to() cannot directly compare <DataFrame>: its '==' is element-wise
  and has no single truth value. Compare the value's own equality (e.g.
  assert_that(actual.equals(expected)).is_true()), assert on extracted scalars
  (columns, shape, length), or use satisfies(...) with an explicit predicate.
  

Internal

• Restructured the README integrations section (compact, linked) and added a data-frame row to the comparison table.
• Bumped dev type-checker ty to 0.0.55; renamed a snapshot test off a dev-phase name.

2.10.0

Added

• Pydantic v2 models in structural matching.
  matches_structure(), satisfies(match.structure(...)), each(...), and the == form now accept a Pydantic model directly (via model_dump()) and report a path-level diff. Previously a model raised TypeError: val must be a dict - you had to call .model_dump() yourself.

  class User(BaseModel):
      name: str
      role: str
  
  user = User(name="Alice", role="superadmin")
  
  # Before 2.10.0:  assert_that(user.model_dump()).matches_structure({...})   # TypeError otherwise
  # Now:
  assert_that(user).matches_structure({"role": match.is_in("admin", "user")})
  # diff (match):
  #   role: expected a value in <('admin', 'user')>, but was 'superadmin'

• Pydantic v2 models in extracting().
  Pull attributes straight off model instances. Previously a list of models raised TypeError: item <User> does not have [] accessor (models are iterable but not subscriptable).

  users = [User(name="Alice", role="admin"), User(name="Bob", role="editor")]
  
  assert_that(users).extracting("name").contains("Alice", "Bob")
  assert_that(users).extracting("name", "role").is_equal_to(
      [("Alice", "admin"), ("Bob", "editor")]
  )

Improved

• Richer nested diffs.
  Nested sequences and dataclass fields are now decomposed to the exact differing path, matching the detail already shown at the top level.

  @dataclass
  class Matrix:
      rows: list[list[int]]
  
  assert_that(Matrix([[1, 2], [3, 4]])).is_equal_to(Matrix([[1, 2], [3, 9]]))
  
  # Before 2.10.0 - the whole nested list was one leaf:
  #   .rows:
  #     - [[1, 2], [3, 4]]
  #     + [[1, 2], [3, 9]]
  #
  # Now - decomposed to the exact index:
  #   .rows[1][1]:
  #     - 4
  #     + 9

Internal

• Mutation-testing gaps closed.
  Hardened the rich-diff ordering guards and file.is_named.
• Tooling and docs.
  Refreshed diff screenshots and docs; bumped dev type-checker ty to 0.0.54.

v2.9.1

Fixed

match.structure() no longer reports a false circular reference when the same nested instance is reused under sibling keys.

When a spec or value shared one sub-object instance across two keys (a DAG, not a cycle), matches() - and with it satisfies(match.structure(...)), each(...), and the == form - failed incorrectly. matches_structure() was unaffected. The matcher now scopes its visited-set per path, so shared sub-objects match while genuine cycles are still detected.

Internal

The structure matcher's two parallel traversals were merged into one, with no behavior change beyond the fix.
Plus documentation and test-suite housekeeping. No public API changes.

v2.9.0

Added

is_equal_to(..., ignore=) and include= now accept set and frozenset.
Selective field comparison previously required a list or tuple of keys; sets now work too:

assert_that(actual).is_equal_to(expected, ignore={"created_at", "id"})

Date assertions accept datetime subclasses.
is_before, is_after, is_equal_to_ignoring_*, and is_close_to now treat instances of datetime subclasses (e.g. third-party datetime libraries and test fakes) as valid datetimes instead of rejecting them on an exact-type check.

Fixed

is_subset_of() against a single-key superset dict raised KeyError instead of a clean assertion.
A value mismatch against a one-entry mapping crashed while formatting the failure message; it now reports the mismatch normally.

is_divisible_by() matcher rejects a zero divisor with a clear ValueError instead of failing with ZeroDivisionError at match time.

Parallel-safe snapshots. Snapshot writes are serialized with a file lock and the snapshot directory is created race-free, so parallel test runs no longer collide on snapshot files.

eventually() awaits awaitables returned by synchronous callables, so a plain function that returns a coroutine is handled correctly.

Plus smaller correctness fixes: is_child_of path-boundary check, is_between range-type error message, length matchers on non-Sized values, structural-match headline paths, the allure diff-entry cap, single-item contains diffs, and several failure-message wording fixes.

Internal

Test-suite hardening driven by mutation testing (cosmic-ray) closed real gaps across the date, collection, matchers, bytes, dict, numeric, and string assertions. A weekly mutation-testing workflow and a typed-overload cross-check (ty + mypy --strict + pyright over assert_that) were added to CI. Plus shared-helper refactors (dict-like checks, datetime formatting, collection guards) and dependency bumps. No public API changes beyond the above.

v2.8.1

Fixed

starts_with() and ends_with() now accept generators. Calling either on a generator or any other non-Sized iterable previously raised TypeError from an internal len() check. They now consume the iterable correctly, matching the documented "string or iterable" contract:

assert_that(x for x in [1, 2, 3]).starts_with(1)  # previously raised TypeError

Internal

Type-checker alignment with no public API or behavior change: assert_that's overload implementation is annotated against the shared base protocol (clearing the overload-consistency diagnostics), structure-matcher dict parameters are now parameterized, and the value matchers return an explicit bool. The comparison docs were rebalanced - table emphasis and trimmed slogans.

v2.8.0

What's new

Path-level diffs for matcher assertions. When matches_structure(), satisfies(), or each() fail, the pytest plugin now renders a structured match diff pointing at the exact path of every failing field and the predicate that failed - not just the first mismatch:

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

Previously these assertions raised a plain AssertionError with no structured diff. They now attach structured failure data (.actual / .expected / .diff with kind="match"), so the breakdown also flows into Allure attachments.

Docs

Failure output is now shown throughout the docs - landing page, README, comparison, matchers, errors, and getting started - including a side-by-side "when it fails" comparison against plain pytest and dirty-equals.

Compatibility

Backward compatible: failure messages are unchanged, AssertionFailure stays an AssertionError subclass, no API changes. Python 3.10+.

v2.7.0

New

• returned() pivots a callable assertion onto the value the call returned. Use it after warns(), does_not_warn(), or does_not_raise() to assert on the return value in the same chain:
  assert_that(make_client).warns(DeprecationWarning).when_called_with().returned().is_instance_of(Client). It raises TypeError if the call raised (no return value to inspect).

Improved

• when_called_with() is now typed to return a string assertion, so chaining .matches() / .starts_with() on a captured exception or warning message type-checks (it already worked at runtime).
• Corrected the internal builder() type stub (expected is type[BaseException] | None).
• Added Hypothesis property-based tests (dev-only) covering equality, ignore/include (incl. nested paths and dataclasses/namedtuples), collection multiset/ordering semantics, and matcher algebra.

v2.6.0

New

• warns() / does_not_warn() for callables: assert that calling a function emits (or does not emit) a warning, mirroring raises() / does_not_raise(). On success the matched warning message becomes the new value, so you can chain assertions on it, e.g. assert_that(func).warns(DeprecationWarning).when_called_with(x).matches("since 2.6").
• The expected category defaults to Warning (matches any warning) and matches subclasses. Unlike pytest.warns, DeprecationWarning / PendingDeprecationWarning are captured by default.

Notes

• warns() / does_not_warn() are safe within a single thread (including asyncio tasks on one event loop), but not across OS threads - the same limitation as pytest.warns.

v2.5.1

Packaging

• typing_extensions is now installed only on Python 3.10. assertpy2 has no runtime dependencies on Python 3.11+.

Fixed

• assertpy2.__version__ now reports the installed version (it was stale at 2.4.0).

Documentation

• New documentation site: https://solganis.github.io/assertpy2/ - hand-written guides for assertions, matchers, the fluent API, testing, errors, extending and integrations, plus dedicated comparison and migration pages.