#assert #check #test #unit-test

dev assert2

assert!(…) and check!(…) macros inspired by Catch2

17 unstable releases (3 breaking)

0.3.3 Sep 29, 2020
0.3.2 Sep 9, 2020
0.3.1 Jul 25, 2020
0.2.1 Apr 26, 2020
0.0.9 Jan 12, 2020

#32 in Debugging

Download history 104/week @ 2020-08-10 80/week @ 2020-08-17 82/week @ 2020-08-24 72/week @ 2020-08-31 135/week @ 2020-09-07 86/week @ 2020-09-14 63/week @ 2020-09-21 99/week @ 2020-09-28 78/week @ 2020-10-05 93/week @ 2020-10-12 85/week @ 2020-10-19 63/week @ 2020-10-26 82/week @ 2020-11-02 71/week @ 2020-11-09 57/week @ 2020-11-16 73/week @ 2020-11-23

298 downloads per month
Used in 17 crates (16 directly)

BSD-2-Clause

22KB
263 lines

assert2

All-purpose assert!(...) and check!(...) macros, inspired by Catch2. There is also a debug_assert!(...) macro that is disabled on optimized builds by default. As cherry on top there is a let_assert!(...) macro that lets you test a pattern while capturing parts of it.

Why these macros?

These macros offer some benefits over the assertions from the standard library:

  • The macros parse your expression to detect comparisons and adjust the error message accordingly. No more assert_eq or assert_ne, just write assert!(1 + 1 == 2), or even assert!(1 + 1 > 1)!
  • You can test for pattern matches: assert!(let Err(_) = File::open("/non/existing/file")).
  • You can capture parts of the pattern for further testing by using the let_assert!(...) macro.
  • The check macro can be used to perform multiple checks before panicking.
  • The macros provide more information when the assertion fails.
  • Colored failure messages!

The macros also accept additional arguments for a custom message, so it is fully compatible with std::assert. That means you don't have to worry about overwriting the standard assert with use assert2::assert.

Examples

check!(6 + 1 <= 2 * 3);

Assertion error


check!(true && false);

Assertion error


check!(let Ok(_) = File::open("/non/existing/file"));

Assertion error


let_assert!(Err(e) = File::open("/non/existing/file"));
check!(e.kind() == ErrorKind::PermissionDenied);

Assertion error

assert vs check

The crate provides two macros: check!(...) and assert!(...). The main difference is that check is really intended for test cases and doesn't immediately panic. Instead, it will print the assertion error and fail the test. This allows you to run multiple checks and can help to determine the reason of a test failure more easily. The assert macro on the other hand simply prints the error and panics, and can be used outside of tests just as well.

Currently, check uses a scope guard to delay the panic until the current scope ends. Ideally, check doesn't panic at all, but only signals that a test case has failed. If this becomes possible in the future, the check macro will change, so you should not rely on check to panic.

Difference between stable and nightly.

If available, the crate uses the proc_macro_span feature to get the original source code. On stable and beta, it falls back to stringifying the expression. This makes the output a bit more readable on nightly.

The let_assert!() macro

You can also use the let_assert!(...). It is very similar to assert!(let ...), but all placeholders will be made available as variables in the calling scope.

This allows you to run additional checks on the captured variables.

For example:

let_assert!(Ok(foo) = Foo::try_new("bar"));
check!(foo.name() == "bar");

let_assert!(Err(Error::InvalidName(e)) = Foo::try_new("bogus name"));
check!(e.name() == "bogus name");
check!(e.to_string() == "invalid name: bogus name");

Controlling colored output.

Colored output can be controlled using environment variables, as per the clicolors spec:

  • CLICOLOR != 0: ANSI colors are supported and should be used when the program isn't piped.
  • CLICOLOR == 0: Don't output ANSI color escape codes.
  • CLICOLOR_FORCE != 0: ANSI colors should be enabled no matter what.

Dependencies

~0.5–1MB
~22K SLoC