assertpy2 2.27.0

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.

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