Assertables: Rust crate of assert macros for testing

The assertables Rust crate 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 Rust programming language provides assert macros such as assert!(x) to test code. The assertables crate provides many more for numbers, strings, results, options, iterators, files, streams, and more. See below for examples.

Top benefits:

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

To use this crate, add it to your Cargo.toml file as a development dependency:

[dev-dependencies]
assertables = "*"

Comparable crates: assert_matches, assert_approx_eq, more_asserts, cool_asserts, assert2, claims, static_assertions.

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_in_delta!(a, b, delta); // |a-b| <= delta
• assert_in_epsilon!(a, b, epsilon); // |a-b| <= epsilon * min(a,b)

Groups for iterators, chars, etc.:

• assert_all!(group, predicate); // group.all(predicate)
• assert_any!(group, predicate); // group.any(predicate)

Infix for order operators, logic operators, etc.:

• assert_infix!(a == b); // order: == != < <= > >=
• assert_infix!(a && b); // logic: && || ^ & |

Parts for strings, vectors, etc.:

• assert_starts_with!(whole, part); // whole.starts_with(part)
• assert_ends_with!(whole, part); // whole.ends_with(part)

Lengths and counts for strings, vectors, iterators, etc.:

• assert_len_eq!(item, x); // item.len() == x
• assert_count_eq!(item, x); // item.count() == x
• assert_is_empty!(item); // item.is_empty()

Matching for strings, regex, etc.:

• assert_matches!(expression, pattern); // matches!(expression, pattern)
• assert_is_match!(matcher, matchee); // matcher.is_match(matchee)
• assert_contains!(container, containee); // container.contains(containee)

Collections for arrays, vectors, iterators, sets, maps:

• assert_iter_eq2!(arr1, arr2); // eq ne etc.
• assert_set_eq2!(vec1, vec2); // eq ne etc.
• assert_bag_eq2!(map1, map2); // eq ne etc.

Result Ok/Err:

• assert_ok_eq!(result, x); // result is Ok(x)
• assert_err_eq!(result, x); // result is Err(x)

Option Some/None:

• assert_some_eq!(option, x); // option is Some(x)
• assert_none!(option); // option is None

Poll Ready/Pending:

• assert_ready_eq!(poll, x); // poll is Ready(x)
• assert_pending!(poll); // poll is Pending

Read file system paths and input/output streams:

• assert_fs_read_to_string_eq!(path, x); // read path == x
• assert_io_read_to_string_eq!(stream, x); // read stream == x

Run commands and programs then assert on stdout or stderr:

• assert_command_stdout_eq!(command, x); // command stdout == x
• assert_program_args_stdout_eq!(program, args, x); // program-args stdout == x

Function comparisons, which can be especially helpful for refactoring:

• assert_fn_eq!(fn, x); // fn() == x
• assert_fn_ok_eq!(fn, x); // fn() == Ok(x)
• assert_fn_err_eq!(fn, x); // fn() == Err(x)

Forms

All assertables macros have forms for an optional message:

• assert_gt!(a, b); // automatic error message
• assert_gt!(a, b, "your text"); // custom error message

All assertables macros have forms for different outcomes:

• assert_gt!(a, b); // panic during typical test
• assert_gt_as_result!(a, b); // return Ok or Err
• debug_assert_gt!(a, b); // panic when in debug mode

Many assertables macros have forms for comparing one item (to an expression) or two items (to each other):

• assert_ok_eq!(a, x); // a.unwrap() == x
• assert_ok_eq2!(a, b); // a.unwrap() == b.unwrap()

Migrating from version 8 to version 9

A macro naming convention is changing, to improve usability.

Version 8 naming convention:

assert_foo_eq_expr!(a, x) // compare one item with an expression
assert_foo_eq!(a, b) // compare two items of the same type

Version 9 naming conventions:

assert_foo_eq!(a, x) // compare one item with an expression
assert_foo_eq2!(a, b) // compare two items of the same type

To update your code, one way is to use regular expressions.

Run this first:

• Match: \b(|debug_)(assert_\w*_)(eq|ne|lt|le|gt|ge)(|_as_result)\b

• Replace: $1$2$32$4

Run this second:

• Match: \b(|debug_)(assert_\w*_)(eq|ne|lt|le|gt|ge)_expr(|_as_result)\b

• Replace: $1$2$3$4

Tracking

• Package: assertables-rust-crate
• Version: 9.0.0
• Created: 2021-03-30T15:47:49Z
• Updated: 2024-10-19T21:00:54Z
• 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])