Macro verify_that

macro_rules! verify_that {
    ($actual:expr, [$($expecteds:expr),+ $(,)?]) => { ... };
    ($actual:expr, {$($expecteds:expr),+ $(,)?}) => { ... };
    ($actual:expr, $expected:expr $(,)?) => { ... };
}

Checks whether the Matcher given by the second argument matches the first argument.

Evaluates to Result::Ok(()) if the matcher matches and Result::Err(TestAssertionFailure) if it does not. The caller must then decide how to handle the Err variant. It has a few options:

• Abort the current function with the ? operator. This requires that the function return a suitable Result.
• Log the test failure and continue by calling the method and_log_failure.

Of course, one can also use all other standard methods on Result.

Invoking this macro by itself does not cause a test failure to be recorded or output. The resulting Result must be handled as described above to cause the test to be recorded as a failure.

Example:

verify_that!(42, eq(42))?; // This will pass.
verify_that!(42, eq(123)).and_log_failure();
            // This will log a test failure and allow execution to continue.
let _ = verify_that!(42, eq(123)); // This will do nothing.
verify_that!(42, eq(123))?; // This will fail, returning immediately.
verify_that!(42, eq(0))?; // This will not run.

This macro has special support for matching against container. Namely:

• verify_that!(actual, [m1, m2, ...]) is equivalent to verify_that!(actual, elements_are![m1, m2, ...])
• verify_that!(actual, {m1, m2, ...}) is equivalent to verify_that!(actual, unordered_elements_are![m1, m2, ...])

Matching against tuples

One can match against a tuple by constructing a tuple of matchers as follows:

verify_that!((123, 456), (eq(123), eq(456)))?; // Passes
verify_that!((123, 456), (eq(123), eq(0)))?; // Fails: second matcher does not match

This also works with composed matchers:

verify_that!((123, 456), not((eq(456), eq(123))))?; // Passes

Matchers must correspond to the actual tuple in count and type. Otherwise the test will fail to compile.

verify_that!((123, 456), (eq(123),))?; // Does not compile: wrong tuple size
verify_that!((123, "A string"), (eq(123), eq(456)))?; // Does not compile: wrong type

All fields must be covered by matchers. Use anything for fields which are not relevant for the test.

verify_that!((123, 456), (eq(123), anything()))

This supports tuples of up to 12 elements. Tuples longer than that do not automatically inherit the Debug trait from their members, so are generally not supported; see Rust by Example.