Trait Matcher

Source

pub trait Matcher<ActualT: Debug + ?Sized>: Describable {
    // Required method
    fn matches(&self, actual: &ActualT) -> MatcherResult;

    // Provided method
    fn explain_match(&self, actual: &ActualT) -> Description { ... }
}

Expand description

Represents an arbitrary condition on data of the given type which can be checked to perform an assertion.

Matchers are the core of the assertion language of Test That!. They can be combined and composed to assert on complex data structures. The variety of available matchers allows precise specification of the intent of the assertion.

Matchers can be logically combined with the and and or methods as well as the not matcher.

This trait is implemented for tuples of up to twelve arbitrary implementations of Matcher. So one can match tuples of up to twelve items using corresponding tuple of matchers.

let value = (1, "Hello, world");
assert_that!(value, (eq(1), ends_with("world")));

Tuples of more than twelve items do not automatically inherit the Debug trait from their members, so are generally not supported; see Rust by Example.

Required Methods§

Source

fn matches(&self, actual: &ActualT) -> MatcherResult

Returns whether the condition matches the datum actual.

The trait implementation defines what it means to “match”. Often the matching condition is based on data stored in the matcher. For example, eq matches when its stored expected value is equal (in the sense of the == operator) to the value actual.

Provided Methods§

Source

fn explain_match(&self, actual: &ActualT) -> Description

Prepares a String describing how the expected value encoded in this instance matches or does not match the given value actual.

This should be in the form of a relative clause, i.e. something starting with a relative pronoun such as “which” or “whose”. It will appear next to the actual value in an assertion failure. For example:

Value of: ...
Expected: ...
Actual: ["Something"], which does not contain "Something else"
                       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The default implementation relies on describe. Thus it does not make any use of the actual value itself, but rather only whether the value is matched.

Override the default implementation to provide additional context on why a particular value matched or did not match. For example, the container_eq matcher displays information on which elements of the actual value were not present in the expected value and vice versa.

This implementation should be overridden in any matcher which contains one or more inner matchers. The implementation should invoke explain_match on the inner matchers, so that the generated match explanation also reflects their implementation. Without this, the match explanation of the inner matchers will not be able to make use of the actual value at all.

For example, the explain_match implementation of the matcher points_to defers immediately to the inner matcher and appears as follows:

fn explain_match(&self, actual: &Self::ActualT) -> Description {
    self.expected.explain_match(actual.deref())
}

The matcher can also provide some additional context before deferring to an inner matcher. In that case it should invoke explain_match on the inner matcher at a point where a relative clause would fit. For example:

fn explain_match(&self, actual: &Self::ActualT) -> Description {
    Description::new()
        .text("which points to a value")
        .nested(self.expected.explain_match(actual.deref()))
}

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Matcher

Trait Matcher Copy item path

Required Methods§

fn matches(&self, actual: &ActualT) -> MatcherResult

Provided Methods§

fn explain_match(&self, actual: &ActualT) -> Description

Dyn Compatibility§

Implementations on Foreign Types§

impl Matcher<()> for ()

fn matches(&self, _: &()) -> MatcherResult

fn matches( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11), ) -> MatcherResult

fn explain_match( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10, T11), ) -> Description

fn matches( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10), ) -> MatcherResult

fn explain_match( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8, T9, T10), ) -> Description

fn matches( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8, T9), ) -> MatcherResult

fn explain_match( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8, T9), ) -> Description

fn matches( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8), ) -> MatcherResult

fn explain_match( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7, T8), ) -> Description

fn matches(&self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7)) -> MatcherResult

fn explain_match( &self, actual: &(T0, T1, T2, T3, T4, T5, T6, T7), ) -> Description

impl<T0: Debug, I0: Matcher<T0>, T1: Debug, I1: Matcher<T1>, T2: Debug, I2: Matcher<T2>, T3: Debug, I3: Matcher<T3>, T4: Debug, I4: Matcher<T4>, T5: Debug, I5: Matcher<T5>, T6: Debug, I6: Matcher<T6>> Matcher<(T0, T1, T2, T3, T4, T5, T6)> for (I0, I1, I2, I3, I4, I5, I6)

fn matches(&self, actual: &(T0, T1, T2, T3, T4, T5, T6)) -> MatcherResult

fn explain_match(&self, actual: &(T0, T1, T2, T3, T4, T5, T6)) -> Description

impl<T0: Debug, I0: Matcher<T0>, T1: Debug, I1: Matcher<T1>, T2: Debug, I2: Matcher<T2>, T3: Debug, I3: Matcher<T3>, T4: Debug, I4: Matcher<T4>, T5: Debug, I5: Matcher<T5>> Matcher<(T0, T1, T2, T3, T4, T5)> for (I0, I1, I2, I3, I4, I5)

fn matches(&self, actual: &(T0, T1, T2, T3, T4, T5)) -> MatcherResult

fn explain_match(&self, actual: &(T0, T1, T2, T3, T4, T5)) -> Description

impl<T0: Debug, I0: Matcher<T0>, T1: Debug, I1: Matcher<T1>, T2: Debug, I2: Matcher<T2>, T3: Debug, I3: Matcher<T3>, T4: Debug, I4: Matcher<T4>> Matcher<(T0, T1, T2, T3, T4)> for (I0, I1, I2, I3, I4)

fn matches(&self, actual: &(T0, T1, T2, T3, T4)) -> MatcherResult

fn explain_match(&self, actual: &(T0, T1, T2, T3, T4)) -> Description

impl<T0: Debug, I0: Matcher<T0>, T1: Debug, I1: Matcher<T1>, T2: Debug, I2: Matcher<T2>, T3: Debug, I3: Matcher<T3>> Matcher<(T0, T1, T2, T3)> for (I0, I1, I2, I3)

fn matches(&self, actual: &(T0, T1, T2, T3)) -> MatcherResult

fn explain_match(&self, actual: &(T0, T1, T2, T3)) -> Description

impl<T0: Debug, I0: Matcher<T0>, T1: Debug, I1: Matcher<T1>, T2: Debug, I2: Matcher<T2>> Matcher<(T0, T1, T2)> for (I0, I1, I2)

fn matches(&self, actual: &(T0, T1, T2)) -> MatcherResult

fn explain_match(&self, actual: &(T0, T1, T2)) -> Description

impl<T0: Debug, I0: Matcher<T0>, T1: Debug, I1: Matcher<T1>> Matcher<(T0, T1)> for (I0, I1)

fn matches(&self, actual: &(T0, T1)) -> MatcherResult

fn explain_match(&self, actual: &(T0, T1)) -> Description

impl<T0: Debug, I0: Matcher<T0>> Matcher<(T0,)> for (I0,)

fn matches(&self, actual: &(T0,)) -> MatcherResult

fn explain_match(&self, actual: &(T0,)) -> Description

Implementors§

impl<ExpectedT, ActualT> Matcher<ActualT> for StrMatcher<ExpectedT>where ExpectedT: Deref<Target = str> + Debug, ActualT: AsRef<str> + Debug + ?Sized,

impl<T: Debug + Display + ?Sized, InnerMatcher: Matcher<String>> Matcher<T> for DisplayMatcher<InnerMatcher>

impl<T: Debug + Float> Matcher<T> for NearMatcher<T>

impl<T: Debug, P, D1: PredicateDescription, D2: PredicateDescription> Matcher<T> for PredicateMatcher<T, P, D1, D2>where for<'a> P: Fn(&'a T) -> bool,

Trait Matcher

impl<ExpectedT, ActualT> Matcher<ActualT> for StrMatcher<ExpectedT>
where ExpectedT: Deref<Target = str> + Debug, ActualT: AsRef<str> + Debug + ?Sized,

impl<T: Debug, P, D1: PredicateDescription, D2: PredicateDescription> Matcher<T> for PredicateMatcher<T, P, D1, D2>
where for<'a> P: Fn(&'a T) -> bool,