---
id: pytest-deepassert
version: "0.3.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# pytest-deepassert — A pytest plugin for enhanced assertion reporting with detailed diffs

License: permissive · Maintenance: aging · Downloads: 133.3K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 133.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest assertion diff plugin, detailed test failure output, nested object comparison testing, deepdiff pytest integration, enhanced assertion reporting, complex data structure testing, pytest debugging plugin, pytest-plugin, test-debugging, diff-reporting

[View on SkillFed](https://skillfed.io/packages/pytest-deepassert) · [View on PyPI](https://pypi.org/project/pytest-deepassert/)