pytest-icdiff

pytest-icdiff is a small pytest plugin that improves the readability of assertion failure messages. When an assert == comparison fails, it replaces pytest’s default diff with a colorized, side-by-side view rendered by the icdiff library and pretty-printed with pprintpp.

Installing the package is all that is required: pytest discovers the plugin automatically and applies the enhanced diff to any equality assertion. It adds command-line options to control column width, whitespace highlighting, and line numbers, making test failures faster to diagnose without changing how you write tests.

What You Get

• Colorized, side-by-side diffs for failed assert == comparisons
• Automatic activation on install with no configuration or code changes
• Command-line options for column width, whitespace highlighting, and line numbers
• Pretty-printed values via pprintpp for readable nested structures

Common Use Cases

• Diagnosing failing equality assertions in large dictionaries or lists faster
• Improving the readability of CI test output for complex data structures
• Getting clearer local test feedback without editing test code

Under The Hood

Architecture - The entire plugin lives in a single module, pytest_icdiff.py. It registers command-line options through the pytest_addoption hook and implements pytest_assertrepr_compare, the pytest hook that pytest calls whenever an assertion fails. When invoked, it pretty-prints both operands with pprintpp.pformat, feeds them to icdiff.ConsoleDiff, and returns the colorized side-by-side lines that pytest displays.

Tech Stack - Pure Python with two runtime dependencies: icdiff for the colorized diff rendering and pprintpp for stable, readable value formatting. Packaging is a classic setup.py with tox for multi-version testing.

Code Quality - The codebase is intentionally tiny, with a tests/ directory exercising the plugin across pytest configurations and the various CLI options. Because the surface area is small, correctness is straightforward to reason about, though the plugin relies on pytest’s internal assertion-comparison hook contract.

API Design - There is effectively no API to learn: install the package and it works. The only user-facing surface is a handful of well-documented --icdiff-* command-line flags, which keeps the developer experience frictionless.