Fully typed fluent assertion library for Python
A modern, batteries-included fork of assertpy

---

Quick start

pip install assertpy2  # drop-in replacement for assertpy, just change the import

from assertpy2 import assert_that

def test_user():
    user = {"name": "Alice", "age": 30, "roles": ["viewer", "editor"]}

    assert_that(user).contains_key("name", "age")
    assert_that(user).contains_entry({"name": "Alice"})
    assert_that(user["age"]).is_between(18, 120)
    assert_that(user["roles"]).contains("viewer").does_not_contain("admin")

The full documentation covers every assertion, matcher, and integration.

Failures that point at the difference A recursive diff names the exact path that differs, in color, instead of dumping both structures.	Type-aware autocomplete assert_that() returns a protocol per value type, so your IDE offers the methods that fit.
Typed narrowing An assertion hands the value back statically narrowed, with no cast and no bare assert.	Composable matchers 45 matchers that combine with &, |, ~ and nest inside the expected structure itself.
Built for test suites Soft assertions, polling for eventual consistency, snapshots, and expected-exception chains.	Integrations Allure, Behave, JSON Path and Schema, pandas, polars, numpy, and OpenAPI response contracts.

Why fluent assertions?

assert states a condition well. pytest reports it well.

What it cannot say is where two structures differ. It prints both and leaves the reading to you:

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 names the exact path, in color:

assert_that(response).is_equal_to(expected)

It recurses through nested containers. Matcher predicates get the same treatment.

For dynamic fields like IDs, assert a subset with matches_structure().

The chain is the other half. Your IDE offers only the methods that fit the value.

assert_that(items).is_instance_of(list).is_length(3).contains("admin")

Matchers are ordinary values that answer ==, the way unittest.mock.ANY does.

Nothing is patched, so a matcher can sit inside the expected structure at any depth:

response = {"id": 7, "user": {"name": "Alice", "age": 30}, "tags": ["a", "b"]}

assert_that(response).is_equal_to(
    {
        "id": match.greater_than(0),
        "user": {"name": "Alice", "age": match.between(18, 120)},
        "tags": ["a", "b"],
    }
)

# or keep the bare `assert`, and pytest's own rewriting reports it
assert response == {
    "id": match.greater_than(0),
    "user": match.ignore(),
    "tags": ["a", "b"],
}

The fluent form keeps the path-level diff, the bare form keeps pytest's.

There are 45 matchers, combining with &, | and ~.

Type-aware autocomplete

assert_that() uses @overload to return type-specific Protocols.
Your IDE shows only methods relevant to the value you're testing, not the whole surface:

• assert_that("hello"). → string methods: starts_with, matches, is_alpha, ...
• assert_that(42). → numeric methods: is_positive, is_between, is_close_to, ...
• assert_that(Path("/tmp")). → path methods: exists, is_file, is_readable, ...
• assert_that(my_dict). → dict methods: contains_key, contains_entry, has_json_path, ...
• assert_that(b"\x89PNG"). → bytes methods: starts_with_bytes, is_valid_utf8, decoded_as, ...

15 type-specific Protocols instead of one Any.
Works in PyCharm, VS Code, and any editor that runs a type checker.

Typed narrowing

An assertion hands the value back, statically narrowed.

is_not_none() strips None, is_instance_of() narrows to the class, and .value returns it:

order = assert_that(repo.find(42)).is_not_none().is_instance_of(PaidOrder).value
order.refund()  # statically PaidOrder - verified by ty, mypy, pyright and pyrefly

For API tests, assert_conforms() validates a payload against a Pydantic model and narrows to it. exact=True catches contract drift:

data = assert_conforms(response.json(), OrderModel).value  # data: OrderModel

A failure you can read from code

An exception is the right default. Reading the result means catching it.

check() runs the next assertion for its verdict instead:

response = {"user": {"name": "Alice", "role": "superadmin"}, "status": "active"}
expected = {"user": {"name": "Alice", "role": "admin"}, "status": "active"}

outcome = assert_that(response).check().is_equal_to(expected)

if not outcome and outcome.diff:
    print(outcome.diff.entries[0].path)  # user.role

It is truthy when the assertion held. When it did not, it carries .message, .actual, .expected and a walkable .diff. So does AssertionFailure.

So a reporter reads structure instead of parsing a string. That is how the Allure integration works. Anything else you build can too.

Features

Fluent API

• Structural matching: matches_structure() for declarative dict/API-response validation.
• Recursive field assertions: all_fields_satisfy() / has_no_none_fields() apply a predicate to every leaf of an object graph.
• Universal negation: .not_ inverts any assertion, no dedicated is_not_* methods.
• Collection pipeline: filtered_on(), mapped(), flat_mapped(), first(), last(), element(), single().
• Positional & pairwise checks: satisfies_exactly(), zip_satisfies(), contains_only_once(), has_same_size_as(), plus *_in_any_order variants.

Type safety

• Refinement predicates: satisfies() takes a TypeIs predicate, so a domain check narrows the chain too.
• Contract testing: assert_conforms() validates a raw payload against a Pydantic model and narrows to it. exact=True catches contract drift, each=True validates list endpoints.

Built-in types

• Strings, numbers, lists, tuples, sets, dicts, dates, booleans, objects, bytes, files, exceptions.
• Bytes assertions: is_valid_utf8(), starts_with_bytes(), is_hex_equal_to(), decoded_as() for bytes/bytearray.
• Dynamic assertions: has_<name>() for any attribute, property, or zero-argument method.
• Dict comparison: is_equal_to(ignore=..., include=...) for selective key/field matching by name, regex, or type.
• Recursive comparison: is_equal_to() with tolerance, comparators, or ignore_null for nested structures.
• Extracting: flatten collections on attributes with filter and sort support.
• Regex group extraction: extracting_group() and matches_with_groups() for regex captures.

Testing

• Soft assertions: thread-safe and async-safe via contextvars, each failure reported with its file:line. Group with sa.group() or assert_all().
• Polling assertions: eventually() (async) / eventually_sync() (blocking) retry for eventual consistency, with a convergence trace on timeout.
• Expected exceptions: raises().when_called_with(), walk the cause chain (caused_by(), has_root_cause()), search an ExceptionGroup (contains_error(), errors(), error_of()), or pivot to the object (raised()).
• HTTP responses: assert on the response itself and every failure names the request it came from, with decoded_as_json() to step into the body. No client library is a dependency.
• Snapshot testing: an external JSON file, an inline value recorded into the test source, or a value-tolerant contract, all updated with --assertpy2-snapshot-update.
• OpenAPI response contracts: conforms_to_openapi() checks a JSON body against an operation's response schema, reporting every violation with its JSON path.

Failure reporting

• Structured errors: AssertionFailure carries .actual, .expected and .diff, and the diff renders into the message, so it shows off pytest too.
• Assertions as values: check() runs the next assertion for its verdict instead of raising, handing back an AssertionOutcome.
• Rich pytest diffs: recursive diffs across containers, dataclasses, attrs and Pydantic models, with intra-line carets for strings.

Plugin for pytest

Set from the command line or from [tool.pytest.ini_options], not from a call.

• Failure clustering: forty failing tests are usually not forty problems. Where three or more differ at the same place, the run ends with a line saying where. On by default, assertpy2_failure_clusters = "off" turns it off.
• Diagnostic profiles: assertpy2_profile turns the guards below on in one line. compatible (default) leaves them off, safe warns, strict fails the tests they find. A setting you name yourself still wins.
• Vacuous-assertion guard: --assertpy2-vacuous warns when a universal assertion passes over an empty collection, having checked nothing.
• Dangling-assertion detector: --assertpy2-dangling warns when a chain builds an assertion and never runs it. assert assert_that(x).is_positive passes on any value, and neither ruff nor coverage sees it.

Extensibility

• Custom matchers: register_matcher() composes existing ones, BaseMatcher carries its own predicate. Both compose with &, |, ~.
• Custom assertions: add_extension() adds a method to the builder.

Integrations

• Allure (pip install assertpy2[allure]): the pytest plugin auto-attaches structured diff and actual/expected data to Allure reports, in three configurable modes.
• Behave (pip install assertpy2[behave]): ready-made parameter types (PositiveInt, NonEmptyString, ...) for step definitions like {age:PositiveInt}.
• JSON (pip install assertpy2[json]): JSONPath navigation (at_json_path(), has_json_path()) and JSON Schema validation (matches_json_schema()).
• Data frames (pip install assertpy2[pandas] / [polars] / [numpy]): fluent equality for pandas/polars frames and numpy arrays, carrying each library's own diff.

---

BSD 3-Clause License