pytest-icdiff

0.9 · active · verified Thu Apr 09

pytest-icdiff is a plugin for the pytest testing framework that significantly improves the readability of assertion error messages. By leveraging the `icdiff` utility, it provides clear, colorized, side-by-side diffs for failed equality assertions (assert ==), making it easier to pinpoint differences in complex data structures like dictionaries and lists. The current stable version is 0.9, released in December 2023, and it generally maintains an active development status with compatibility for Python 3.7 and newer.

Warnings

gotcha Subtle type differences (e.g., integer 5 vs. float 5.0) might not always be highlighted as distinct changes in the diff output. The underlying `icdiff` library might choose to represent them similarly to avoid 'false-positive' colorization, potentially masking minor distinctions that could be relevant in some contexts.
Fix: Manually inspect assertions for edge cases involving type-sensitive comparisons or use explicit type checks in your tests if such distinctions are critical.
gotcha The enhanced diffing provided by `pytest-icdiff` is primarily designed for and most effective with `assert ==` (equality comparisons). Other types of assertions, such as `assert 'substring' in my_string`, `assert obj is None`, or custom assertion helpers, will revert to `pytest`'s default output format and will not benefit from the `icdiff` formatting.
Fix: Be aware that not all assertion failures will display `icdiff`'s enhanced output. Focus on `assert ==` for complex object comparisons to leverage the plugin fully.
gotcha While `pytest-icdiff` aims for broad compatibility, `pytest` itself undergoes frequent updates, including major version bumps with breaking changes (e.g., dropping Python version support or internal API modifications). Although `pytest-icdiff` currently supports Python >=3.7 and lists a general `pytest` dependency, ensure your specific `pytest` version is compatible to avoid unexpected behavior or conflicts.
Fix: Regularly check the `pytest-icdiff` GitHub repository for updates on `pytest` compatibility. When upgrading `pytest`, test your suite thoroughly to catch any unforeseen interactions.

Install

pip install pytest-icdiff Install with pip

Quickstart

After installing `pytest-icdiff`, its functionality is automatically enabled for `pytest` runs. Create a simple test file with failing `assert ==` comparisons to see the enhanced, colorized, side-by-side diffs in action.

import pytest

# test_example.py
def test_dictionary_comparison_failure():
    expected_data = {"name": "Alice", "age": 30, "city": "New York"}
    actual_data = {"name": "Bob", "age": 31, "city": "London", "occupation": "Engineer"}
    assert expected_data == actual_data

def test_list_comparison_failure():
    expected_list = [1, 2, 3, "a", 5]
    actual_list = [1, 2, 4, "b", 5]
    assert expected_list == actual_list

# To run this example, save it as a .py file (e.g., test_example.py)
# and execute `pytest -q test_example.py` in your terminal.
# pytest-icdiff will automatically enhance the output for failed assertions.

view raw JSON →