rust-pretty-assertions

pretty_assertions is a small, focused Rust crate that overwrites the standard library’s assert_eq! and assert_ne! macros with versions that render a colorful, line-by-line diff of the two values under test. When a standard assert_eq! fails, Rust dumps the full Debug representation of both sides and leaves the developer to spot the differing fields by eye; pretty_assertions instead formats both values with {:#?}, diffs the resulting text, and prints only what changed, highlighted in color.

The crate is designed to be imported per-module (use pretty_assertions::{assert_eq, assert_ne};) so it only shadows the macros where explicitly opted into, and is commonly scoped to [dev-dependencies] so it never affects non-test build times. It supports no_std environments via an alloc-only feature flag, and exposes the underlying Comparison and StrComparison types directly for anyone who wants pretty diff output outside of an assertion macro.

With over 190 million downloads on crates.io, it is one of the most widely used testing-ergonomics crates in the Rust ecosystem, valued for the amount of debugging time it saves without requiring any change to test logic.

What You Get

• Drop-in assert_eq! and assert_ne! macros that match the standard library’s signature, including custom panic messages
• A colorful, line-by-line diff of the Debug representation of both compared values on failure
• Comparison and StrComparison types for producing the same diff output outside of an assertion, including string-specific multi-line diffing via AsRef<str>
• no_std support via an alloc-only feature flag for environments without the standard library
• An unstable feature flag for opting into in-progress functionality ahead of semantic versioning guarantees
• Zero required configuration beyond a per-module use import, so it can be adopted incrementally across a codebase

Common Use Cases

• Faster failed-test triage - a developer scanning CI output for a failing assert_eq! sees only the fields that actually differ instead of two full struct dumps
• Reviewing snapshot-style struct comparisons - teams testing large structs or nested enums use the diff to immediately see which nested field regressed
• Debugging string-heavy assertions - StrComparison gives a readable multi-line diff for comparing rendered templates, serialized output, or generated code
• Enforcing pretty diffs project-wide via Clippy - teams add a disallowed-macros Clippy lint pointing std::assert_eq/assert_ne at the pretty_assertions versions so the ergonomic macros are used consistently across a codebase
• Test-only dependency with no build-time cost - added under [dev-dependencies] so production compile times and binary size are unaffected

Under The Hood

Architecture The crate is intentionally small and single-purpose: src/lib.rs defines the public Comparison/StrComparison structs and the assert_eq!/assert_ne! macros, while src/printer.rs owns the actual diff rendering (line splitting, coloring, and the write_header/write_lines output routines). Comparisons are lazy — a Comparison::new call only stores references to the two values, and the expensive Debug-formatting and diffing work happens inside Display::fmt, so the cost is paid only when a diff is actually printed (i.e., on assertion failure). The macros themselves expand to an internal @ arm that formats a common panic message, keeping the public macro surface a near-exact match for core::assert_eq!/assert_ne! including support for custom panic messages.

Tech Stack The crate is pure Rust (edition 2018, MSRV 1.35), built with Cargo as a workspace containing the library crate (pretty_assertions) and a separate benchmark crate (pretty_assertions_bench). Runtime dependencies are minimal and deliberately scoped: yansi for terminal color output and diff for line-level text diffing. Feature flags (std, alloc, unstable) gate no_std support and let downstream users opt out of the standard library while still pulling in alloc for the string/vector operations the diff formatting needs.

Code Quality Tests live in pretty_assertions/tests/macros.rs and exercise the macro output directly, including custom-message formatting and edge cases like values that already contain ANSI-like text. The crate enables #![deny(clippy::all, missing_docs, unsafe_code)] at the crate root, meaning every public item requires a doc comment, all Clippy lints are treated as errors, and unsafe code is categorically disallowed — a strict bar for a widely-depended-upon crate. Public types are documented with runnable doctests demonstrating actual usage, which double as both documentation and regression tests. CI is configured via GitHub Actions plus a legacy .travis.yml, with a qvet.yml release-vetting config.

What Makes It Unique Rather than reimplementing assertion logic, pretty_assertions works by formatting both operands with {:#?} and running a generic text diff over the resulting Debug strings — a technique that requires no changes to how types implement PartialEq/Debug and works uniformly across any comparable type, including deeply nested structs and enums. Its explicit semantic-versioning carve-out for output formatting (the diff’s exact appearance can change between minor versions, since it’s meant for humans, not snapshot testing) is an unusually candid piece of API design that keeps the crate free to improve its output without being pinned to compatibility guarantees that don’t apply to display formatting.