Pytest DeepAssert Plugin

0.3.0 · active · verified Thu Apr 16

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.

Common errors

```
AssertionError: Expected: {...} == Actual: {...} (standard pytest diff)
```
cause 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.
```
cause 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.
```
cause 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)`.

Warnings

breaking Starting 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.
gotcha The 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.
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)`.

Install

pip install pytest-deepassert Install from PyPI

Imports

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.

Quickstart

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

view raw JSON →