feat: field-by-field recursive comparison

.github/workflows/ci.yml

@@ -141,7 +141,7 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: test
-          args: --no-default-features --features "colored, float-cmp, num-bigint, rust-decimal, bigdecimal"
+          args: --no-default-features --features "colored, float-cmp, num-bigint, recursive, regex, rust-decimal, bigdecimal"
       - uses: Swatinem/rust-cache@v2
 
   msrv:

Cargo.toml

@@ -4,7 +4,7 @@ version = "0.13.1"
 authors = ["haraldmaida"]
 license = "MIT OR Apache-2.0"
 edition = "2021"
-rust-version = "1.78.0"
+rust-version = "1.82.0"
 repository = "https://github.com/innoave/asserting"
 readme = "README.md"
 
@@ -19,33 +19,50 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
-default = ["std", "colored", "float-cmp", "panic", "regex"]
-bigdecimal = ["dep:bigdecimal", "dep:lazy_static"]
+default = ["std", "colored", "float-cmp", "panic", "recursive", "regex"]
+bigdecimal = ["dep:bigdecimal", "dep:once_cell"]
 colored = ["dep:sdiff"]
 float-cmp = ["dep:float-cmp"]
-num-bigint = ["dep:num-bigint", "dep:lazy_static"]
+num-bigint = ["dep:num-bigint", "dep:once_cell"]
+recursive = ["dep:serde_core", "dep:indexmap", "indexmap/serde", "dep:rapidhash"]
 rust-decimal = ["dep:rust_decimal"]
 panic = ["std"]
 regex = ["dep:regex"]
-std = []
+std = [
+    "bigdecimal?/std",
+    "float-cmp?/std",
+    "indexmap?/std",
+    "num-bigint?/std",
+    "once_cell?/std",
+    "rapidhash?/std",
+    "regex?/std",
+    "rust_decimal?/std",
+    "sdiff?/std",
+    "serde_core?/std"
+]
 
 [dependencies]
 hashbrown = "0.16"
 
 # optional
 bigdecimal = { version = "0.4", optional = true, default-features = false }
 float-cmp = { version = "0.10", optional = true }
-lazy_static = { version = "1", optional = true }
+indexmap = { version = "2", optional = true, default-features = false }
 num-bigint = { version = "0.4", optional = true, default-features = false }
+once_cell = { version = "1", optional = true, default-features = false, features = ["alloc", "critical-section"] }
+rapidhash = { version = "4", optional = true, default-features = false }
 regex = { version = "1", optional = true }
 rust_decimal = { version = "1", optional = true, default-features = false }
-sdiff = { version = "0.1", optional = true }
+sdiff = { version = "0.1", optional = true, default-features = false }
+serde_core = { version = "1", optional = true, default-features = false, features = ["alloc"] }
 
 [dev-dependencies]
 anyhow = "1"
 fakeenv = { version = "0.1", default-features = false, features = ["fake"] }
 proptest = "1"
 time = { version = "0.3", default-features = false, features = ["macros"] }
+serde = { version = "1", default-features = false, features = ["alloc", "derive"] }
+serde_bytes = { version = "0.11", default-features = false, features = ["alloc"] }
 version-sync = "0.9"
 
 [profile.dev.package]

README.md

@@ -12,13 +12,15 @@ Features of `asserting`:
 1. assertions are convenient to write and easy to read
 2. helpful error messages in case of failing assertions
 3. colored diffs between expected and actual values
-4. provide a reasonable number of assertions out of the box
-5. chaining of multiple assertions on the same subject (see ["Chaining assertions"])
+   (see ["Highlighted differences"](#highlighted-differences))
+4. chaining of multiple assertions on the same subject (see ["Chaining assertions"])
+5. field-by-field recursive comparison (see ["Field-by-field recursive comparison"]) :new:
 6. soft assertions (execute multiple assertions before panicking) (see ["Soft assertions"])
-7. do not require that asserted types have to implement traits if it is not absolutely necessary
-8. support for asserting custom types with provided assertions
-9. writing custom assertions requires minimal effort
-10. support no-std environments
+7. provide a reasonable number of assertions out of the box
+8. do not require that asserted types have to implement traits if it is not absolutely necessary
+9. support for asserting custom types with provided assertions
+10. writing custom assertions requires minimal effort
+11. support no-std environments
 
 For an overview of the provided features and many examples on how to use `asserting` see the
 [crate-level documentation][docs-url].
@@ -83,11 +85,29 @@ require std can still be added.
 
 ```toml
 [dev-dependencies]
-asserting = { version = "0.13", default-features = false, features = ["colored", "float-cmp", "regex"] }
+asserting = { version = "0.13", default-features = false, features = ["colored", "float-cmp", "recursive", "regex"] }
 ```
 
 An allocator is still needed for no-std.
 
+## Crate Features
+
+Overview of the crate features of `asserting`. The column "no-std" specifies if this feature is
+available in no-std environments. The column "default" specifies if this feature is enabled by
+default.
+
+| Feature        | Description                                                           | no-std | default |
+|----------------|-----------------------------------------------------------------------|:------:|:-------:|
+| `std`          | Use the `std` library                                                 |   no   |   yes   |
+| `colored`      | Colored highlighting of differences between actual and expected value |  yes   |   yes   |
+| `recursive`    | Field-by-field recursive comparison mode                              |  yes   |   yes   |
+| `float-cmp`    | Floating point comparison (`ìs_close_to`)                             |  yes   |   yes   |
+| `regex`        | String matches Regex assertions (`matching`)                          |  yes   |   yes   |
+| `panic`        | Assert that code panics (with the expected message)                   |   no   |   yes   |
+| `num-bigint`   | Enhanced support for `num-bigint::BigInt`                             |  yes   |   no    |
+| `bigdecimal`   | Enhanced support for `bigdecimal::BigDecimal`                         |  yes   |   no    |
+| `rust-decimal` | Enhanded support for `rust_decimal::Decimal`                          |  yes   |   no    |
+
 ## Highlighted differences
 
 `asserting` can highlight the differences between the expected value(s) and the actual value(s) when
@@ -493,6 +513,8 @@ To start assertions on code, use the `assert_that_code!()` macro.
 
 ["Chaining assertions"]: https://docs.rs/asserting/latest/asserting/#chaining-assertions-on-the-same-subject
 
+["Field-by-field recursive comparison"]: https://docs.rs/asserting/latest/asserting/#field-by-field-recursive-comparison
+
 ["soft assertions"]: https://docs.rs/asserting/#soft-assertions
 
 [custom assertions]: https://docs.rs/asserting/#custom-assertions

examples/fixture/mod.rs

@@ -8,17 +8,25 @@ mod dummy_extern_uses {
     #[cfg(feature = "float-cmp")]
     use float_cmp as _;
     use hashbrown as _;
-    #[cfg(feature = "num-bigint")]
-    use lazy_static as _;
+    #[cfg(feature = "recursive")]
+    use indexmap as _;
     #[cfg(feature = "num-bigint")]
     use num_bigint as _;
+    #[cfg(any(feature = "bigdecimal", feature = "num-bigint"))]
+    use once_cell as _;
     use proptest as _;
+    #[cfg(feature = "recursive")]
+    use rapidhash as _;
     #[cfg(feature = "regex")]
     use regex as _;
     #[cfg(feature = "rust-decimal")]
     use rust_decimal as _;
     #[cfg(feature = "colored")]
     use sdiff as _;
+    use serde as _;
+    use serde_bytes as _;
+    #[cfg(feature = "recursive")]
+    use serde_core as _;
     use time as _;
     use version_sync as _;
 }

justfile

@@ -44,7 +44,7 @@ lint-default:
 
 # linting code using Clippy for no-std environment
 lint-no-std:
-    cargo clippy --all-targets --no-default-features --features "colored, float-cmp, num-bigint, rust-decimal, bigdecimal"
+    cargo clippy --all-targets --no-default-features --features "colored, float-cmp, num-bigint, recursive, regex, rust-decimal, bigdecimal"
 
 # linting code using Clippy with no features enabled
 lint-no-features:
@@ -67,7 +67,7 @@ test-default:
 
 # run tests for no-std environment
 test-no-std:
-    cargo test --no-default-features --features "colored, float-cmp, num-bigint, rust-decimal, bigdecimal"
+    cargo test --no-default-features --features "colored, float-cmp, num-bigint, recursive, regex, rust-decimal, bigdecimal"
 
 # run tests with no features enabled
 test-no-features:

src/assertions.rs

@@ -99,6 +99,7 @@ pub trait AssertSameAs<E> {
     ///
     /// assert_that!(42).is_same_as(42);
     /// ```
+    #[track_caller]
     fn is_same_as(self, expected: E) -> Self;
 
     /// Verifies that the subject is of the same type but has a different value
@@ -114,9 +115,150 @@ pub trait AssertSameAs<E> {
     ///
     /// assert_that!(41).is_not_same_as(42);
     /// ```
+    #[track_caller]
     fn is_not_same_as(self, expected: E) -> Self;
 }
 
+/// Assert whether a value is equivalent to a value of type [`Value`] using
+/// field-by-field recursive comparison.
+///
+/// These assertions are intended for the field-by-field recursive comparison
+/// mode and are implemented for all types that implement [`serde::Serialize`].
+///
+/// # Examples
+///
+/// ```
+/// use asserting::prelude::*;
+/// use serde::Serialize;
+///
+/// #[derive(Serialize)]
+/// struct Person {
+///     id: u64,
+///     name: String,
+///     age: u8,
+///     email: Vec<String>,
+/// }
+///
+/// let person = Person {
+///     id: 456,
+///     name: "Silvia".into(),
+///     age: 25,
+///     email: vec!["silvia@domain.com".to_string()],
+/// };
+///
+/// assert_that!(person)
+///     .using_recursive_comparison()
+///     .ignoring_not_expected_fields()
+///     .is_equivalent_to(value!({
+///         name: "Silvia",
+///         age: 25_u8,
+///     }));
+/// ```
+///
+/// [`Value`]: crate::recursive_comparison::value::Value
+/// [`serde::Serialize`]: serde_core::Serialize
+#[cfg(feature = "recursive")]
+#[cfg_attr(docsrs, doc(cfg(feature = "recursive")))]
+pub trait AssertEquivalence<E> {
+    /// Verifies that the subject is equivalent to the expected value of type
+    /// [`Value`].
+    ///
+    /// The actual value (subject) and the expected value (parameter) are
+    /// compared field-by-field recursively.
+    ///
+    /// The intended and most convenient way to construct a [`Value`] instance
+    /// is using the [`value!`] macro.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use asserting::prelude::*;
+    /// use serde::Serialize;
+    ///
+    /// #[derive(Serialize)]
+    /// struct Person {
+    ///     id: u64,
+    ///     name: String,
+    ///     age: u8,
+    ///     email: Vec<String>,
+    /// }
+    ///
+    /// let person = Person {
+    ///     id: 456,
+    ///     name: "Silvia".into(),
+    ///     age: 25,
+    ///     email: vec!["silvia@domain.com".to_string()],
+    /// };
+    ///
+    /// assert_that!(person)
+    ///     .using_recursive_comparison()
+    ///     .ignoring_not_expected_fields()
+    ///     .is_equivalent_to(value!({
+    ///         name: "Silvia",
+    ///         age: 25_u8,
+    ///     }));
+    /// ```
+    ///
+    /// See the documentation of the [`recursive_comparison`] module for more
+    /// details.
+    ///
+    /// [`value!`]: crate::prelude::value
+    /// [`Value`]: crate::recursive_comparison::value::Value
+    /// [`recursive_comparison`]: crate::recursive_comparison
+    /// [`serde::Serialize`]: serde_core::Serialize
+    #[track_caller]
+    fn is_equivalent_to(self, expected: E) -> Self;
+
+    /// Verifies that the subject is not equivalent to the expected value of
+    /// type [`Value`].
+    ///
+    /// The actual value (subject) and the expected value (parameter) are
+    /// compared field-by-field recursively. Fields of the actual value that
+    /// are not present in the actual value are always ignored.
+    ///
+    /// The intended and most convenient way to construct a [`Value`] instance
+    /// is using the [`value!`] macro.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use asserting::prelude::*;
+    /// use serde::Serialize;
+    ///
+    /// #[derive(Serialize)]
+    /// struct Person {
+    ///     id: u64,
+    ///     name: String,
+    ///     age: u8,
+    ///     email: Vec<String>,
+    /// }
+    ///
+    /// let person = Person {
+    ///     id: 456,
+    ///     name: "Silvia".into(),
+    ///     age: 25,
+    ///     email: vec!["silvia@domain.com".to_string()],
+    /// };
+    ///
+    /// assert_that!(person)
+    ///     .using_recursive_comparison()
+    ///     .is_not_equivalent_to(value!({
+    ///         name: "Silvia",
+    ///         age: 21_u8,
+    ///     }));
+    /// ```
+    ///
+    /// See the documentation of the [`recursive_comparison`] module for more
+    /// details.
+    ///
+    /// [`value!`]: crate::prelude::value
+    /// [`Value`]: crate::recursive_comparison::value::Value
+    /// [`recursive_comparison`]: crate::recursive_comparison
+    /// [`serde::Serialize`]: serde_core::Serialize
+    #[track_caller]
+    fn is_not_equivalent_to(self, expected: E) -> Self;
+}
+
 /// Assert approximate equality for floating point numbers.
 ///
 /// # Examples

src/bigdecimal/mod.rs

@@ -3,12 +3,12 @@ use crate::properties::{
 };
 use bigdecimal::num_bigint::Sign;
 use bigdecimal::{BigDecimal, BigDecimalRef, One, Zero};
-use lazy_static::lazy_static;
+use once_cell::sync::Lazy;
 
-lazy_static! {
-    static ref BIGDECIMAL_ZERO: BigDecimal = bigdecimal_zero();
-    static ref BIGDECIMAL_ONE: BigDecimal = bigdecimal_one();
-}
+#[allow(clippy::non_std_lazy_statics)]
+static BIGDECIMAL_ZERO: Lazy<BigDecimal> = Lazy::new(bigdecimal_zero);
+#[allow(clippy::non_std_lazy_statics)]
+static BIGDECIMAL_ONE: Lazy<BigDecimal> = Lazy::new(bigdecimal_one);
 
 #[inline]
 fn bigdecimal_zero() -> BigDecimal {

src/collection.rs

@@ -98,7 +98,7 @@ impl<T, const N: usize> IsEmptyProperty for [T; N] {
 #[cfg(feature = "std")]
 mod std {
     use crate::properties::{IsEmptyProperty, LengthProperty};
-    use std::collections::{HashMap, HashSet};
+    use crate::std::collections::{HashMap, HashSet};
 
     impl<K, V, S> IsEmptyProperty for HashMap<K, V, S> {
         fn is_empty_property(&self) -> bool {

src/colored/tests.rs

@@ -522,6 +522,7 @@ mod with_colored_and_std_features {
         assert_that(assertion.diff_format()).is_equal_to(&DIFF_FORMAT_NO_HIGHLIGHT);
     }
 
+    #[cfg(feature = "panic")]
     #[test]
     fn assert_that_code_sets_the_diff_format_to_red_green() {
         env::set_var(ENV_VAR_HIGHLIGHT_DIFFS, "red-green");
@@ -531,6 +532,7 @@ mod with_colored_and_std_features {
         assert_that(assertion.diff_format()).is_equal_to(&DIFF_FORMAT_RED_GREEN);
     }
 
+    #[cfg(feature = "panic")]
     #[test]
     fn verify_that_code_sets_the_diff_format_to_no_highlighting() {
         let assertion = verify_that_code(|| {});

src/env.rs

@@ -14,9 +14,9 @@ pub use fake_env::*;
 
 #[cfg(test)]
 mod fake_env {
+    use crate::std::cell::RefCell;
+    use crate::std::env::VarError;
     use fakeenv::EnvStore;
-    use std::cell::RefCell;
-    use std::env::VarError;
 
     thread_local! {
         static ENV_STORE: RefCell<EnvStore> = RefCell::new({