Assertables: Rust crate of assert macros for testing

Assertables is a Rust crate that provides many assert macros to improve your compile-time tests and run-time reliability.

• Crate: https://crates.io/crates/assertables
• Docs: https://docs.rs/assertables/
• Repo: https://github.com/sixarm/assertables-rust-crate/
• Contact: [email protected]

Introduction

The Assertables Rust crate provides many assert macros that can help you develop, test, and debug.

• Test values with assert_lt, assert_gt, …
• Test results with assert_ok, assert_err, …
• Test groups with assert_all, assert_any, …
• Test matching with assert_matches, assert_is_match, …
• Test nearness with assert_approx, assert_abs_diff, …
• Test programs with assert_command, assert_status, …
• Many more below.

To use this crate, add it to your file Cargo.toml:

assertables = "9.4.0"

Benefits:

• You can write better tests to improve reliability and maintainability.
• You can handle more corner cases without needing to write custom code.
• You can troubleshoot faster because error messages show more detail.

Features:

• Easy to use: everything is well-documented with runnable examples.
• Zero overhead: if you don't use a macro, then it's not compiled.
• Multiple forms: for panic, debug, result return, success return.

Learning: FAQ, docs, examples, changes, upgrades, developing.

Comparisons: more_asserts, cool_asserts, assert2, claims, etc.

Examples

Examples with numbers:

let i = 10;
assert_lt!(i, 11);
assert_gt!(i, 9);
assert_in_range!(i, 1..100);
assert_abs_diff_eq!(i, 12, 2);

Examples with strings:

let s = "hello world";
assert_starts_with!(s, "hello");
assert_ends_with!(s, "world");
assert_contains!(s, " ");
assert_is_match!(Regex::new(r"h.* w.*").unwrap(), s);

Examples with arrays:

let a = [1, 2, 3];
assert_not_empty!(a);
assert_len_eq_x!(a, 3);
assert_all!(a.into_iter(), |i: i32| i < 4);
assert_any!(a.into_iter(), |i: i32| i > 2);

Highlights

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

Approximations:

• assert_approx_eq!(a, b) ≈ |a-b| ≤ 1e-6
• assert_abs_diff_eq!(a, b, delta) ≈ |a-b| = Δ
• assert_in_delta!(a, b, delta) ≈ |a-b| ≤ Δ
• assert_in_epsilon!(a, b, epsilon) ≈ |a-b| ≤ ε min(a,b)
• assert_in_range!(a, range) ≈ a ∈ range

Groups:

• assert_all!(group, predicate) ≈ group.all(predicate)
• assert_any!(group, predicate) ≈ group.any(predicate)
• assert_is_empty!(group) ≈ a.is_empty()
• assert_len_eq!(a, b) ≈ a.len() = b.len()
• assert_count_eq!(a, b) ≈ a.count() = b.count()

Matching:

• assert_starts_with!(sequence, x) ≈ sequence.starts_with(x)
• assert_ends_with!(sequence, x) ≈ sequence.ends_with(x)
• assert_contains!(container, x) ≈ container.contains(x)
• assert_is_match!(matcher, x) ≈ matcher.is_match(x)
• assert_matches!(expr, pattern) ≈ matches!(expr, pattern)

Results:

• assert_ok!(a) ≈ a is Ok
• assert_err!(a) ≈ a is Err
• assert_ok_eq_x!(a, x) ≈ a is Ok unwrap = x

Options:

• assert_some!(a) ≈ a is Some
• assert_none!(a) ≈ a is None
• assert_some_eq_x!(a, x) ≈ a is Some unwrap = x

Polls:

• assert_ready!(a) ≈ a is Ready
• assert_pending!(a) ≈ a is Pending
• assert_ready_eq_x!(a, x) ≈ a is Ready unwrap = x

Readers:

• assert_fs_read_to_string_eq_x!(path, x ≈ path ⇒ file ⇒ string = x
• assert_io_read_to_string_eq_x!(reader, x) ≈ reader ⇒ bytes ⇒ string = x

Collections:

• assert_iter_eq!(a, b) ≈ a into iter = b into iter
• assert_set_eq!(a, b) ≈ a into set = b into set
• assert_bag_eq!(a, b) ≈ a into bag = b into bag

Commands:

• assert_command_stdout_eq_x!(command, x) ≈ command ⇒ stdout == x
• assert_program_args_stdout_eq_x!(program, args, x) ≈ program.args ⇒ stdout = x

Status:

• assert_status_success!(a) ≈ a.status().success()
• assert_status_code_value_eq_x!(a, x) ≈ a.status().code().unwrap() = x

Infix:

• assert_infix!(a == b) ≈ order operators == != < <= > >=
• assert_infix!(a && b) ≈ logic operators && || ^ & |

For a complete list of modules and macros, see the docs.

Forms

All the macros have forms for an optional message:

• assert_gt!(a, b) ≈ default message
• assert_gt!(a, b, "your text") ≈ custom message

All the macros have forms for different outcomes:

• assert_gt!(1, 2) ≈ panic
• assert_gt_as_result!(1, 2) ≈ Result Err
• debug_assert_gt!(a, b) ≈ panic in debug mode

Many of the macros have a form "compare left item to right item" that compares items of the same kind, and a form "compare left item to right expression" that compares one item to any arbitrary expression:

• assert_len_eq!(a, b) ≈ a.len() = b.len()
• assert_len_eq_x!(a, x) ≈ a.len() = x

Many of the macros has a "success return", which means the macro returns data that you can optionally use for more testing.

• let inner = assert_ok!(result)
• let string = assert_fs_read_to_string_ne!("alfa.txt", "")
• let stdout = assert_command_stdout_gt!("ls", vec![b' '])

Tracking

• Package: assertables-rust-crate
• Version: 9.4.0
• Created: 2021-03-30T15:47:49Z
• Updated: 2024-11-05T16:40:19Z
• License: MIT or Apache-2.0 or GPL-2.0 or GPL-3.0 or contact us for more
• Contact: Joel Parker Henderson ([email protected])