Introduce a function verify_current_test_outcome.

This allows a test to check whether the current test has passed or failed based on non-fatal assertions such as `expect_that!`. Its naming follows the pattern of `verify_that!` since it uses the same idiom of returning a `googletest::Result`.

Author: hovinen

googletest/src/internal/test_outcome.rs

@@ -84,6 +84,20 @@ impl TestOutcome {
         })
     }
 
+    /// Returns a `Result` corresponding to the outcome of the currently running
+    /// test.
+    pub(crate) fn get_current_test_outcome() -> Result<(), TestAssertionFailure> {
+        TestOutcome::with_current_test_outcome(|mut outcome| {
+            let outcome = outcome
+                .as_mut()
+                .expect("No test context found. This indicates a bug in GoogleTest.");
+            match outcome {
+                TestOutcome::Success => Ok(()),
+                TestOutcome::Failure => Err(TestAssertionFailure::create("Test failed".into())),
+            }
+        })
+    }
+
     /// Records that the currently running test has failed.
     fn fail_current_test() {
         TestOutcome::with_current_test_outcome(|mut outcome| {

googletest/src/lib.rs

@@ -43,6 +43,7 @@ pub mod matchers;
 pub mod prelude {
     pub use super::matcher::Matcher;
     pub use super::matchers::*;
+    pub use super::verify_current_test_outcome;
     pub use super::GoogleTestSupport;
     pub use super::IntoTestResult;
     pub use super::Result;
@@ -83,6 +84,37 @@ use internal::test_outcome::{TestAssertionFailure, TestOutcome};
 /// failed but allow it to continue running, are not encoded in this type.
 pub type Result<T> = std::result::Result<T, TestAssertionFailure>;
 
+/// Returns a [`Result`] corresponding to the outcome of the currently running
+/// test.
+///
+/// This returns `Result::Err` precisely if the current test has recorded at
+/// least one test assertion failure via [`expect_that!`][crate::expect_that],
+/// [`expect_pred!`][crate::expect_pred], or
+/// [`GoogleTestSupport::and_log_failure`]. It can be used in concert with the
+/// `?` operator to continue execution of the test conditionally on there not
+/// having been any failure yet.
+///
+/// This requires the use of the [`#[googletest::test]`][crate::test] attribute
+/// macro.
+///
+/// ```
+/// # use googletest::prelude::*;
+/// # /* Make sure this also compiles as a doctest.
+/// #[googletest::test]
+/// # */
+/// fn should_fail_and_not_execute_last_assertion() -> Result<()> {
+/// #   googletest::internal::test_outcome::TestOutcome::init_current_test_outcome();
+///     let value = 1;
+///     expect_that!(value, eq(2));     // Fails but does not abort the test.
+///     verify_current_test_outcome()?; // Aborts the test due to the previous failure.
+///     verify_that!(value, eq(1))      // Does not execute.
+/// }
+/// # verify_that!(should_fail_and_not_execute_last_assertion(), err(displays_as(contains_substring("Test failed")))).unwrap();
+/// ```
+pub fn verify_current_test_outcome() -> Result<()> {
+    TestOutcome::get_current_test_outcome()
+}
+
 /// Adds to `Result` support for GoogleTest Rust functionality.
 pub trait GoogleTestSupport {
     /// If `self` is a `Result::Err`, writes to `stdout` a failure report