pytest-deepassert

What it is and what it does

pytest-deepassert is a pytest plugin that intercepts assertion failures and replaces the default comparison output with structured, readable diffs generated by deepdiff. When you enable it with the --deepassert flag, any failed assertion on complex data structures—dictionaries, lists, nested objects, custom types—shows you exactly which fields differ, what values changed, and where items were added or removed, rather than dumping a wall of text that requires manual parsing.

The plugin is designed as an opt-in enhancement: it does not interfere with normal pytest behavior unless you explicitly pass --deepassert at runtime. It handles basic types (int, string, float, bool), collections (dict, list, tuple, set, frozenset), and advanced types (OrderedDict, NamedTuple, custom objects), and claims to work with pytest.approx() and mock.ANY for flexible comparisons. The implementation depends on deepdiff for the heavy lifting, pytest for the plugin interface, and typing-extensions for compatibility.

Use it for:

• Debugging test failures on API responses or database records where only a few nested fields differ from expected.
• Comparing large configuration dictionaries or JSON payloads where visual diff clarity matters more than raw output.
• Testing mock objects with ANY placeholders or approximate float comparisons that standard assertions struggle to report clearly.
• Reducing time spent reading assertion diffs in CI logs by getting a structured, path-based view of what changed.
• Validating complex domain objects or data transfer objects where the structure is deeply nested and changes are subtle.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that replaces standard assertion failures with detailed, structured diffs powered by DeepDiff, making it easier to spot differences in complex nested data structures.

Yes, with conditions. Install if you regularly debug test failures on complex nested data and want clearer diffs without rewriting assertions. The low install friction and permissive license make it a safe experiment. However, the aging maintenance status (283 days since last release, 11 stars) means the project has limited community traction and may not receive timely fixes; use it in projects where you can tolerate slower response to issues. The opt-in flag design means you can enable it selectively without affecting existing test suites.

Install

pytest-deepassert on PyPI

pip install pytest-deepassert

uv add pytest-deepassert

poetry add pytest-deepassert

Installing pytest-deepassert

Before you install

Low friction: pure Python wheel with only three runtime dependencies (deepdiff, pytest, typing-extensions). Maintenance status is aging—last release was 283 days ago and the project has 11 stars—so expect infrequent updates and limited community validation.

License in practice

MIT license (permissive): you can use, modify, and distribute this package freely in commercial and open-source projects with minimal restrictions.

Quickstart

pip install pytest-deepassert

# In your test file:
import pytest

def test_example():
    expected = {"name": "Alice", "age": 30}
    actual = {"name": "Bob", "age": 30}
    assert expected == actual

# Run with: pytest --deepassert your_test.py

Requires pytest 6.0+ and Python 3.8+; the plugin is opt-in via the --deepassert flag and does not activate by default.

Verify before relying

• How well does the plugin handle pytest.approx() and mock.ANY in practice across different data nesting levels?
• What is the performance impact on test suites with very large nested structures?
• Are there known limitations or edge cases with custom comparator utilities beyond what the description lists?

Package facts

Evidence: pytest_deepassert-0.3.0-py3-none-any.whl

Keywords: assertions, debugging, diff, plugin, pytest, testing

Tags

More Testing packages