NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #4405 most downloaded on PyPI
Fluent, fully typed assertion library for Python: your type checker sees only the assertions that fit the value, and every failure carries a structured diff. Soft assertions, polling, inline snapshots, OpenAPI contracts.
Latest stable
2.36.0
Last release 17 days ago
05 Nov 2026
Ships unpredictably
gaps range from 3 weeks to 6.3 years
Nearly every release is documented
notes for 14 of 15 stable releases
Nothing withdrawn
no release was ever pulled
12 years old
15 releases · first in 2015
Drag across the ruler to compare, or tap a release to open it.
Read Behaviour changes below before upgrading
Read Behaviour changes below before upgrading
| New | |
|---|---|
is_html_equal_to() and match.html_equal_to() |
compare two HTML strings as trees: attribute order, quotes, case and indentation do not count (#140) |
assertpy_snapshot_layout = beside |
keeps each snapshot beside its test file, so test files of one name in two folders get one each (#88) |
| Passed when it should not have | |
|---|---|
assert_conforms(exact=True) over a union of TypedDict that read a field by its alias, the field's own name sent beside it |
passed, the name taken as read |
assert_conforms(exact=True) over a TypedDict or a pydantic dataclass that keeps extras, the same payload, under pydantic 2.14.2 and later |
passed, pydantic ignores the name since 2.14.2 where it put it over the field before |
| Failed when it should have passed | |
|---|---|
snapshot() of a value holding a tuple, such as mock.method_calls |
failed on every run after the first, the tuple read back as a list (#121) |
| Crashed or misreported | |
|---|---|
--assertpy-snapshot-update with one snapshot file reached as path="snaps" and as path="./snaps" |
reported the keys of each spelling as obsolete under the other and removed them all, the file with them |
| The test suite run from the sdist | failed: ARCHITECTURE.md, pyrefly.toml and .github/workflows/ci.yml were not in it (#164) |
| Typing: accepted now, and refused before | |
|---|---|
snapshot(path=None) and matches_contract_snapshot(path=None) |
path is str | None, and None is the place a snapshot without path= goes |
is_html_equal_to() compares HTML as treeshtml = '<ul class="menu nav">\n <li><a href="/">Home</a></li>\n</ul>'
assert_that(html).is_html_equal_to("<ul class='nav menu'><li><a href='/'>Home</a></li></ul>") # 1
assert_that(html).is_html_equal_to("<ul class='nav menu'><li><a href='/home'>Home</a></li></ul>") # 2
assert_that({"body": html}).matches_structure({"body": match.html_equal_to("<ul class='nav menu'><li><a href='/'>Home</a></li></ul>")}) # 3
Before
1: AttributeError: assertpy has no assertion <is_html_equal_to()>
2: AttributeError: assertpy has no assertion <is_html_equal_to()>
3: AttributeError: match has no matcher 'html_equal_to'
Now
1: passed
2: AssertionFailure: Expected <.., line 3: <a href="/">"Home"</a>, ..> to be equal to <.., line 3: <a href="/home">"Home"</a>, ..> as HTML, but was not.
diff (string):
line 3:
- <a href="/">"Home"</a>
+ <a href="/home">"Home"</a>
? ++++
3: passed
whitespace="lenient" reads text as Django's assertHTMLEqual does, "exact" compares it as writtenhtml.parserValueErrorGuide: HTML
# tests/api/test_users.py
def test_user():
assert_that({"source": "api"}).snapshot()
# tests/ui/test_users.py
def test_user():
assert_that({"source": "ui"}).snapshot()
Before
1 failed, 1 passed
AssertionFailure: Expected <{'source': 'ui'}> to be equal to <{'source': 'api'}>, but was not.
Now, with assertpy_snapshot_layout = beside in the pytest settings
2 passed
tests/api/__snapshots/snap-test_users.json
tests/ui/__snapshots/snap-test_users.json
cwd, keeps __snapshots in the working directory through 2.xbeside, a call written in no file on disk, such as code compiled from a string, needs path=Guide: Where snapshots are kept
@patch("sys.stdout")
def test_prints(stdout):
print("Something")
assert_that(stdout.method_calls).snapshot()
Before
first run: passed
second run: AssertionFailure: Expected <[call.write('Something'), call.write('\n')]> to be equal to <[['write', ['Something'], {}], ['write', ['\n'], {}]]>, but was not.
Now
first run: passed
second run: passed
tuple, such as a named tuple or mock.call, comes back a plain tuple that compares equalregister_snapshot_serializer() brings the class backGuide: Custom types, Known limitations
exact=True names a field's name sent beside its alias in a unionclass Person(TypedDict):
first: Annotated[str, Field(alias="firstName")]
class Other(TypedDict):
first: Annotated[str, Field(alias="firstName")]
class Envelope(BaseModel):
person: Person | Other
assert_conforms({"person": {"first": "Ann", "firstName": "Bob"}}, Envelope, exact=True)
Before
passed
Now
AssertionFailure: Expected <{'person': {'first': 'Ann', 'firstName': 'Bob'}}> to conform exactly to <Envelope>, but it carries 1 undeclared field(s) the model does not declare: ['person.first']
<person.first> is not read: its field was read from <firstName>
diff (match):
person.first: - 'Ann'
TypedDict was checked right before, a union of them was notTypedDict or a pydantic dataclass that keeps extras fails the same way since pydantic 2.14.2Guide: Contract drift with exact=True
| A snapshot holding a tuple | is written as a tagged list, which assertpy 2.35 and earlier read as a dict and fail on<br>A tuple they stored as a list still compares as a list until rewritten under --assertpy-snapshot-update |
register_snapshot_serializer() |
is asked for subclasses of tuple, list, dict and str, for dict keys and for set members, and a serializer matching one now writes it |
snapshot(path=None) and matches_contract_snapshot(path=None) |
keep the snapshot where a call without path= keeps it<br>They raised ValueError |
| Writing a snapshot, and reading one that holds a tagged value or text outside ASCII | takes about 1 ms more per 2 000 records |
Guide: Snapshot testing
v* release tagsYour coding agent can read these notes before it upgrades. Set up the MCP server →
Read Behaviour changes below before upgrading
| New | |
|---|---|
is_html_equal_to() and match.html_equal_to() |
compare two HTML strings as trees: attribute order, quotes, case and indentation do not count (#140) |
assertpy_snapshot_layout = beside |
keeps each snapshot beside its test file, so test files of one name in two folders get one each (#88) |
| Passed when it should not have | |
|---|---|
assert_conforms(exact=True) over a union of TypedDict that read a field by its alias, the field's own name sent beside it |
passed, the name taken as read |
assert_conforms(exact=True) over a TypedDict or a pydantic dataclass that keeps extras, the same payload, under pydantic 2.14.2 and later |
passed, pydantic ignores the name since 2.14.2 where it put it over the field before |
| Failed when it should have passed | |
|---|---|
snapshot() of a value holding a tuple, such as mock.method_calls |
failed on every run after the first, the tuple read back as a list (#121) |
| Crashed or misreported | |
|---|---|
--assertpy-snapshot-update with one snapshot file reached as path="snaps" and as path="./snaps" |
reported the keys of each spelling as obsolete under the other and removed them all, the file with them |
| The test suite run from the sdist | failed: ARCHITECTURE.md, pyrefly.toml and .github/workflows/ci.yml were not in it (#164) |
| Typing: accepted now, and refused before | |
|---|---|
snapshot(path=None) and matches_contract_snapshot(path=None) |
path is str | None, and None is the place a snapshot without path= goes |
is_html_equal_to() compares HTML as treeshtml = '<ul class="menu nav">\n <li><a href="/">Home</a></li>\n</ul>'
assert_that(html).is_html_equal_to("<ul class='nav menu'><li><a href='/'>Home</a></li></ul>") # 1
assert_that(html).is_html_equal_to("<ul class='nav menu'><li><a href='/home'>Home</a></li></ul>") # 2
assert_that({"body": html}).matches_structure({"body": match.html_equal_to("<ul class='nav menu'><li><a href='/'>Home</a></li></ul>")}) # 3Before
1: AttributeError: assertpy has no assertion <is_html_equal_to()>
2: AttributeError: assertpy has no assertion <is_html_equal_to()>
3: AttributeError: match has no matcher 'html_equal_to'
Now
1: passed
2: AssertionFailure: Expected <.., line 3: <a href="/">"Home"</a>, ..> to be equal to <.., line 3: <a href="/home">"Home"</a>, ..> as HTML, but was not.
diff (string):
line 3:
- <a href="/">"Home"</a>
+ <a href="/home">"Home"</a>
? ++++
3: passed
whitespace="lenient" reads text as Django's assertHTMLEqual does, "exact" compares it as writtenhtml.parserValueErrorGuide: HTML
# tests/api/test_users.py
def test_user():
assert_that({"source": "api"}).snapshot()
# tests/ui/test_users.py
def test_user():
assert_that({"source": "ui"}).snapshot()Before
1 failed, 1 passed
AssertionFailure: Expected <{'source': 'ui'}> to be equal to <{'source': 'api'}>, but was not.
Now, with assertpy_snapshot_layout = beside in the pytest settings
2 passed
tests/api/__snapshots/snap-test_users.json
tests/ui/__snapshots/snap-test_users.json
cwd, keeps __snapshots in the working directory through 2.xbeside, a call written in no file on disk, such as code compiled from a string, needs path=Guide: Where snapshots are kept
@patch("sys.stdout")
def test_prints(stdout):
print("Something")
assert_that(stdout.method_calls).snapshot()Before
first run: passed
second run: AssertionFailure: Expected <[call.write('Something'), call.write('\n')]> to be equal to <[['write', ['Something'], {}], ['write', ['\n'], {}]]>, but was not.
Now
first run: passed
second run: passed
tuple, such as a named tuple or mock.call, comes back a plain tuple that compares equalregister_snapshot_serializer() brings the class backGuide: Custom types, Known limitations
exact=True names a field's name sent beside its alias in a unionclass Person(TypedDict):
first: Annotated[str, Field(alias="firstName")]
class Other(TypedDict):
first: Annotated[str, Field(alias="firstName")]
class Envelope(BaseModel):
person: Person | Other
assert_conforms({"person": {"first": "Ann", "firstName": "Bob"}}, Envelope, exact=True)Before
passed
Now
AssertionFailure: Expected <{'person': {'first': 'Ann', 'firstName': 'Bob'}}> to conform exactly to <Envelope>, but it carries 1 undeclared field(s) the model does not declare: ['person.first']
<person.first> is not read: its field was read from <firstName>
diff (match):
person.first: - 'Ann'
TypedDict was checked right before, a union of them was notTypedDict or a pydantic dataclass that keeps extras fails the same way since pydantic 2.14.2Guide: Contract drift with exact=True
| A snapshot holding a tuple | is written as a tagged list, which assertpy 2.35 and earlier read as a dict and fail on A tuple they stored as a list still compares as a list until rewritten under --assertpy-snapshot-update |
register_snapshot_serializer() |
is asked for subclasses of tuple, list, dict and str, for dict keys and for set members, and a serializer matching one now writes it |
snapshot(path=None) and matches_contract_snapshot(path=None) |
keep the snapshot where a call without path= keeps itThey raised ValueError |
| Writing a snapshot, and reading one that holds a tagged value or text outside ASCII | takes about 1 ms more per 2 000 records |
Guide: Snapshot testing
v* release tagsassertpy 2.35.0 is the typed rewrite published until now as assertpy2, released under the original name: the first assertpy release since 1.1 in 2020
assertpy 2.35.0 is the typed rewrite published until now as assertpy2, released under the original name: the first assertpy release since 1.1 in 2020
A major release. On 1.1 your imports stay the same, but some results, extensions and messages change
Thanks to Justin Shacklette for handing over the name, and to everyone who contributed to 1.x
| You use | What to do |
|---|---|
assertpy 1.1, upgrading |
Read Upgrading from assertpy 1.x, remove types-assertpy, run your tests |
assertpy 1.1, staying |
Pin assertpy<2. The 1.x source is on the v1.x branch |
assertpy2 |
Switch the dependency and imports to assertpy. assertpy2 2.35.0 keeps old imports working meanwhile |
The same assert_that(...) chain, plus:
==A major release, so some things change:
assert_that(float("nan")).is_greater_than(1)
Before (1.1)
passed
Now
AssertionFailure: Expected <nan> to be greater than <1>, but was not.
bool in is_close_to(), and moreadd_extension() refuses a taken name without override=TrueAssertionFailure, a subclass of AssertionErrortypes-assertpy: it describes 1.1 and hides the 2.x typesGuide: Upgrading from assertpy 1.x
- assertpy2[json]
+ assertpy[json]
- from assertpy2 import assert_that
+ from assertpy import assert_that
Old flags, settings and environment variables still work, with a warning:
$ pytest --assertpy2-snapshot-update
FutureWarning: --assertpy2-snapshot-update is the assertpy2 name of --assertpy-snapshot-update. It keeps working until assertpy 3.0, use --assertpy-snapshot-update instead.
2: --assertpy-snapshot-update, assertpy_diff, ASSERTPY_SNAPSHOT_CI. Old ones go in 3.0ignore:.*is the assertpy2 name of:FutureWarning# assertpy2: allow-dangling is still readGuide: Coming from assertpy2
assertpy2 |
assertpy |
|
|---|---|---|
assert_warn() default logger |
assertpy2 |
assertpy |
log_passes() logger |
assertpy2.passes |
assertpy.passes |
| pytest plugin name | -p no:assertpy2 |
-p no:assertpy |
assertpy 2.35.0 is the typed rewrite published until now as assertpy2, released under the original name: the first assertpy release since 1.1 in 2020
A major release. On 1.1 your imports stay the same, but some results, extensions and messages change
Thanks to Justin Shacklette for handing over the name, and to everyone who contributed to 1.x
| You use | What to do |
|---|---|
assertpy 1.1, upgrading |
Read Upgrading from assertpy 1.x, remove types-assertpy, run your tests |
assertpy 1.1, staying |
Pin assertpy<2. The 1.x source is on the v1.x branch |
assertpy2 |
Switch the dependency and imports to assertpy. assertpy2 2.35.0 keeps old imports working meanwhile |
The same assert_that(...) chain, plus:
==A major release, so some things change:
assert_that(float("nan")).is_greater_than(1)Before (1.1)
passed
Now
AssertionFailure: Expected <nan> to be greater than <1>, but was not.
bool in is_close_to(), and moreadd_extension() refuses a taken name without override=TrueAssertionFailure, a subclass of AssertionErrortypes-assertpy: it describes 1.1 and hides the 2.x typesGuide: Upgrading from assertpy 1.x
- assertpy2[json]
+ assertpy[json]- from assertpy2 import assert_that
+ from assertpy import assert_thatOld flags, settings and environment variables still work, with a warning:
$ pytest --assertpy2-snapshot-update
FutureWarning: --assertpy2-snapshot-update is the assertpy2 name of --assertpy-snapshot-update. It keeps working until assertpy 3.0, use --assertpy-snapshot-update instead.
2: --assertpy-snapshot-update, assertpy_diff, ASSERTPY_SNAPSHOT_CI. Old ones go in 3.0ignore:.*is the assertpy2 name of:FutureWarning# assertpy2: allow-dangling is still readGuide: Coming from assertpy2
assertpy2 |
assertpy |
|
|---|---|---|
assert_warn() default logger |
assertpy2 |
assertpy |
log_passes() logger |
assertpy2.passes |
assertpy.passes |
| pytest plugin name | -p no:assertpy2 |
-p no:assertpy |
hide verbose traceback messages in pytest
fixup code formatting to be PEP8
is_sorted() assertion (#99)fix deprecated collections.Iterable
extracting() with list extract by index (#81, d02b53e)contains_entry() (#85)collections.Iterable (#90)is_subset_of() when invoked with 1-item arg (#93)soft_assertions() context manager to be reentrant (#92, #94)assert_warn() to log instead of print (#97)add is_not_close_to() and is_not_between()
is_not_close_to() and is_not_between() (#82)include flag when comparing dicts with is_equal_to() (#79)does_not_exist() (#78)much improved and actually useful is_equal_to() failure message when testing dicts
is_equal_to() failure message when testing dicts (#75)new numeric assertions is_nan(), is_not_nan(), is_inf(), is_not_inf()
is_nan(), is_not_nan(), is_inf(), is_not_inf() (#66)py.test (#67)contains() failure messages, and less verbose (#68, 9474760)raises() assertion supports any callable (#70)extracting() helper with filter and sort (#71, docs)correct support for metaclass testing with is_type_of()
is_type_of() (#57)fail() (#58)soft_fail() assertion (#59)API Breakage! rename assert_soft() to assert_warn() (commit 9983b3a)
assert_soft() to assert_warn() (commit 9983b3a)is_subset_of() assertion (#48)is_subset_of() to work with dicts (#50, PR #51)is_type_of() and is_instance_of() (#52)contains_only() assertion (#54)with soft_assertions(): context manager (#53, PR #55)API Breakage! rename extract() helper to extracting()
extract() helper to extracting() (#42)raises() and when_called_with() syntax (#41)is_iterable() assertion (#45)extracting() helper so it can flatten a collection of dicts on key (#44)contains_key(), contains_value(), ..) to be merely dict-like (#46)starts_with() and end_with() work with collections (#24)AssertionErrorsingle codebase with support for Python 2.6, 2.7, 3.3, 3.4
contains_ignoring_case() (#37)described_as() (#35)added does_not_contain_key() and does_not_contain_value()
does_not_contain_entry() (#34)does_not_contain_key() and does_not_contain_value() (#33)numpy.float64 (#32)contains_duplicates() and does_not_contain_duplicates() (#31)is_not_in() (#29)is_in() (#28)is_zero() and is_not_zero() (#27)is_greater_than_or_equal_to() and is_less_than_or_equal_to() (#26)contains_sequence() (#25)is_positive() and is_negative() (#23)initial release on Anaconda Cloud (aka binstar)
Nothing published for this version
One column per quarter.