Struct Spec

pub struct Spec<'a, S, R> { /* private fields */ }

Data of an actual assertion.

It holds the data needed to execute an assertion such as the subject, the name of the subject or expression, an optional description of the current assertion and the location of the assertion in the source code respectively test code.

It also holds the concrete FailingStrategy on how to behave in case an assertion fails.

In case of the CollectFailures failing strategy, the AssertFailures are collected in this struct.

Implementations

impl<S, R> Spec<'_, S, R>

pub fn subject(&self) -> &S

Returns the subject.

pub fn expression(&self) -> Option<Expression<'_>>

Returns the expression (or subject name) if one has been set.

pub fn location(&self) -> Option<Location<'_>>

Returns the location in source code or test code if it has been set.

pub fn description(&self) -> Option<&str>

Returns the description or the assertion if it has been set.

pub const fn diff_format(&self) -> &DiffFormat

Returns the diff format used with this assertion.

pub fn failing_strategy(&self) -> &R

Returns the failing strategy that is used in case an assertion fails.

pub fn failures(&self) -> Vec<AssertFailure>

Returns the assertion failures that have been collected so far.

pub fn display_failures(&self) -> Vec<String>

Returns the assertion failures collected so far as formatted text.

impl<'a, S, R> Spec<'a, S, R>

pub const fn new(subject: S, failing_strategy: R) -> Self

Constructs a new Spec for the given subject and with the specified failing strategy.

The diff format is set to “no highlighting”. Failure messages will not highlight differences between the actual and the expected value.

pub const fn named(self, subject_name: &'a str) -> Self

Sets the subject name or expression for this assertion.

pub const fn described_as(self, description: &'a str) -> Self

Sets a custom description about what is being asserted.

pub const fn located_at(self, location: Location<'a>) -> Self

Sets the location of the assertion in the source code respectively test code.

pub const fn with_diff_format(self, diff_format: DiffFormat) -> Self

Sets the diff format that is used to highlight differences between the actual value and the expected value.

Note: This method must be called before an assertion method is called to have an effect on the failure message of the assertion as failure messages are formatted immediately when an assertion is executed.

pub fn with_configured_diff_format(self) -> Self

Available on crate feature colored only.

Sets the diff format used to highlight differences between the actual value and the expected value according the configured mode.

The mode is configured via environment variables like described in the module colored.

pub fn extracting<F, U>(self, extractor: F) -> Spec<'a, U, R>

where F: FnOnce(S) -> U,

Maps the current subject to some other value.

It takes a closure that maps the current subject to a new subject and returns a new Spec with the value returned by the closure as the new subject. The new subject may have a different type than the original subject. All other data like expression, description and location are taken over from this Spec into the returned Spec.

This function is useful when having a custom type and some specific property of this type shall be asserted only.

This is an alias function to the mapping() function. Both functions do exactly the same. The idea is to provide different names to be able to express the intent more clearly when used in assertions.

Example

use asserting::prelude::*;

struct MyStruct {
    important_property: String,
    other_property: f64,
}

let some_thing = MyStruct {
    important_property: "imperdiet aliqua zzril eiusmod".into(),
    other_property: 99.9,
};

assert_that!(some_thing).extracting(|s| s.important_property)
    .is_equal_to("imperdiet aliqua zzril eiusmod");

pub fn mapping<F, U>(self, mapper: F) -> Spec<'a, U, R>

where F: FnOnce(S) -> U,

Maps the current subject to some other value.

It takes a closure that maps the current subject to a new subject and returns a new Spec with the value returned by the closure as the new subject. The new subject may have a different type than the original subject. All other data like expression, description and location are taken over from this Spec into the returned Spec.

This function is useful if some type does not implement a trait that is required for an assertion.

Spec also provides the extracting() function, which is an alias to this function. Both functions do exactly the same. Choose that function of which its name expresses the intent more clearly.

Example

use asserting::prelude::*;

struct Point {
    x: i64,
    y: i64,
}

let target = Point { x: 12, y: -64 };

assert_that!(target).mapping(|s| (s.x, s.y)).is_equal_to((12, -64));

The custom type Point does not implement the PartialEq trait nor the Debug trait, which are both required for an is_equal_to assertion. So we map the subject of the type Point to a tuple of its fields.

impl<S, R> Spec<'_, S, R>

where R: FailingStrategy,

pub fn expecting(self, expectation: impl Expectation<S>) -> Self

Asserts the given expectation.

In case the expectation is not meet, it does fail according the current failing strategy of this Spec.

This method is called from the implementations of the assertion traits defined in the assertions module. Implementations of custom assertions will call this method with a proper expectation.

Examples

use asserting::expectations::{IsEmpty, IsEqualTo};
use asserting::prelude::*;

assert_that!(7 * 6).expecting(IsEqualTo {expected: 42 });

assert_that!("").expecting(IsEmpty);

pub fn satisfies<P>(self, predicate: P) -> Self

where P: Fn(&S) -> bool,

Asserts whether the given predicate is meet.

This method takes a predicate function and calls it as an expectation. In case the predicate function returns false, it does fail with a generic failure message and according to the current failing strategy of this Spec.

This method can be used to do simple custom assertions without implementing an Expectation and an assertion trait.

Examples

use asserting::prelude::*;

fn is_odd(value: &i32) -> bool {
    value & 1 == 1
}

assert_that!(37).satisfies(is_odd);

let failures = verify_that!(22).satisfies(is_odd).display_failures();

assert_that!(failures).contains_exactly([
    "assertion failed: expected 22 to satisfy the given predicate, but returned false\n"
]);

To assert a predicate with a custom failure message instead of the generic one, use the method satisfies_with_message.

pub fn satisfies_with_message<P>( self, message: impl Into<String>, predicate: P, ) -> Self

where P: Fn(&S) -> bool,

Asserts whether the given predicate is meet.

This method takes a predicate function and calls it as an expectation. In case the predicate function returns false, it does fail with the provided failure message and according to the current failing strategy of this Spec.

This method can be used to do simple custom assertions without implementing an Expectation and an assertion trait.

Examples

use asserting::prelude::*;

fn is_odd(value: &i32) -> bool {
    value & 1 == 1
}

assert_that!(37).satisfies_with_message("expected my number to be odd", is_odd);

let failures = verify_that!(22)
        .satisfies_with_message("expected my number to be odd", is_odd)
        .display_failures();

assert_that!(failures).contains_exactly([
    "assertion failed: expected my number to be odd\n"
]);

To assert a predicate with a generic failure message instead of providing one use the method satisfies.

impl<S> Spec<'_, S, CollectFailures>

pub fn soft_panic(&self)

Turns assertions into “soft assertions”.

It executes all specified assertions on a Spec and if at least one assertion fails, it panics. The panic message contains the messages of all assertions that have failed.

This method is only available on Specs with the CollectFailures-FailingStrategy. That is any Spec contructed by the macros verify_that! and verify_that_code! or by the functions verify_that() and verify_that_code().

On a Spec with the PanicOnFail-FailingStrategy it would not work as the very first failing assertion panics immediately, and later assertions never get executed.

Examples

Running the following two assertions in “soft” mode:

use asserting::prelude::*;

verify_that!("the answer to all important questions is 42")
    .contains("unimportant")
    .has_at_most_length(41)
    .soft_panic();

executes both assertions and prints the messages of both failing assertions in the panic message:

assertion failed: expected subject to contain "unimportant"
   but was: "the answer to all important questions is 42"
  expected: "unimportant"

assertion failed: expected subject has at most a length of 41
   but was: 43
  expected: <= 41

To highlight differences in failure messages of soft assertions use the with_configured_diff_format() method, like so:

use asserting::prelude::*;

verify_that!("the answer to all important questions is 42")
    .with_configured_diff_format()
    .contains("important")
    .has_at_most_length(43)
    .soft_panic();

Trait Implementations

impl<R> AssertBoolean for Spec<'_, bool, R>

where R: FailingStrategy,

fn is_true(self) -> Self

Verifies that the subject is true.

fn is_false(self) -> Self

Verifies that the subject is false.

impl<S, R> AssertCodePanics for Spec<'_, Code<S>, R>

where S: FnOnce(), R: FailingStrategy,

fn does_not_panic(self) -> Self

Available on crate feature panic only.

Verifies that the actual code under test does not panic.

fn panics(self) -> Self

Available on crate feature panic only.

Verifies that the actual code under test panics with any message.

fn panics_with_message(self, message: impl Into<String>) -> Self

Available on crate feature panic only.

Verifies that the actual code under test panics with the given message.

impl<S, R> AssertEmptiness for Spec<'_, S, R>

where S: IsEmptyProperty + Debug, R: FailingStrategy,

fn is_empty(self) -> Self

Verifies that the subject is empty.

fn is_not_empty(self) -> Self

Verifies that the subject is not empty.

impl<S, E, R> AssertEquality<E> for Spec<'_, S, R>

where S: PartialEq<E> + Debug, E: Debug, R: FailingStrategy,

fn is_equal_to(self, expected: E) -> Self

Verifies that the subject is equal to some other value.

fn is_not_equal_to(self, expected: E) -> Self

Verifies that subject is not equal to some other value.

impl<S, R> AssertHasCharCount<usize> for Spec<'_, S, R>

where S: CharCountProperty + Debug, R: FailingStrategy,

fn has_char_count(self, expected_char_count: usize) -> Self

Verifies that the subject contains the expected number of characters.

fn has_char_count_in_range<U>(self, expected_range: U) -> Self

where U: RangeBounds<usize> + Debug,

Verifies that the subject contains a number of characters that is in the expected range.

fn has_char_count_less_than(self, expected_char_count: usize) -> Self

Verifies that the subject contains less than the expected number of characters.

fn has_char_count_greater_than(self, expected_char_count: usize) -> Self

Verifies that the subject contains more than the expected number of characters.

fn has_at_most_char_count(self, expected_char_count: usize) -> Self

Verifies that the subject contains at least the expected number of characters.

fn has_at_least_char_count(self, expected_char_count: usize) -> Self

Verifies that the subject contains at least the expected number of characters.

impl<T, E, X, R> AssertHasError<X> for Spec<'_, Result<T, E>, R>

where T: Debug, E: PartialEq<X> + Debug, X: Debug, R: FailingStrategy,

fn has_error(self, expected: X) -> Self

Verifies that the subject holds an error value that is equal to the expected one.

impl<'a, T, E, X, R> AssertHasErrorMessage<'a, X, R> for Spec<'a, Result<T, E>, R>

where T: Debug, E: Display, X: Debug, String: PartialEq<X>, R: FailingStrategy,

fn has_error_message(self, expected: X) -> Spec<'a, String, R>

Verifies that the subject is an error value with the expected message.

impl<S, R> AssertHasLength<usize> for Spec<'_, S, R>

where S: LengthProperty + Debug, R: FailingStrategy,

fn has_length(self, expected_length: usize) -> Self

Verifies that the subject has the expected length.

fn has_length_in_range<U>(self, expected_range: U) -> Self

where U: RangeBounds<usize> + Debug,

Verifies that the subject has a length in the expected range.

fn has_length_less_than(self, expected_length: usize) -> Self

Verifies that the subject has a length that is less than the expected length.

fn has_length_greater_than(self, expected_length: usize) -> Self

Verifies that the subject has a length that is greater than the expected length.

fn has_at_most_length(self, expected_length: usize) -> Self

Verifies that the subject has a length that is at most the expected length.

fn has_at_least_length(self, expected_length: usize) -> Self

Verifies that the subject has a length that is at least the expected length.

impl<S, E, R> AssertHasValue<E> for Spec<'_, Option<S>, R>

where S: PartialEq<E> + Debug, E: Debug, R: FailingStrategy,

fn has_value(self, expected: E) -> Self

Verifies that the subject holds a value that is equal to the expected one.

impl<T, E, X, R> AssertHasValue<X> for Spec<'_, Result<T, E>, R>

where T: PartialEq<X> + Debug, E: Debug, X: Debug, R: FailingStrategy,

fn has_value(self, expected: X) -> Self

Verifies that the subject holds a value that is equal to the expected one.

impl<S, E, R> AssertInRange<E> for Spec<'_, S, R>

where S: PartialOrd<E> + Debug, E: PartialOrd<S> + Debug, R: FailingStrategy,

fn is_in_range<U>(self, range: U) -> Self

where U: RangeBounds<E> + Debug,

Verifies that the subject is within the expected range.

fn is_not_in_range<U>(self, range: U) -> Self

where U: RangeBounds<E> + Debug,

Verifies that the subject is not within the expected range.

impl<S, R> AssertInfinity for Spec<'_, S, R>

where S: InfinityProperty + Debug, R: FailingStrategy,

fn is_infinite(self) -> Self

Verifies that the subject is an infinite number.

fn is_finite(self) -> Self

Verifies that the subject is a finite number.

impl<R> AssertIsCloseToWithDefaultMargin<f32> for Spec<'_, f32, R>

where R: FailingStrategy,

fn is_close_to(self, expected: f32) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value is approximately equal to the expected value.

fn is_not_close_to(self, expected: f32) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value is not approximately equal to the expected value.

impl<R> AssertIsCloseToWithDefaultMargin<f64> for Spec<'_, f64, R>

where R: FailingStrategy,

fn is_close_to(self, expected: f64) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value is approximately equal to the expected value.

fn is_not_close_to(self, expected: f64) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value is not approximately equal to the expected value.

impl<R> AssertIsCloseToWithinMargin<f32, F32Margin> for Spec<'_, f32, R>

where R: FailingStrategy,

fn is_close_to_with_margin( self, expected: f32, margin: impl Into<F32Margin>, ) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value is approximately equal to the expected value.

fn is_not_close_to_with_margin( self, expected: f32, margin: impl Into<F32Margin>, ) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value not approximately equals to the expected value.

impl<R> AssertIsCloseToWithinMargin<f64, F64Margin> for Spec<'_, f64, R>

where R: FailingStrategy,

fn is_close_to_with_margin( self, expected: f64, margin: impl Into<F64Margin>, ) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value is approximately equal to the expected value.

fn is_not_close_to_with_margin( self, expected: f64, margin: impl Into<F64Margin>, ) -> Self

Available on crate feature float-cmp only.

Verifies that the actual value not approximately equals to the expected value.

impl<'a, S, T, E, R> AssertIteratorContains<'a, Vec<T>, E, R> for Spec<'a, S, R>

where S: IntoIterator<Item = T>, T: PartialEq<E> + Debug, E: Debug, R: FailingStrategy,

fn contains(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains the expected value.

impl<'a, S, T, E, R> AssertIteratorContainsInAnyOrder<'a, Vec<T>, E, R> for Spec<'a, S, R>

where S: IntoIterator<Item = T>, T: PartialEq<<E as IntoIterator>::Item> + Debug, E: IntoIterator, <E as IntoIterator>::Item: Debug, R: FailingStrategy,

fn contains_exactly_in_any_order(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains exactly the given values and nothing else in any order.

fn contains_any_of(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains at least one of the given values.

fn contains_all_of(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains the given values in any order.

fn contains_only(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains only the given values and nothing else in any order and ignoring duplicates.

fn contains_only_once(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains only the given values in any order and each of them only once.

impl<'a, S, T, E, R> AssertIteratorContainsInOrder<'a, Vec<T>, E, R> for Spec<'a, S, R>

where S: IntoIterator<Item = T>, <S as IntoIterator>::IntoIter: DefinedOrderProperty, E: IntoIterator, <E as IntoIterator>::IntoIter: DefinedOrderProperty, <E as IntoIterator>::Item: Debug, T: PartialEq<<E as IntoIterator>::Item> + Debug, R: FailingStrategy,

fn contains_exactly(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains exactly the given values and nothing else in the given order.

fn contains_sequence(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains the given sequence of values in the given order and without extra values between the sequence values.

fn contains_all_in_order(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains all the given values and in the given order, possibly with other values between them.

fn starts_with(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains the given values as the first elements in order.

fn ends_with(self, expected: E) -> Spec<'a, Vec<T>, R>

Verifies that the actual collection/iterator contains the given values as the last elements in order.

impl<S, R> AssertNotANumber for Spec<'_, S, R>

where S: IsNanProperty + Debug, R: FailingStrategy,

fn is_not_a_number(self) -> Self

Verifies that the subject is not a number.

fn is_a_number(self) -> Self

Verifies that the subject is a number.

impl<S, R> AssertNumericIdentity for Spec<'_, S, R>

where S: AdditiveIdentityProperty + MultiplicativeIdentityProperty + PartialEq + Debug, R: FailingStrategy,

fn is_zero(self) -> Self

Verifies whether the subject is the additive identity (zero).

fn is_one(self) -> Self

Verifies whether the subject is the multiplicative identity (one).

impl<S, R> AssertOption for Spec<'_, Option<S>, R>

where S: Debug, R: FailingStrategy,

fn is_some(self) -> Self

Verifies that the subject has some value.

fn is_none(self) -> Self

Verifies that the subject has no value.

impl<'a, T, R> AssertOptionValue<'a, T, R> for Spec<'a, Option<T>, R>

where R: FailingStrategy,

fn some(self) -> Spec<'a, T, R>

Maps the subject to the option’s value if it has some. Otherwise, this assertion fails.

impl<S, E, R> AssertOrder<E> for Spec<'_, S, R>

where S: PartialOrd<E> + Debug, E: Debug, R: FailingStrategy,

fn is_less_than(self, expected: E) -> Self

Verifies that the subject is less than some expected value.

fn is_greater_than(self, expected: E) -> Self

Verifies that the subject is greater than some expected value.

fn is_at_most(self, expected: E) -> Self

Verifies that the subject is less than or equal to some expected value.

fn is_at_least(self, expected: E) -> Self

Verifies that the subject is greater than or equal to some expected value.

fn is_before(self, expected: E) -> Self

Verifies that the subject is before some expected value.

fn is_after(self, expected: E) -> Self

Verifies that the subject is after some expected value.

fn is_between(self, min: E, max: E) -> Self

Verifies that the subject is between a min value and a max value.

impl<T, E, R> AssertResult for Spec<'_, Result<T, E>, R>

where T: Debug, E: Debug, R: FailingStrategy,

fn is_ok(self) -> Self

Verifies that the subject has an ok value.

fn is_err(self) -> Self

Verifies that the subject has an err value.

impl<'a, T, E, R> AssertResultValue<'a, T, E, R> for Spec<'a, Result<T, E>, R>

where T: Debug, E: Debug,

fn ok(self) -> Spec<'a, T, R>

Maps the subject to the result’s ok value.

fn err(self) -> Spec<'a, E, R>

Maps the subject to the result’s err value.

impl<S, R> AssertSignum for Spec<'_, S, R>

where S: SignumProperty + Debug, R: FailingStrategy,

fn is_negative(self) -> Self

Verifies that the subject is a negative number.

fn is_not_negative(self) -> Self

Verifies that the subject is a non-negative number.

fn is_positive(self) -> Self

Verifies that the subject is a positive number.

fn is_not_positive(self) -> Self

Verifies that the subject is a non-positive number.

impl<'a, S, R> AssertStringContainsAnyOf<&'a [char]> for Spec<'a, S, R>

where S: 'a + AsRef<str> + Debug, R: FailingStrategy,

fn contains_any_of(self, expected: &'a [char]) -> Self

Verifies that a string contains any char from a collection of chars.

impl<'a, S, R, const N: usize> AssertStringContainsAnyOf<&'a [char; N]> for Spec<'a, S, R>

where S: 'a + AsRef<str> + Debug, R: FailingStrategy,

fn contains_any_of(self, expected: &'a [char; N]) -> Self

Verifies that a string contains any char from a collection of chars.

impl<'a, S, R, const N: usize> AssertStringContainsAnyOf<[char; N]> for Spec<'a, S, R>

where S: 'a + AsRef<str> + Debug, R: FailingStrategy,

fn contains_any_of(self, expected: [char; N]) -> Self

Verifies that a string contains any char from a collection of chars.

impl<S, R> AssertStringMatches for Spec<'_, S, R>

where S: AsRef<str> + Debug, R: FailingStrategy,

fn matches(self, regex_pattern: &str) -> Self

Available on crate feature regex only.

Verifies that a string matches the given regex pattern.

impl<'a, S, R> AssertStringPattern<&'a str> for Spec<'a, S, R>

where S: 'a + AsRef<str> + Debug, R: FailingStrategy,

fn contains(self, pattern: &'a str) -> Self

Verifies that a string contains a substring or character.

fn starts_with(self, pattern: &str) -> Self

Verifies that a string starts with a substring or character.

fn ends_with(self, pattern: &str) -> Self

Verifies that a string ends with a substring or character.

impl<'a, S, R> AssertStringPattern<String> for Spec<'a, S, R>

where S: 'a + AsRef<str> + Debug, R: FailingStrategy,

fn contains(self, pattern: String) -> Self

Verifies that a string contains a substring or character.

fn starts_with(self, pattern: String) -> Self

Verifies that a string starts with a substring or character.

fn ends_with(self, pattern: String) -> Self

Verifies that a string ends with a substring or character.

impl<'a, S, R> AssertStringPattern<char> for Spec<'a, S, R>

where S: 'a + AsRef<str> + Debug, R: FailingStrategy,

fn contains(self, expected: char) -> Self

Verifies that a string contains a substring or character.

fn starts_with(self, expected: char) -> Self

Verifies that a string starts with a substring or character.

fn ends_with(self, pattern: char) -> Self

Verifies that a string ends with a substring or character.