pub trait Matcher<ActualT: Debug + Copy>: MatcherBase {
// Required methods
fn matches(&self, actual: ActualT) -> MatcherResult;
fn describe(&self, matcher_result: MatcherResult) -> Description;
// Provided method
fn explain_match(&self, actual: ActualT) -> Description { ... }
}Expand description
An interface for checking an arbitrary condition on a datum.
This trait is automatically implemented for a reference of any type
implementing Matcher. This simplifies reusing a matcher in different
assertions.
It is also implemented for tuple of Matcher. If MatcherT: Matcher<T> and
MatcherU: Matcher<U>, then (MatcherT, MatcherU): Matcher<(T, U)>, and so
on, up to 12 elements. Tuples longer than that do not automatically inherit
the Debug trait from their members, so are generally not well-supported;
see Rust by Example.
Required Methods§
Sourcefn matches(&self, actual: ActualT) -> MatcherResult
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.
Sourcefn describe(&self, matcher_result: MatcherResult) -> Description
fn describe(&self, matcher_result: MatcherResult) -> Description
Returns a description of self or a negative description if
matcher_result is DoesNotMatch.
The function should print a verb phrase that describes the property a value matching, respectively not matching, this matcher should have. The subject of the verb phrase is the value being matched.
The output appears next to Expected in an assertion failure message.
For example:
Value of: ...
Expected: is equal to 7
^^^^^^^^^^^^^
Actual: ...When the matcher contains one or more inner matchers, the implementation
should invoke Self::describe on the inner matchers to complete the
description. It should place the inner description at a point where a
verb phrase would fit. For example, the matcher
some implements describe as follows:
ⓘ
fn describe(&self, matcher_result: MatcherResult) -> Description {
match matcher_result {
MatcherResult::Matches => {
Description::new()
.text("has a value which")
.nested(self.inner.describe(MatcherResult::Matches))
// Inner matcher: ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
}
MatcherResult::DoesNotMatch => {...} // Similar to the above
}
}The output expectation differs from that of
explain_match in that it is a verb phrase
(beginning with a verb like “is”) rather than a relative clause
(beginning with “which” or “whose”). This difference is because the
output of explain_match is always used adjectivally to describe the
actual value, while describe is used in contexts where a relative
clause would not make sense.
Provided Methods§
Sourcefn explain_match(&self, actual: ActualT) -> Description
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: &ActualT) -> Description {
self.expected.explain_match(*actual)
}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: ActualT) -> Description {
Description::new()
.text("which points to a value")
.nested(self.expected.explain_match(*actual))
}