Assertables Rust crate of macros for "assert" and "assertable"

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

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

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

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

assert vs. assertable

These macros have two styles:

• assert macros return () or panic!(…).

• assertable macros return Ok(()) or Err(…).

Examples:

assert_lt!(1, 2); // assert 1 is less than 2
//-> ()

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

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 such as 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 comparing 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 comparing function return values

• 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 comparing 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 comparing function Result 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!
//  // assertion failed: `assert_f_err_string_eq!(example_digit_to_string, left, right)`
//  //    left input: `20`,
//  //   right input: `10``,
//  //   left is err: `true`,
//  //  right is err: `true`,
//  //   left output: `\"20 is out of range\"`,
//  //  right output: `\"10 is out of range\"`

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.

• assert_bag_eq(a, b): bag a == bag b

• assert_bag_ne(a, b): bag a != bag b

• assert_bag_subbag(a, b): bag a ⊆ bag b

• assert_bag_superbag(a, b): bag a ⊇ bag b

Examples:

assert_bag_eq!([1, 1], [1, 1]);
//-> ()

assert_bag_eq!([1, 1], [1, 1, 1]);
//-> panic!
// assertion failed: `assert_bag_eq!(left, right)`
//   left: `[1, 1]`,
//  right: `[1, 1, 1]`

assert_io_xx for input/output comparisons

These macros help with input/output checking, such as with comparison of disk files, IO streams, etc.

• assert_io!(a): a is true

• assert_io_eq!(a, b): a == b

• assert_io_ne!(a, b): a != b

• assert_io_lt!(a, b): a < b

• assert_io_le!(a, b): a <= b

• assert_io_gt!(a, b): a > b

• assert_io_ge!(a, b): a >= b

Examples:

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

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

assert_read_to_string_xx for std::io::Read comparisons

These macros help with readers, such as file handles, byte arrays, input streams, and the trait std::io::Read.

• assert_read_to_string_eq!(a, b): a.read_to_string() == b.read_to_string()

• assert_read_to_string_ne!(a, b): a.read_to_string() != b.read_to_string()

• assert_read_to_string_lt!(a, b): a.read_to_string() < b.read_to_string()

• assert_read_to_string_le!(a, b): a.read_to_string() <= b.read_to_string()

• assert_read_to_string_gt!(a, b): a.read_to_string() > b.read_to_string()

• assert_read_to_string_ge!(a, b): a.read_to_string() >= b.read_to_string()

Examples:

use std::io::Read;

let mut a = "a".as_bytes();
let mut b = "b".as_bytes();
assert_read_to_string_lt!(a, b);
//-> ()

let mut a = "a".as_bytes();
let mut b = "b".as_bytes();
assert_read_to_string_lt!(b, a);
//-> panic!
// assertion failed: `assert_read_to_string_lt!(left, right)`
//   left: `\"b\"`,
//  right: `\"a\"`