Asserting

Fluent assertions for tests in Rust that are convenient to write and easy to extend.

The goals for asserting are:

1. assertions are convenient to write and easy to read
2. helpful error messages in case of failing assertions
3. colored diffs between expected and actual values
4. provide a sensible amount of assertions out of the box
5. do not require from asserted types to implement traits if it is not absolutely necessary
6. support for asserting custom types with provided assertions
7. writing custom assertions requires minimal effort
8. support no-std environments

Convenient to write

The expected value does not need to be exactly of the same type as the subject. For example, instead of writing:

#[test]
fn the_message_is_right() {
    let message = "lorem consectetur ipsum exercitation".to_string();

    assert_that!(message).is_equal_to("lorem consectetur ipsum exercitation".to_string());
}

with asserting we can write:

#[test]
fn the_message_is_right() {
    let message = "lorem consectetur ipsum exercitation".to_string();

    assert_that!(message).is_equal_to("lorem consectetur ipsum exercitation");
}

Note that we do not convert the expected value to a String.

This might seem to be a minor advantage, but when writing assertions for a collection of Strings, converting every expected &str to String results in lots of noise.

Easy to extend

Easy to extend means that we can write assertions for custom types with minimal effort.

asserting provides three kinds of custom assertions:

1. use any predicate function as a custom assertion (see "predicate as custom assertion")
2. property based assertions can be used with any type that implements the related property ( see "property based assertions")
3. write custom assertions by implementing two simple traits (see "custom assertions")

The mentioned references link to a chapter in the crate's documentation that describes the possibilities for custom assertions including examples.

no-std support

To use asserting in a no-std environment disable the default features. Features that do not require std can still be added.

[dev-dependencies]
asserting = { version = "0.3", default-features = false, features = ["colored", "float"] }

An allocator is still needed for no-std.

Highlighted differences

asserting can highlight the differences between the expected value(s) and the actual value(s) when printing assertion failures to the terminal. The colored diffs in assertion failures look like this:

It supports different variants of how differences are highlighted.

The mode can be configured by setting the environment variable ASSERTING_HIGHLIGHT_DIFFS to one of the modes in the table above. The value is case-insensitive. E.g. setting the environment variable to values like Red-Blue, Bold or OFF works as well.

The intended way for configuring the highlighting mode is to set the environment variable in the configuration for Cargo by adding it to the [env] section in your ~/.cargo/config.toml file:

[env]
ASSERTING_HIGHLIGHT_DIFFS = "red-blue"

By default the mode red-green is used. Differences are colored in green and red.

Differences are only highlighted if the crate feature colored is enabled. The configuration via the environment variable only works when the crate feature std is enabled too. In no-std projects the default colors red and green are used.

Available Assertions

This chapter gives an overview for the assertions provided by asserting. For a comprehensive list of available assertions including examples browse the documentation of the assertions module. The documentation of the assertion traits contain examples on how to use each assertion. The crate level documentation contains lots of examples as a quick introduction.

Equality

for all types that implement PartialEq<E> with E being the type of the expected value.

Order

for all types that implement PartialOrd<E> with E being the type of the expected value.

Range

for all types T that implement PartialOrd<E> and E implementing PartialOrd<T> with E being the type of the expected value.

Float

for floating point numbers of type f32 and f64.

requires crate feature float which is enabled by default.

Boolean

for bool.

String

for all string types of Rust: String, str, OsString, OsStr, CString and CStr.

Option

for the Option type.

Result

for the Result type.

Emptiness

for collections and strings.

The implementation of these assertions is based on the property trait IsEmptyProperty. Implementing this property for any type enables these assertions for that type.

Length (Size)

for collections and strings.

The implementation of these assertions is based on the property trait LengthProperty. Implementing this property for any type enables these assertions for that type.

Iterator / Collection

for all iterators.

for iterators that yield items in a well-defined order.

All the above assertions provided for any kind of iterator plus the following:

Panic

for code inside a closure.

requires the crate feature panic which is enabled by default.

To start assertions on code use the assert_that_code!() macro.