assert-json-diff

assert-json-diff is a Rust testing crate that provides macros for comparing two serializable values by diffing their JSON representations. Instead of the terse failure from a plain assert_eq!, it reports the exact paths and values that differ, which makes assertions on large JSON payloads far easier to debug. It supports both exact equality and partial inclusion matching, building on serde and serde_json.

What You Get

• An assert_json_eq! macro for asserting two values are fully equal as JSON
• An assert_json_include! macro for asserting one value is contained within another
• Human-readable diff output pinpointing the exact differing paths and values
• Direct integration with any type that implements serde’s Serialize
• A assert_json_matches entry point with configurable comparison modes

Common Use Cases

• Asserting API response bodies match expected JSON in integration tests
• Checking that a serialized struct produces the expected JSON shape
• Verifying partial JSON payloads without pinning every field exactly

Under The Hood

Architecture

The crate is organized around src/diff.rs, which recursively walks two serde_json::Value trees and records differences with their JSON paths, and src/core_ext.rs, which supplies helper extensions. src/lib.rs exposes the public macros assert_json_eq, assert_json_include, and the underlying assert_json_matches, translating a comparison config and the collected diffs into a formatted panic message on failure.

Tech Stack

It targets Rust edition 2018 and depends only on serde and serde_json, keeping the footprint minimal. Dev dependencies add version-sync and serde derive for the test suite. There are no feature flags; the crate is a focused test-time utility.

Code Quality

Tests reside in tests/integration_test.rs with a separate version-numbers.rs check that keeps the README and crate version in sync. The diffing logic is contained and the code is small and legible. The maintenance badge marks the project as passively maintained, consistent with a stable, narrowly scoped tool.

API Design

The API is macro-first and mirrors the familiar assert_eq! ergonomics, so adoption in an existing test suite is nearly frictionless. assert_json_matches exposes a config for choosing comparison strictness. Documentation is thorough, with README examples showing both the input and the exact diff output produced on failure.