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: joel@joelparkerhenderson.com

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_process, …
• Many more below.

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

assertables = "9.3.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, examples, changes, upgrades, docs.

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

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)

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!(a_path, b_path) ≈ (a_path ⇒ string) = (b_path ⇒ string)
• assert_io_read_to_string_eq!(a_bytes, b_bytes) ≈ (a_bytes ⇒ string) = (b_bytes ⇒ string)

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

Infix notation:

• 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.3.0
• Created: 2021-03-30T15:47:49Z
• Updated: 2024-11-03T21:01:28Z
• License: MIT or Apache-2.0 or GPL-2.0 or GPL-3.0 or contact us for more
• Contact: Joel Parker Henderson (joel@joelparkerhenderson.com)