Struct AssertThat

pub struct AssertThat<'t, T, M: Mode> { /* private fields */ }

AssertThat is the core structure used for assertions. It allows developers to perform assertions on actual values in a fluent and expressive manner, supporting detailed messages as well as different modes of operation, such as panic or capture modes.

Type Parameters

• 't: The lifetime of the actual value being asserted.
• T: The type of the actual value being asserted.
• M: The assertion mode, implementing the Mode trait. Examples include Panic and Capture modes.

Fields

• parent: A reference to the parent assertion, if this is a derived assertion. Failures will propagate to the root assertion.
• actual: The value being asserted against.
• subject_name: An optional subject name for the assertion, allowing for more descriptive error messages.
• detail_messages: A collection of additional messages that provide context for the assertion.
• print_location: A boolean indicating whether the source code location of the assertion should be printed on failure.
• number_of_assertions: Tracks the number of assertions made.
• failures: A collection of failure messages for assertions in Capture mode.
• mode: The mode used for this assertion, determining behavior on failure.

Key Features

• Fluent API: Chainable and composable methods for making expressive assertions.
• Detail Messages: Add custom messages to provide context for failures.
• Modes:
  • Panic Mode: The default mode where failures result in immediate panics.
  • Capture Mode: Collect failures instead of panicking, useful for batch processing scenarios.
• Derived Assertions: Assertions derived from parent assertions, facilitating nested or mapped assertions.

Notes

• When using Capture mode, failures must be captured explicitly.
• This struct is designed to handle both simple and complex assertion chaining scenarios.

Implementations

impl<T, M: Mode> AssertThat<'_, T, M>

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

Add a message to be displayed on assertion failure.

pub fn with_conditional_detail_message<Message: Into<String>>( self, condition: impl Fn(&Self) -> bool, message_provider: impl Fn(&Self) -> Message, ) -> Self

Add a message to be displayed on assertion failure bound by the given condition.

pub fn add_detail_message(&self, message: impl Into<String>)

Add a message to be displayed on assertion failure.

Use this variant instead of the with_ variants when not in a call-chain context, and you don’t want to call an ownership-taking function.

impl<T, M: Mode> AssertThat<'_, T, M>

pub fn fail(&self, failure: impl Failure)

impl<T> AssertThat<'_, T, Capture>

pub fn capture_failures(self) -> Vec<String>

impl<'t, T, M: Mode> AssertThat<'t, T, M>

pub fn actual(&self) -> &T

pub fn map<U>( self, mapper: impl FnOnce(Actual<'_, T>) -> Actual<'_, U>, ) -> AssertThat<'t, U, M>

pub fn map_owned<U>( self, mapper: impl FnOnce(<T as ToOwned>::Owned) -> U, ) -> AssertThat<'t, U, M>

where T: ToOwned,

pub async fn map_async<U: 't, Fut>( self, mapper: impl FnOnce(Actual<'_, T>) -> Fut, ) -> AssertThat<'t, U, M>

where Fut: Future<Output = U>,

pub fn derive<'u, U: 'u>( &'t self, mapper: impl FnOnce(&'t T) -> U, ) -> AssertThat<'u, U, M>

where 't: 'u,

pub async fn derive_async<'u, U: 'u, Fut: Future<Output = U>>( &'t self, mapper: impl FnOnce(&'t T) -> Fut, ) -> AssertThat<'u, U, M>

where 't: 'u,

pub fn satisfies<U, F, A>(self, mapper: F, assertions: A) -> Self

where for<'a> F: FnOnce(&'a T) -> U, for<'a> A: FnOnce(AssertThat<'a, U, M>),

pub fn satisfies_ref<U, F, A>(self, mapper: F, assertions: A) -> Self

where for<'a> F: FnOnce(&'a T) -> &'a U, for<'a> A: FnOnce(AssertThat<'a, &'a U, M>),

pub fn with_subject_name(self, subject_name: impl Into<String>) -> Self

Gives the actual value contain in this assertion a descriptive name. This name will be part of panic messages when set.

pub fn with_capture(self) -> AssertThat<'t, T, Capture>

Control whether the location is shown on assertion failure.

It can be helpful to call .with_location(false) when you want to test the panic message for exact equality and do not want to be bothered by constantly differing line and column numbers fo the assert-location.

pub fn with_location(self, value: bool) -> Self

Control whether the location (file, line and column) is shown on assertion failure.

It can be helpful to call .with_location(false) when you want to test a panic message for exact equality and do not want to be bothered by constantly differing line and column numbers for the assert-location.

Trait Implementations

impl<T: Debug, const N: usize, M: Mode> ArrayAssertions<T> for AssertThat<'_, [T; N], M>

Assertions for generic arrays.

fn contains_exactly<E: AsRef<[T]>>(self, expected: E) -> Self

where T: PartialEq,

fn contains_exactly_in_any_order<E: AsRef<[T]>>(self, expected: E) -> Self

where T: PartialEq,

impl<M: Mode> BoolAssertions for AssertThat<'_, bool, M>

fn is_true(self) -> Self

fn is_false(self) -> Self

impl<'t, M: Mode> BoxAssertions<'t, M> for AssertThat<'t, Box<dyn Any>, M>

fn has_type<E: 'static>(self) -> AssertThat<'t, E, M>

If this fails in capturing mode, a panic is raised!

fn has_type_ref<E: 'static>(&'t self) -> AssertThat<'t, &'t E, M>

If this fails in capturing mode, a panic is raised!

impl<M: Mode> CharAssertions for AssertThat<'_, char, M>

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

fn is_lowercase(self) -> Self

fn is_uppercase(self) -> Self

fn is_ascii_lowercase(self) -> Self

fn is_ascii_uppercase(self) -> Self

impl<M: Mode> CommandAssertions for AssertThat<'_, Command, M>

fn has_arg(self, expected: impl AsRef<OsStr>) -> Self

impl<T, M: Mode> ConditionAssertions<T> for AssertThat<'_, T, M>

fn is<C: Condition<T>>(self, condition: C) -> Self

fn has<C: Condition<T>>(self, condition: C) -> Self

impl<T: Debug, M: Mode> DebugAssertions for AssertThat<'_, T, M>

fn has_debug_string(self, expected: impl AsRef<str>) -> Self

Test that actual has the expected Debug representation.

fn has_debug_value(self, expected: impl Debug) -> Self

Test that actual and expected have the same Debug representation.

impl<T: Display, M: Mode> DisplayAssertions for AssertThat<'_, T, M>

fn has_display_value(self, expected: impl Display) -> Self

impl<'t, R, F: FnOnce() -> R, M: Mode> FnOnceAssertions<'t, R, M> for AssertThat<'t, F, M>

fn panics(self) -> AssertThat<'t, PanicValue, M>

fn does_not_panic(self) -> AssertThat<'t, R, M>

where R: Debug,

impl<K, V, M: Mode> HashMapAssertions<K, V> for AssertThat<'_, HashMap<K, V>, M>

fn contains_key(self, expected: impl Borrow<K>) -> Self

where K: Eq + Hash + Debug, V: Debug,

fn does_not_contain_key(self, not_expected: impl Borrow<K>) -> Self

where K: Eq + Hash + Debug, V: Debug,

fn contains_value<E>(self, expected: E) -> Self

where K: Debug, V: AssertrPartialEq<E> + Debug, E: Debug,

fn contains_entry<E>(self, key: impl Borrow<K>, value: impl Borrow<E>) -> Self

where K: Eq + Hash + Debug, V: AssertrPartialEq<E> + Debug, E: Debug,

impl<T, I, M: Mode> IntoIteratorAssertions<T> for AssertThat<'_, I, M>

where T: Debug, for<'any> &'any I: IntoIterator<Item = &'any T>,

fn into_iter_contains<E>(self, expected: E) -> Self

where E: Debug, T: Debug + AssertrPartialEq<E>,

fn into_iter_contains_exactly<E>(self, expected: impl AsRef<[E]>) -> Self

where E: Debug, T: PartialEq<E> + AssertrPartialEq<E> + Debug,

fn into_iter_iterator_is_empty(self) -> Self

impl<I, T, M: Mode> IterableConditionAssertions<T, I> for AssertThat<'_, I, M>

where for<'any> &'any I: IntoIterator<Item = &'any T>,

fn are<C: Condition<T>>(self, condition: C) -> Self

fn have<C: Condition<T>>(self, condition: C) -> Self

impl<'t, T, I, M: Mode> IteratorAssertions<'t, T, M> for AssertThat<'t, I, M>

where T: Debug, I: Iterator<Item = T>,

fn contains<'u, E>(self, expected: E) -> AssertThat<'u, (), M>

where E: Debug, T: Debug + AssertrPartialEq<E>, 't: 'u,

This is a terminal assertion, as it must consume the underlying iterator.

fn contains_exactly<'u, E>( self, expected: impl AsRef<[E]>, ) -> AssertThat<'u, (), M>

where E: Debug, T: PartialEq<E> + AssertrPartialEq<E> + Debug, 't: 'u,

This is a terminal assertion, as it must consume the underlying iterator.

impl<T: HasLength + Debug, M: Mode> LengthAssertions for AssertThat<'_, T, M>

fn is_empty(self) -> Self

fn is_not_empty(self) -> Self

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

impl<T, M: Mode> MemAssertions for AssertThat<'_, Type<T>, M>

fn needs_drop(self) -> Self

impl<T: Debug, M: Mode> MutexAssertions for AssertThat<'_, Mutex<T>, M>

fn is_locked(self) -> Self

Asserts that this mutex is locked. Note that implementations may try to acquire the lock in order to check its state.

fn is_not_locked(self) -> Self

Asserts that this mutex is not locked. Note that implementations may try to acquire the lock in order to check its state.

fn is_free(self) -> Self

where Self: Sized,

Asserts that this mutex is not locked. Note that implementations may try to acquire the lock in order to check its state.

impl<T: Num + Debug, M: Mode> NumAssertions<T> for AssertThat<'_, T, M>

fn is_zero(self) -> Self

Fails if actual is not equal to the additive identity.

fn is_additive_identity(self) -> Self

fn is_one(self) -> Self

Fails if actual is not equal to the multiplicative identity.

fn is_multiplicative_identity(self) -> Self

fn is_negative(self) -> Self

where T: Signed,

fn is_positive(self) -> Self

where T: Signed,

fn is_close_to(self, expected: T, allowed_deviation: T) -> Self

where T: PartialOrd + Clone,

Fails if actual is not in the range [expected - allowed_deviation, expected + allowed_deviation].

fn is_nan(self) -> Self

where T: Float,

fn is_finite(self) -> Self

where T: Float,

fn is_infinite(self) -> Self

where T: Float,

impl<'t, T, M: Mode> OptionAssertions<'t, T, M> for AssertThat<'t, Option<T>, M>

fn is_some(self) -> AssertThat<'t, T, M>

where T: Debug,

Test if this option is of the Some variant. This is a terminal operation on the contained Option, as there is nothing meaningful to do with the option if its variant was ensured. This allows you to chain additional expectations on the contained success value.

fn is_none(self) -> AssertThat<'t, (), M>

where T: Debug,

Test if this option is of the None variant. This is a terminal operation on the contained Option, as there is nothing meaningful to do with the option after its variant was ensured.

impl<'t, M: Mode> PanicValueAssertions<'t, M> for AssertThat<'t, PanicValue, M>

fn has_type<E: 'static>(self) -> AssertThat<'t, E, M>

If this fails in capturing mode, a panic is raised!

fn has_type_ref<E: 'static>(&'t self) -> AssertThat<'t, &'t E, M>

NOTE: If this fails in capturing mode, a panic is raised!

impl<T, M: Mode> PartialEqAssertions<T> for AssertThat<'_, T, M>

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

where T: AssertrPartialEq<E> + Debug, E: Debug,

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

where T: AssertrPartialEq<E> + Debug, E: Debug,

impl<T: Debug, M: Mode> PartialOrdAssertions<T> for AssertThat<'_, T, M>

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

where E: Debug, T: PartialOrd<E>,

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

where E: Debug, T: PartialOrd<E>,

fn is_less_or_equal_to<E>(self, expected: impl Borrow<E>) -> Self

where E: Debug, T: PartialOrd<E>,

fn is_greater_or_equal_to<E>(self, expected: impl Borrow<E>) -> Self

where E: Debug, T: PartialOrd<E>,

impl<M: Mode> PathAssertions for AssertThat<'_, &Path, M>

fn exists(self) -> Self

fn does_not_exist(self) -> Self

fn is_a_file(self) -> Self

fn is_a_directory(self) -> Self

fn is_a_symlink(self) -> Self

fn has_a_root(self) -> Self

fn is_relative(self) -> Self

fn has_file_name(self, expected: impl AsRef<OsStr>) -> Self

fn has_file_stem(self, expected: impl AsRef<OsStr>) -> Self

fn has_extension(self, expected: impl AsRef<OsStr>) -> Self

impl<M: Mode> PathAssertions for AssertThat<'_, PathBuf, M>

fn exists(self) -> Self

fn does_not_exist(self) -> Self

fn is_a_file(self) -> Self

fn is_a_directory(self) -> Self

fn is_a_symlink(self) -> Self

fn has_a_root(self) -> Self

fn is_relative(self) -> Self

fn has_file_name(self, expected: impl AsRef<OsStr>) -> Self

fn has_file_stem(self, expected: impl AsRef<OsStr>) -> Self

fn has_extension(self, expected: impl AsRef<OsStr>) -> Self

impl<'t, T: Debug, M: Mode> PollAssertions<'t, T, M> for AssertThat<'t, Poll<T>, M>

fn is_pending(self) -> Self

fn is_ready(self) -> AssertThat<'t, T, M>

impl<B, M: Mode> RangeAssertions<B> for AssertThat<'_, B, M>

fn is_in_range(self, expected: impl RangeBounds<B>) -> Self

where B: PartialOrd + Debug,

fn is_not_in_range(self, expected: impl RangeBounds<B>) -> Self

where B: PartialOrd + Debug,

fn is_outside_of_range(self, expected: impl RangeBounds<B>) -> Self

where Self: Sized, B: PartialOrd + Debug,

impl<B, R: RangeBounds<B>, M: Mode> RangeBoundAssertions<B, R> for AssertThat<'_, R, M>

fn contains_element(&self, expected: B)

where R: Debug, B: PartialOrd + Debug,

fn does_not_contain_element(&self, expected: B)

where R: Debug, B: PartialOrd + Debug,

impl<T: Debug, M: Mode> RefCellAssertions for AssertThat<'_, RefCell<T>, M>

fn is_borrowed(self) -> Self

Check that the RefCell is immutably or mutably borrowed.

fn is_mutably_borrowed(self) -> Self

Check that the RefCell is mutably borrowed.

fn is_not_mutably_borrowed(self) -> Self

Check that the RefCell is not mutably borrowed, wither by being not borrowed at all, or only borrowed immutably.

impl<'t, M: Mode, T, E> ResultAssertions<'t, M, T, E> for AssertThat<'t, Result<T, E>, M>

fn is_ok(self) -> AssertThat<'t, T, M>

where T: Debug, E: Debug,

This is a terminal operation on the contained Result, as there is little meaningful to do with the result if its variant was ensured. This allows you to chain additional expectations on the contained success value.

fn is_err(self) -> AssertThat<'t, E, M>

where T: Debug, E: Debug,

This is a terminal operation on the contained Result, as there is little meaningful to do with the result if its variant was ensured. This allows you to chain additional expectations on the contained error value.

fn is_ok_satisfying<A>(self, assertions: A) -> Self

where T: Debug, E: Debug, A: for<'a> FnOnce(AssertThat<'a, &'a T, M>),

fn is_err_satisfying<A>(self, assertions: A) -> Self

where T: Debug, E: Debug, A: for<'a> FnOnce(AssertThat<'a, &'a E, M>),

impl<'t, T, M: Mode> SliceAssertions<'t, T> for AssertThat<'t, &[T], M>

fn contains<E>(self, expected: E) -> Self

where E: Debug, T: Debug + AssertrPartialEq<E>,

fn contains_exactly<E, EE>(self, expected: EE) -> Self

where E: Debug + 't, EE: AsRef<[E]>, T: AssertrPartialEq<E> + Debug,

Test that the subject contains exactly the expected elements. Order is important. Lengths must be identical.

fn contains_exactly_in_any_order<E: AsRef<[T]>>(self, expected: E) -> Self

where T: PartialEq + Debug,

fn contains_exactly_matching_in_any_order<P>( self, expected: impl AsRef<[P]>, ) -> Self

where T: Debug, P: Fn(&T) -> bool,

[P] - Predicate

impl<M: Mode> StrSliceAssertions for AssertThat<'_, &str, M>

fn is_blank(self) -> Self

Tests whether this string is empty or only containing whitespace characters. ‘Whitespace’ is defined according to the terms of the Unicode Derived Core Property White_Space.

fn is_blank_ascii(self) -> Self

Tests whether this string is empty or only containing ascii-whitespace characters.

fn contains(self, expected: impl AsRef<str>) -> Self

fn starts_with(self, expected: impl AsRef<str>) -> Self

fn ends_with(self, expected: impl AsRef<str>) -> Self

impl<M: Mode> StringAssertions for AssertThat<'_, String, M>

fn contains(self, expected: impl AsRef<str>) -> Self

fn starts_with(self, expected: impl AsRef<str>) -> Self

fn ends_with(self, expected: impl AsRef<str>) -> Self

impl<'t, T: Debug, M: Mode> VecAssertions<'t, T> for AssertThat<'t, Vec<T>, M>

fn contains<E>(self, expected: E) -> Self

where E: Debug, T: AssertrPartialEq<E> + Debug,

fn contains_exactly<E>(self, expected: impl AsRef<[E]>) -> Self

where E: Debug + 't, T: AssertrPartialEq<E> + Debug,

fn contains_exactly_matching_in_any_order<P>( self, expected: impl AsRef<[P]>, ) -> Self

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

[P] - Predicate

impl<T, M: Mode> RefUnwindSafe for AssertThat<'_, T, M>

impl<T, M: Mode> UnwindSafe for AssertThat<'_, T, M>