Crate assertables

Expand description

Assertables: Rust crate of macros “assert” and “assertable”

This assertables Rust crate provides macros for assert…! and assertable…!, which are useful for testing and also for runtime reliability checking. By SixArm.com.

Crate: https://crates.io/crates/assertables

Docs: https://docs.rs/assertables/

Repo: https://github.com/sixarm/assertables-rust-crate/

assert & assertable

These macros have two styles:

assert macros return () or panic!(…).
assertable macros return Ok(()) or Err(…).

Examples of “assert less than” and “assertable less than”:

assert_lt!(1, 2);
//-> ()

assert_lt!(2, 1);
//-> panic!
// assertion failed: `assert_lt!(left, right)`
//   left: `2`,
//  right: `1`

let x = assertable_lt!(1, 2); 
//-> Ok(())

let x = assertable_eq!(2, 1); 
//-> Err("…")
// assertable failed: `assertable_lt!(left, right)`
//   left: `2`,
//  right: `1`

These two styles are useful because:

assert macros favor compile-time tests and diagnostics.
assertable macros favor run-time tracing and recoveries.

The macros use abbreviations: eq (equals), ne (not equals), lt (less than), le (less than or equal to), gt (greater than), ge (greater than or equals).

The macros have a second form where a custom error message can be provided.

assert_xx for values

Compare values.

assert_eq!(a, b) ~ a == b
assert_ne!(a, b) ~ a != b
assert_lt!(a, b) ~ a < b
assert_le!(a, b) ~ a <= b
assert_gt!(a, b) ~ a > b
assert_ge!(a, b) ~ a >= b

Examples:

assert_lt!(1, 2);
//-> ()

assert_lt!(2, 1);
//-> panic!
// assertion failed: `assert_lt!(left, right)`
//   left: `2`
//  right: `1`

assert_f_xx for function returns

assert_f_eq!(f, a, b) ~ f(a) == f(b)
assert_f_ne!(f, a, b) ~ f(a) != f(b)
assert_f_lt!(f, a, b) ~ f(a) < f(b)
assert_f_le!(f, a, b) ~ f(a) <= f(b)
assert_f_gt!(f, a, b) ~ f(a) > f(b)
assert_f_ge!(f, a, b) ~ f(a) >= f(b)

Examples:

assert_f_lt!(i32::abs, 1, -2);
//-> ()

assert_f_lt!(i32::abs, -2, 1);
//-> panic!
// assertion failed: `assert_f_eq!(function, left, right)`
//   left input: `-2`,
//  right input: `1`,
//  left output: `2`,
// right output: `1`

assert_f_ok_xx for function Result Ok values

assert_f_ok_eq!(f, a, b) ~ f(a).unwrap() == f(b).unwrap()
assert_f_ok_ne!(f, a, b) ~ f(a).unwrap() != f(b).unwrap()
assert_f_ok_lt!(f, a, b) ~ f(a).unwrap() < f(b).unwrap()
assert_f_ok_le!(f, a, b) ~ f(a).unwrap() <= f(b).unwrap()
assert_f_ok_gt!(f, a, b) ~ f(a).unwrap() > f(b).unwrap()
assert_f_ok_ge!(f, a, b) ~ f(a).unwrap() >= f(b).unwrap()

fn example_digit_to_string(i: isize) -> Result<String, String> {
    match i {
        0..=9 => Ok(format!("{}", i)),
        _ => Err(format!("{:?} is out of range", i)),
    }
}

assert_f_ok_lt!(example_digit_to_string, 1, 2);
//-> ()
 
assert_f_ok_lt!(example_digit_to_string, 2, 1);
//-> panic!("…")
// assertion failed: `assert_f_eq!(function, left, right)`
//    left input: `2`,
//   right input: `1`,
//   left output: `\"2\"`,
//  right output: `\"1\"`

assert_f_err_string_xx for function Err strings

assert_f_err_string_eq!(f, a, b) ~ f(a).unwrap_err().to_string() == f(b).unwrap_err().to_string()
assert_f_err_string_ne!(f, a, b) ~ f(a).unwrap_err().to_string() != f(b).unwrap_err().to_string()
assert_f_err_string_lt!(f, a, b) ~ f(a).unwrap_err().to_string() < f(b).unwrap_err().to_string()
assert_f_err_string_le!(f, a, b) ~ f(a).unwrap_err().to_string() <= f(b).unwrap_err().to_string()
assert_f_err_string_gt!(f, a, b) ~ f(a).unwrap_err().to_string() > f(b).unwrap_err().to_string()
assert_f_err_string_ge!(f, a, b)~ f(a).unwrap_err().to_string() >= f(b).unwrap_err().to_string()

Examples:

fn example_digit_to_string(i: isize) -> Result<String, String> {
    match i {
        0..=9 => Ok(format!("{}", i)),
        _ => Err(format!("{:?} is out of range", i)),
    }
}

assert_f_err_string_lt!(example_digit_to_string, 10, 20);
//-> ()

assert_f_err_string_lt!(example_digit_to_string, 20, 10);
//-> panic!

Two functions that we use often:

assert_f_ok_eq!(i32::from_str, str1, str2); // compare parsing of numbers
assert_f_ok_eq!(std::fs::read_to_string, file1, file2); // compare file text

assert_set_xx for set comparisons

These macros help with comparison of set parameters, such as two arrays or two vectors. where the item order does not matter, and the item count does not matter. The macros convert inputs into HashSet iterators.

assert_set_eq!(a, b) ~ set a == set b
assert_set_ne!(a, b) ~ set a != set b
assert_set_subset!(a, b) ~ set a ⊆ set b
assert_set_superset!(a, b) ~ set a ⊇ set b
assert_set_joint!(a, b) ~ set a is joint with set b
assert_set_disjoint!(a, b) ~ set a is disjoint with set b

Examples:

assert_set_eq!([1, 2], [2, 1]);
//-> ()

assert_set_eq!([1, 2], [3, 4]);
//-> panic
// assertion failed: `assert_set_eq!(left, right)`
//   left: `[1, 2]`,
//  right: `[3, 4]`
//-> panic!("assertion failed: `assert_set_eq!(left, right)`\n  left: `[1, 2]`,\n right: `[3, 4]`");

assert_bag_xx for bag cmparisons

Thes macros help with comparison of bag parameters, such as comparison of two arrays or two vectors, where the item order does not matter, and the item count does matter. The macros convert inputs into HashMap iterators.