Crate expectest

This project is inspired by Nimble for Swift. It provides matchers and matcher functions to express expectations in tests for common cases, such as: Equality, Order, Option, Result, etc. The crate also provides instruments to implement custom matchers for your project’s domain.

You express expectations in your tests using three basic constructs:

expect!(...).to(...);
expect!(...).to_not(...);
expect!(...).not_to(...);

If a test fails, you will see the reason in a nice, human readable format.

Example

let result = vec![1, 2, 2];
expect!(result).to(be_equal_to([1, 2, 3]));
// --
// This will print:
// expected to be equal to <[1, 2, 3]>, got <[1, 2, 2]>

Structure

The crate consists of two modules core and matchers but for general use you can access all you need using prelude module. The expect! macro saves file name and line number to print it later if an expectation fails. Internally the macro uses the expect function which is also available to you.

Usage

The crate is meant to be used in tests, so we recommend you include it as a dev dependency with #[cfg(test)] attribute.

In your Cargo.toml:

[dev-dependencies]
expectest = "0.10.0"

If you prefer nightly rust and want failure messages to be integrated in rust’s standard panic message, enable nightly feature:

[dev-dependencies]
expectest = { version = "0.10.0", features = ["nightly"] }

In your tests:

use expectest::prelude::*;

Matchers

Keep in mind that some matchers work with types that implement Debug trait to print inner representation. You need to implement or derive it for your types.

Equality

For types that implement PartialEq trait you can use be_equal_to function or its alias be_eq.

expect!("hello".to_string()).to(be_equal_to("hello"));

Equality of Floats

With default delta equal to 0.001.

expect!(12.001_f64).to(be_close_to(12.0));
expect!(12.1_f64).to(be_close_to(12.0).delta(0.1));

Order

For types that implement PartialOrd trait you can use any of the following matchers:

• be_less_than
• be_less_or_equal_to
• be_greater_than
• be_greater_or_equal_to

or their aliases respectively:

• be_lt
• be_le
• be_gt
• be_ge

expect!(1).to(be_greater_than(0));

Ranges

For two-sided checks range matcher can be used:

• be_within_range

expect!(1).to(be_within_range(0..=1));

Option<T>

Use be_some or be_none matchers.

expect!(Some(9)).to(be_some());
expect!(Some(9)).to(be_some().value(9));

Result<T, E>

Use be_ok or be_err matchers.

expect!("4".parse::<u32>()).to(be_ok());
expect!("4".parse::<u32>()).to(be_ok().value(4));

Iterators

For types that implement Iterator + Clone trait.

Use be_empty or have_count matchers.

expect!("".chars()).to(be_empty());
expect!("abc".chars()).to(have_count(3));

Boolean

Use be_true or be_false matchers.

expect!(9 == 9).to(be_true());

That’s all you need to know.

Happy Testing 😊

Modules

core

A module contains core types of this library.

matchers

A module contains matchers.

prelude

A module contains reexport of all useful functions.

Macros

expect

A macro intended to use as a powerful replacement of expect function.