Readme.md

Galvanic-assert: Matcher-based assertions and expectations for easier testing

This crate provides a new assertion macros (assert_that!, expect_that!, get_expectation_for!) based on matching predicates (matchers) to

• make writing asserts easier
• make reading asserts comprehendable
• easily extend the assertion framework
• provide a large list common matchers
• integrate with galvanic-test and galvanic-mock
• be used with your favourite test framework

The crate is part of galvanic---a complete test framework for Rust. The framework is shipped in three parts, so you can choose to use only the parts you need.

The 2-minute tutorial

Each assertion has the form assert_that!(SOME_VALUE, MATCHES_SOMETHING);. To check if some value satisfies some matching predicate, e.g., less_than, contains_in_order, is_variant!, ...; we can write something like the following to when operating on a single value:

#[macro_use]
extern crate galvanic_assert;
use galvanic_assert::matchers::*;

#[test]
fn expression_should_compute_correct_value {
    assert_that!(&1+2, eq(3));
    // or more wordy ...
    assert_that!(&1+2, is(eq(3)));
}

or assert properties of collections ...

use galvanic_assert::matchers::collection::*;
#[test]
fn expression_should_compute_correct_value {
    /// check for containment
    assert_that!(&vec![5,1,3,4,2], contains_in_any_order(vec![1,2,3,4,5]));
    // check for internal structure
    assert_that!(&vec![4,3,2,1], sorted_descending());
}

or of variants ...

enum Variants {
    First(i32),
    Second { x: i32, y: i32 },
    Third
}

#[test]
fn should_be_the_correct_variant {
    let var = Second { x: 1, y: 2 };
    assert_that!(&var, is_variant!(Variants::Second));
}

If you need to assert multiple fields of a struct or enum you can use a structural matcher ...

enum Baz {
    Var1 { x: i32, y: f64 },
    Var2(i32, f64)
}

#[test]
fn expression_should_compute_correct_value {
    let var1 = Baz::Var1 { x: 12, y: 23.4 };
    assert_that!(&var1, has_structure!(Baz::Var1 {
        x: eq(12),
        y: lt(25.0)
    }));

    let var2 = Baz::Var2(12, 23.4);
    assert_that!(&var2, has_structure!(Baz::Var2 [eq(12), lt(25.0)] ));
}

It is also possible to combine multiple matchers to create more expressive ones ...

#[test]
fn expression_should_compute_correct_value {
    // invert the meaning of a matcher
    assert_that!(&1+2, not(greater_than(3)));
    // join several matchers conjunctively
    assert_that!(&1+2, all_of!(greater_than(0), less_than(5)));
    // join several matchers disjunctively
    assert_that!(&1+2, any_of!(greater_than(5), less_than(5)));
}

If this is not enough you can write your own matchers, either as a closure ...

#[test]
fn expression_should_compute_correct_value {
    assert_that!(&1+2, |x| {
        let builder = MatchResultBuilder::for_("odd");
        if x % 2 == 1 { builder.matched() } else { builder.failed_because("result is not odd") }
    });
}

or if it is easy enough, as an expression ...

#[test]
fn expression_should_compute_correct_value {
    let val = 1 + 2;
    assert_that!(val % 2 == 1, otherwise "result is not odd");
}

If it is more complex implement the Matcher trait for some struct representing the state of the matcher.

Asserting positive things is good, but sometimes we expect that something goes horribly wrong ...

fn press_big_red_button() {
    panic!("shouldn't have done that ...");
}

#[test]
fn someting_should_go_wrong {
    assert_that!(press_big_red_button(), panics);
}

... except when it doesn't.

fn press_faulty_red_button() {
    return;
    panic!("shouldn't have done that ...");
}

#[test]
fn everything_is_fine {
    assert_that!(press_faulty_red_button(), does not panic);
}

Another 2-minutes for learning about expectations

An assertion is immediately check for correctness. That means that any later assertion is not executed and you might lose valuable information for debugging the error. Basically you want as much information as possible to do that. Therefore the the macros expect_that! and get_expectation_for! have been introduced.

Both state an expectation instead of an assertion in exactly the same way as assert_that!---so anything you learned from the last section still applies. The condition is still checked at the point of specification but the inspection of the result is deferred to a later point in time.

The expect_that! macro defers the inspection of the result until the end of the current block:

{
    expect_that!(&1+1, equal_to(0));
    expect_that!(&1+1, less_than(4)); // is executed
}
expect_that!(1+1, panics); // is never executed as the first expectation panics at the end of the block

The get_expectation_for! macro allows for more fine grained control. It returns an Expectation object which can be verified by calling verify ...

let e1 = get_expectation_for!(&1+1, equal_to(0));
let e2 = get_expectation_for!(&1+1, less_than(4)); // is executed
e1.verify();
let e3 = get_expectation_for!(&1+1, panics); // is never executed as e1 panics

... or will be automatically verified once the object goes out of scope.

{
    let e1 = get_expectation_for!(&1+1, equal_to(0));
    let e2 = get_expectation_for!(&1+1, less_than(4)); // is executed
}
let e3 = get_expectation_for!(1+1, panics); // is never executed as e1 panics

Not much more to say---have a look at the documentation and the growing list of matchers.

And remember ... only tested code is happy code!

Contributions

Contributions are very welcome! (Please read and agree with the license.)

The list of included matchers is far from complete. If you encounter a useful matcher please open an issue. Check before if there's already a boolean predicate on the type itself, e.g., like Option::is_none(). Those are already supported by the assertion macros and should only be included if the error message of the Matcher is substantially better than the default one. If something is missing or broken, please open an issue and send (if you want to) a pull request.

For pull requests be sure to include test cases to avoid regressions. Tests for Matchers should be added as integration tests as they test the integration with the assertion macros. Have a look at the existing ones!