test_that/

assertions.rs

// Copyright 2022 Google LLC
// Copyright 2026 Bradford Hovinen <bradford@hovinen.me>
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// There are no visible documentation elements in this module; the declarative
// macros are documented at the top level.
#![doc(hidden)]

/// Checks whether the `Matcher` given by the second argument matches the first
/// argument.
///
/// Evaluates to `Result::Ok(())` if the matcher matches and
/// `Result::Err(TestAssertionFailure)` if it does not. The caller must then
/// decide how to handle the `Err` variant. It has a few options:
///
///  * Abort the current function with the `?` operator. This requires that the
///    function return a suitable `Result`.
///  * Log the test failure and continue by calling the method
///    `and_log_failure`.
///
/// Of course, one can also use all other standard methods on `Result`.
///
/// **Invoking this macro by itself does not cause a test failure to be recorded
/// or output.** The resulting `Result` must be handled as described above to
/// cause the test to be recorded as a failure.
///
/// Example:
/// ```
/// # use test_that::prelude::*;
/// # fn should_pass() -> TestResult<()> {
/// verify_that!(42, eq(42))?; // This will pass.
/// # Ok(())
/// # }
/// # should_pass().unwrap();
/// # fn should_fail() -> TestResult<()> {
/// # test_that::internal::test_outcome::TestOutcome::init_current_test_outcome();
/// verify_that!(42, eq(123)).and_log_failure();
///             // This will log a test failure and allow execution to continue.
/// let _ = verify_that!(42, eq(123)); // This will do nothing.
/// verify_that!(42, eq(123))?; // This will fail, returning immediately.
/// verify_that!(42, eq(0))?; // This will not run.
/// # test_that::internal::test_outcome::TestOutcome::close_current_test_outcome::<&str>(Ok(()))
/// #     .unwrap_err();
/// # Ok(())
/// # }
/// # verify_that!(should_fail(), err(displays_as(contains_substring("Expected: is equal to 123"))))
/// #     .unwrap();
/// ```
///
/// This macro has special support for matching against container. Namely:
///   * `verify_that!(actual, [m1, m2, ...])` is equivalent to
///     `verify_that!(actual, contains_exactly![m1, m2, ...].in_order())`
///   * `verify_that!(actual, {m1, m2, ...})` is equivalent to
///     `verify_that!(actual, contains_exactly![m1, m2, ...])`
#[macro_export]
macro_rules! verify_that {
    ($actual:expr, [$($expecteds:expr),+ $(,)?]) => {
        $crate::assertions::internal::check_matcher(
            &$actual,
            $crate::matchers::containers::contains_exactly![$($expecteds),+].in_order(),
            stringify!($actual),
            $crate::internal::source_location::SourceLocation::new(file!(), line!(), column!()),
        )
    };
    ($actual:expr, {$($expecteds:expr),+ $(,)?}) => {
        $crate::assertions::internal::check_matcher(
            &$actual,
            $crate::matchers::containers::contains_exactly![$($expecteds),+],
            stringify!($actual),
            $crate::internal::source_location::SourceLocation::new(file!(), line!(), column!()),
        )
    };
    ($actual:expr, $expected:expr $(,)?) => {
        $crate::assertions::internal::check_matcher(
            &$actual,
            $expected,
            stringify!($actual),
            $crate::internal::source_location::SourceLocation::new(file!(), line!(), column!()),
        )
    };
}

/// Asserts that the given predicate applied to the given arguments returns
/// true.
///
/// Similarly to [`verify_that`], this evaluates to a `Result` whose `Ok`
/// variant indicates that the given predicate returned true and whose `Err`
/// variant indicates that it returned false.
///
/// The failure message contains detailed information about the arguments. For
/// example:
///
/// ```
/// # use test_that::prelude::*;
/// fn equals_modulo(a: i32, b: i32, n: i32) -> bool { a % n == b % n }
///
/// # /* The attribute macro would prevent the function from being compiled in a doctest.
/// #[test]
/// # */
/// fn test() -> TestResult<()> {
///     let a = 1;
///     let b = 7;
///     let n = 5;
///     verify_pred!(equals_modulo(a, b, n))?;
///     Ok(())
/// }
/// # verify_that!(
/// #     test(),
/// #     err(displays_as(contains_substring("equals_modulo(a, b, n) was false with")))
/// # ).unwrap();
/// ```
///
/// This results in the following message:
///
/// ```text
/// equals_modulo(a, b, n) was false with
///   a = 1,
///   b = 7,
///   n = 5
/// ```
///
/// The function passed to this macro must return `bool`. Each of the arguments
/// must evaluate to a type implementing [`std::fmt::Debug`]. The debug output
/// is used to construct the failure message.
///
/// The predicate can also be a method on a struct, e.g.:
///
/// ```ignore
/// struct AStruct {};
///
/// impl AStruct {
///   fn equals_modulo(...) {...}
/// }
///
/// verify_pred!((AStruct {}).equals_modulo(a, b, n))?;
/// ```
///
/// **Warning:** This macro assumes that the arguments passed to the predicate
/// are either *variables* or *calls to pure functions*. If two subsequent
/// invocations to any of the expresssions passed as arguments result in
/// different values, then the output message of a test failure will deviate
/// from the values actually passed to the predicate. For this reason, *always
/// assign the outputs of non-pure functions to variables before using them in
/// this macro. For example:
///
/// ```ignore
/// let output = generate_random_number();  // Assigned outside of verify_pred.
/// verify_pred!(is_sufficiently_random(output))?;
/// ```
#[macro_export]
macro_rules! verify_pred {
    ([$($predicate:tt)*]($($arg:tt),* $(,)?)) => {
        if !$($predicate)*($($arg),*) {
            $crate::assertions::internal::report_failed_predicate(
                concat!(stringify!($($predicate)*), stringify!(($($arg),*))),
                vec![$((format!(concat!(stringify!($arg), " = {:?}"), $arg))),*],
                $crate::internal::source_location::SourceLocation::new(
                    file!(),
                    line!(),
                    column!(),
                ),
            )
        } else {
            Ok(())
        }
    };

    ([$($predicate:tt)*] $first:tt $($rest:tt)*) => {
        $crate::verify_pred!([$($predicate)* $first] $($rest)*)
    };

    ($first:tt $($rest:tt)*) => {
        $crate::verify_pred!([$first] $($rest)*)
    };
}

/// Evaluates to a `Result` which contains an `Err` variant with the given test
/// failure message.
///
/// This can be used to force the test to fail if its execution reaches a
/// particular point. For example:
///
/// ```ignore
/// match some_value {
///     ExpectedVariant => {...}
///     UnwantedVaraint => {
///         fail!("This thing which should not happen happened anyway")?;
///     }
/// }
/// ```
///
/// One may include formatted arguments in the failure message:
///
/// ```ignore
/// match some_value {
///     ExpectedVariant => {...}
///     UnwantedVaraint => {
///         fail!("This thing which should not happen happened anyway: {}", some_value)?;
///     }
/// }
/// ```
///
/// One may also omit the message, in which case the test failure message will
/// be generic:
///
/// ```ignore
/// match some_value {
///     ExpectedVariant => {...}
///     UnwantedVaraint => {
///         fail!()?;
///     }
/// }
/// ```
///
/// Unlike `panic!` but analogously to [`verify_that`] and [`verify_pred`], this
/// macro has no effect on the flow of control but instead returns a `Result`
/// which must be handled by the invoking function. This can be done with the
/// question mark operator (as above) or the method
/// [`and_log_failure`](crate::TestResultExt::and_log_failure).
#[macro_export]
macro_rules! fail {
    ($($message:expr),+) => {{
        // We wrap this in a function so that we can annotate it with the must_use attribute.
        // must_use on expressions is still experimental.
        #[must_use = "The assertion result must be evaluated to affect the test result."]
        fn create_fail_result(message: String) -> $crate::TestResult<()> {
            Err($crate::internal::test_outcome::TestAssertionFailure::create(format!(
                "{}\n{}",
                message,
                $crate::internal::source_location::SourceLocation::new(
                    file!(),
                    line!(),
                    column!(),
                ),
            )))
        }
        create_fail_result(format!($($message),*))
    }};

    () => { fail!("Test failed") };
}

/// Matches the given value against the given matcher, panicking if it does not
/// match.
///
/// ```should_panic
/// # use test_that::prelude::*;
/// # fn should_fail() {
/// let value = 2;
/// assert_that!(value, eq(3));  // Fails and panics.
/// # }
/// # should_fail();
/// ```
///
/// This is analogous to assertions in most Rust test libraries, where a failed
/// assertion causes a panic.
///
/// One may optionally add arguments which will be formatted and appended to a
/// failure message. For example:
///
/// ```should_panic
/// # use test_that::prelude::*;
/// # fn should_fail() {
/// let value = 2;
/// let extra_information = "Some additional information";
/// assert_that!(value, eq(3), "Test failed. Extra information: {extra_information}.");
/// # }
/// # should_fail();
/// ```
///
/// This is output as follows:
///
/// ```text
/// Value of: value
/// Expected: is equal to 3
/// Actual: 2,
///   which isn't equal to 3
///   at ...
/// Test failed. Extra information: Some additional information.
/// ```
///
/// **Note for users of [GoogleTest for C++](http://google.github.io/googletest/):**
/// This differs from the `ASSERT_THAT` macro in that it panics rather
/// than triggering an early return from the invoking function. To get behaviour
/// equivalent to `ASSERT_THAT`, use [`verify_that!`] with the `?` operator.
#[macro_export]
macro_rules! assert_that {
    ($actual:expr, $expected:expr $(,)?) => {
        match $crate::verify_that!($actual, $expected) {
            Ok(_) => {}
            Err(e) => {
                // The extra newline before the assertion failure message makes the failure a
                // bit easier to read when there's some generic boilerplate from the panic.
                panic!("\n{}", e);
            }
        }
    };

    ($actual:expr, $expected:expr, $($format_args:expr),* $(,)?) => {
        match $crate::verify_that!($actual, $expected)
            .with_failure_message(|| format!($($format_args),*))
        {
            Ok(_) => {}
            Err(e) => {
                // The extra newline before the assertion failure message makes the failure a
                // bit easier to read when there's some generic boilerplate from the panic.
                panic!("\n{}", e);
            }
        }
    };
}

/// Asserts that the given predicate applied to the given arguments returns
/// true, panicking if it does not.
///
/// **Note for users of [GoogleTest for C++](http://google.github.io/googletest/):**
/// This differs from the `ASSERT_PRED*` family of macros in that it panics
/// rather than triggering an early return from the invoking function. To get
/// behaviour equivalent to `ASSERT_PRED*`, use [`verify_pred!`] with the `?`
/// operator.
#[macro_export]
macro_rules! assert_pred {
    ($($content:tt)*) => {
        match $crate::verify_pred!($($content)*) {
            Ok(_) => {}
            Err(e) => {
                // The extra newline before the assertion failure message makes the failure a
                // bit easier to read when there's some generic boilerplate from the panic.
                panic!("\n{}", e);
            }
        }
    };
}

/// Matches the given value against the given matcher, marking the test as
/// failed but continuing execution if it does not match.
///
/// This is a *non-fatal* assertion: the test continues
/// execution in the event of assertion failure.
///
/// This can only be invoked inside tests with the
/// [`test_that::test`][crate::test] attribute. The assertion must
/// occur in the same thread as that running the test itself.
///
/// Invoking this macro is equivalent to using
/// [`and_log_failure`](crate::TestResultExt::and_log_failure) as follows:
///
/// ```ignore
/// verify_that!(actual, expected).and_log_failure()
/// ```
///
/// One may optionally add arguments which will be formatted and appended to a
/// failure message. For example:
///
/// ```
/// # use test_that::prelude::*;
/// # fn should_fail() -> std::result::Result<(), test_that::internal::test_outcome::TestFailure> {
/// # test_that::internal::test_outcome::TestOutcome::init_current_test_outcome();
/// let value = 2;
/// let extra_information = "Some additional information";
/// expect_that!(value, eq(3), "Test failed. Extra information: {extra_information}.");
/// # test_that::internal::test_outcome::TestOutcome::close_current_test_outcome::<&str>(Ok(()))
/// # }
/// # should_fail().unwrap_err();
/// ```
///
/// This is output as follows:
///
/// ```text
/// Value of: value
/// Expected: is equal to 3
/// Actual: 2,
///   which isn't equal to 3
///   at ...
/// Test failed. Extra information: Some additional information.
/// ```
#[macro_export]
macro_rules! expect_that {
    ($actual:expr, $expected:expr $(,)?) => {{
        use $crate::TestResultExt;
        $crate::verify_that!($actual, $expected).and_log_failure();
    }};

    ($actual:expr, $expected:expr, $($format_args:expr),* $(,)?) => {
        $crate::verify_that!($actual, $expected)
            .with_failure_message(|| format!($($format_args),*))
            .and_log_failure()
    };
}

/// Asserts that the given predicate applied to the given arguments returns
/// true, failing the test but continuing execution if not.
///
/// This is a *non-fatal* predicate assertion: the test
/// continues execution in the event of assertion failure.
///
/// This can only be invoked inside tests with the
/// [`test_that::test`][crate::test] attribute. The assertion must
/// occur in the same thread as that running the test itself.
///
/// Invoking this macro is equivalent to using
/// [`and_log_failure`](crate::TestResultExt::and_log_failure) as follows:
///
/// ```ignore
/// verify_pred!(predicate(...)).and_log_failure()
/// ```
#[macro_export]
macro_rules! expect_pred {
    ($($content:tt)*) => {{
        use $crate::TestResultExt;
        $crate::verify_pred!($($content)*).and_log_failure();
    }};
}

/// Functions for use only by the procedural macros in this module.
///
/// **For internal use only. API stablility is not guaranteed!**
#[doc(hidden)]
pub mod internal {
    use crate::{
        internal::{source_location::SourceLocation, test_outcome::TestAssertionFailure},
        matcher::{Matcher, MatcherResult, create_assertion_failure},
    };
    use std::fmt::Debug;

    /// Checks whether the matcher `expected` matches the value `actual`, adding
    /// a test failure report if it does not match.
    ///
    /// Returns `Ok(())` if the value matches and `Err(())` if it does not
    /// match.
    ///
    /// **For internal use only. API stablility is not guaranteed!**
    #[must_use = "The assertion result must be evaluated to affect the test result."]
    pub fn check_matcher<T: Debug + ?Sized>(
        actual: &T,
        expected: impl Matcher<T>,
        actual_expr: &'static str,
        source_location: SourceLocation,
    ) -> Result<(), TestAssertionFailure> {
        match expected.matches(actual) {
            MatcherResult::Match => Ok(()),
            MatcherResult::NoMatch => {
                Err(create_assertion_failure(&expected, actual, actual_expr, source_location))
            }
        }
    }

    /// Constructs a `Result::Err(TestAssertionFailure)` for a predicate failure
    /// as produced by the macro [`crate::verify_pred`].
    ///
    /// This intended only for use by the macro [`crate::verify_pred`].
    ///
    /// **For internal use only. API stablility is not guaranteed!**
    #[must_use = "The assertion result must be evaluated to affect the test result."]
    pub fn report_failed_predicate(
        actual_expr: &'static str,
        formatted_arguments: Vec<String>,
        source_location: SourceLocation,
    ) -> Result<(), TestAssertionFailure> {
        Err(TestAssertionFailure::create(format!(
            "{} was false with\n  {}\n{}",
            actual_expr,
            formatted_arguments.join(",\n  "),
            source_location,
        )))
    }
}