Registry / testing / pytest-deepassert

pytest-deepassert

library0.3.0pypypi✓ verified 87d ago

pytest-deepassert is a pytest plugin (current version 0.3.0) designed to enhance assertion reporting, particularly for complex data structures. Built upon the powerful `deepdiff` library, it provides clear, detailed difference reports, highlighting exact changes in nested objects like dictionaries, lists, and custom types. This significantly helps developers quickly identify discrepancies in test failures, offering focused output that pinpoints specific field names, values, and array indices. It has a non-fixed release cadence, with updates typically occurring a few times a year.

testing

pip install pytest-deepassert

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-DEEPASSERT

pytest-deepassert

testingpythonv0.3.0

Install

3.1s avg

Import

697ms

Disk

32MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.3.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.754s · 33.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 3.1s · import 0.639s · 34MB

32MB installed

● package 32MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

equal

✓ from pytest_deepassert import equal

This function is for direct use outside of pytest's automatic assertion rewriting, e.g., in helper functions or non-test modules. For assertions within pytest test functions, `assert` statements are automatically enhanced when the plugin is enabled.

Create a test file (e.g., `test_example.py`) with a standard `assert` statement comparing complex data structures. Run `pytest` with the `--deepassert` flag to activate the plugin's enhanced reporting. The `-vv` flag increases verbosity to show more details, including the deep diff.

# test_example.py def test_complex_data_comparison(): actual_data = { "id": 1, "name": "Alice", "details": {"age": 30, "city": "New York", "preferences": ["email", "sms"]} } expected_data = { "id": 1, "name": "Bob", # Name changed "details": {"age": 31, "city": "London", "preferences": ["email"]} } assert actual_data == expected_data # To run the test and see detailed diffs: # pytest test_example.py --deepassert -vv

Debug

Known issues

breakingStarting with version 0.3.0, `pytest-deepassert` is disabled by default and requires the `--deepassert` command-line flag to activate its functionality. Tests run without this flag will use standard pytest assertion reporting.

fix

Always run pytest with `pytest --deepassert` to enable the plugin. Consider adding `--deepassert` to your `pytest.ini` configuration file under `addopts` for automatic inclusion.

affects: >=0.3.0

gotchaThe plugin primarily enhances assertion reporting for complex data structures (e.g., dictionaries, lists of objects). For simple comparisons like `assert 1 == 2` or `assert 'a' == 'b'`, the standard pytest assertion introspection is already highly effective, and `pytest-deepassert` will not provide significant additional value.

fix

Focus on using `pytest-deepassert` for tests involving nested dictionaries, lists of objects, custom classes, or other complex types where standard diffs are hard to parse. For basic types, rely on native pytest reporting.

affects: all

gotcha`pytest-deepassert` typically only enhances assertions within test modules that pytest discovers. If you need detailed assertion reporting in helper functions or other non-test modules imported into your tests, the plugin's automatic assertion rewriting will not apply.

fix

For assertions outside of `pytest`'s direct test discovery, use the `pytest_deepassert.equal()` function explicitly to get deep comparison reports. For example: `from pytest_deepassert import equal; equal(actual, expected)`.

affects: all

Errors

Common errors & fixes

AssertionError: Expected: {...} == Actual: {...} (standard pytest diff)

The `pytest-deepassert` plugin was not activated or is comparing simple data types where it provides no additional benefit. Since version 0.3.0, the plugin requires explicit activation.

fix

Ensure you are comparing complex data structures. Run your tests with the `--deepassert` flag: `pytest --deepassert`. If using `pytest.ini`, add `addopts = --deepassert`.

Tests are running, but I don't see any deep diffs for complex objects.

The plugin is likely installed but not enabled. As of version 0.3.0, `pytest-deepassert` requires an explicit flag to be active.

fix

Add `--deepassert` to your pytest command: `pytest your_test_file.py --deepassert`. For continuous use, add `addopts = --deepassert` to your `pytest.ini` configuration file.

I'm calling `assert` in a helper function, and I want `pytest-deepassert` to enhance its output, but it's not.

The automatic assertion rewriting by `pytest` (and thus `pytest-deepassert`) typically only applies to modules directly collected as tests by pytest, not arbitrary imported helper modules.

fix

Explicitly use the `equal` function provided by the plugin in your helper functions: `from pytest_deepassert import equal; equal(my_actual_value, my_expected_value)`.

Upgrade

Version history

0.3.0latest on PyPI · released Nov 4, 2025

Audit

Dependencies

pytestrequiredCore testing framework that this plugin extends.

deepdiffrequiredUnderlying library used for calculating deep differences in data structures.

typing-extensionsoptionalProvides backported and experimental type hints.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/alexkuzmik/pytest-deepassert ↗

packagehttps://pypi.org/project/pytest-deepassert/ ↗