Rewrite README and crate-level documentation to give a frontline summary of the *_that! assertion macros.

This should make the existence of and difference between these macros clearer up front to the reader. The `assert_that!` and `expect_that!` macros are listed first to nudge users to those rather than `verify_that!`.

This change also adds more examples of assertions in the beginning of the top-level documentation and changes the examples in crate-level documentation to use `expect_that!` rather than `verify_that!` when it does not otherwise matter.

Also fixes the Tokio dependency in the integration tests to 1.29.1, since the just released 1.32.0 appears to have a higher MSRV than this crate.

PiperOrigin-RevId: 558057297

Author: hovinenb

README.md

@@ -33,38 +33,57 @@ version 1.66 for the best developer experience.
 
 ## Assertions and matchers
 
-Most assertions are made through the macro [`verify_that!`] which evaluates to a
-[`Result<()>`]. It takes two arguments: an actual value to be tested and a
-[`Matcher`].
+The core of GoogleTest is its *matchers*. Matchers indicate what aspect of an
+actual value one is asserting: (in-)equality, containment, regular expression
+matching, and so on.
+
+To make an assertion using a matcher, GoogleTest offers three macros:
+
+ * [`assert_that!`] panics if the assertion fails, aborting the test.
+ * [`expect_that!`] logs an assertion failure, marking the test as having
+   failed, but allows the test to continue running (called a _non-fatal
+   assertion_). It requires the use of the [`googletest::test`] attribute macro
+   on the test itself.
+ * [`verify_that!`] has no side effects and evaluates to a [`Result`] whose
+   `Err` variant describes the assertion failure, if there is one. In
+   combination with the
+   [`?` operator](https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator),
+   this can be used to abort the test on assertion failure without panicking. It
+   is also the building block for the other two macros above.
+
+For example:
 
-Unlike the macros used in other test assertion libraries in Rust, `verify_that!`
-does not panic when the test assertion fails. Instead, it evaluates to `Result`,
-which the caller can choose to handle by:
-
- * Returning immediately from the function with the `?` operator (a *fatal*
-   assertion), or
- * Logging the failure, marking the test as failed, and allowing execution to
-   continue (see [Non-fatal assertions](#non-fatal-assertions) below).
+```rust
+use googletest::prelude::*;
 
-Fatal assertions are analogous to the `ASSERT_*` family of macros in GoogleTest.
+#[test]
+fn fails_and_panics() {
+    let value = 2;
+    assert_that!(value, eq(4));
+}
 
-For example, for fatal assertions:
+#[googletest::test]
+fn two_logged_failures() {
+    let value = 2;
+    expect_that!(value, eq(4)); // Test now failed, but continues executing.
+    expect_that!(value, eq(5)); // Second failure is also logged.
+}
 
-```rust
-use googletest::prelude::*;
+#[test]
+fn fails_immediately_without_panic() -> Result<()> {
+    let value = 2;
+    verify_that!(value, eq(4))?; // Test fails and aborts.
+    verify_that!(value, eq(2))?; // Never executes.
+    Ok(())
+}
 
 #[test]
-fn more_than_one_failure() -> Result<()> {
+fn simple_assertion() -> Result<()> {
     let value = 2;
-    verify_that!(value, eq(4))?;  // Fails and ends execution of the test.
-    verify_that!(value, eq(2)) // One can also just return the assertion result.
+    verify_that!(value, eq(4)) // One can also just return the last assertion.
 }
 ```
 
-> In case one wants behaviour closer to other Rust test libraries, the macro
-> [`assert_that!`] has the same parameters as [`verify_that!`] but panics on
-> failure.
-
 This library includes a rich set of matchers, covering:
 
  * Equality, numeric inequality, and approximate equality;
@@ -76,10 +95,10 @@ Matchers are composable:
 ```rust
 use googletest::prelude::*;
 
-#[test]
-fn contains_at_least_one_item_at_least_3() -> Result<()> {
+#[googletest::test]
+fn contains_at_least_one_item_at_least_3() {
     let value = vec![1, 2, 3];
-    verify_that!(value, contains(ge(3)))
+    expect_that!(value, contains(ge(3)));
 }
 ```
 
@@ -88,10 +107,10 @@ They can also be logically combined:
 ```rust
 use googletest::prelude::*;
 
-#[test]
-fn strictly_between_9_and_11() -> Result<()> {
+#[googletest::test]
+fn strictly_between_9_and_11() {
     let value = 10;
-    verify_that!(value, gt(9).and(not(ge(11))))
+    expect_that!(value, gt(9).and(not(ge(11))));
 }
 ```
 
@@ -110,17 +129,17 @@ struct AStruct {
 }
 
 #[test]
-fn struct_has_expected_values() -> Result<()> {
+fn struct_has_expected_values() {
     let value = AStruct {
         a_field: 10,
         another_field: 100,
         a_third_field: "A correct value",
     };
-    verify_that!(value, matches_pattern!(AStruct {
+    expect_that!(value, matches_pattern!(AStruct {
         a_field: eq(10),
         another_field: gt(50),
         a_third_field: contains_substring("correct"),
-    }))
+    }));
 }
 ```
 
@@ -162,12 +181,12 @@ pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<ActualT = T>
 }
 ```
 
-The new matcher can then be used in `verify_that!`:
+The new matcher can then be used in the assertion macros:
 
 ```rust
-#[test]
-fn should_be_equal_by_my_definition() -> Result<()> {
-    verify_that!(10, eq_my_way(10))
+#[googletest::test]
+fn should_be_equal_by_my_definition() {
+    expect_that!(10, eq_my_way(10));
 }
 ```
 

googletest/crate_docs.md

@@ -9,52 +9,81 @@ This library provides:
 
 ## Assertions and matchers
 
-Most assertions are made through the macro [`verify_that!`]. It takes two
-arguments: an actual value to be tested and a [`Matcher`].
+The core of GoogleTest is its *matchers*. Matchers indicate what aspect of an
+actual value one is asserting: (in-)equality, containment, regular expression
+matching, and so on.
+
+To make an assertion using a matcher, GoogleTest offers three macros:
+
+ * [`assert_that!`] panics if the assertion fails, aborting the test.
+ * [`expect_that!`] logs an assertion failure, marking the test as having
+   failed, but allows the test to continue running (called a _non-fatal
+   assertion_). It requires the use of the [`googletest::test`][crate::test]
+   attribute macro on the test itself.
+ * [`verify_that!`] has no side effects and evaluates to a [`Result`] whose
+   `Err` variant describes the assertion failure, if there is one. In
+   combination with the
+   [`?` operator](https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator),
+   this can be used to abort the test on assertion failure without panicking. It
+   is also the building block for the other two macros above.
+
+For example:
 
-Unlike the macros used in other test assertion libraries in Rust,
-`verify_that!` does not panic when the test assertion fails. Instead, it
-evaluates to [`googletest::Result<()>`][Result], which the caller can choose
-to handle by:
+```
+use googletest::prelude::*;
 
- * Returning immediately from the function with the `?` operator (a *fatal*
-   assertion), or
- * Logging the failure, marking the test as failed, and allowing execution to
-   continue (see [Non-fatal assertions](#non-fatal-assertions) below).
+# /* The attribute macro would prevent the function from being compiled in a doctest.
+#[test]
+# */
+fn fails_and_panics() {
+    let value = 2;
+    assert_that!(value, eq(4));
+}
 
-For example, for fatal assertions:
+# /* The attribute macro would prevent the function from being compiled in a doctest.
+#[googletest::test]
+# */
+fn two_logged_failures() {
+    let value = 2;
+    expect_that!(value, eq(4)); // Test now failed, but continues executing.
+    expect_that!(value, eq(5)); // Second failure is also logged.
+}
 
-```
-use googletest::prelude::*;
+# /* The attribute macro would prevent the function from being compiled in a doctest.
+#[test]
+# */
+fn fails_immediately_without_panic() -> Result<()> {
+    let value = 2;
+    verify_that!(value, eq(4))?; // Test fails and aborts.
+    verify_that!(value, eq(2))?; // Never executes.
+    Ok(())
+}
 
 # /* The attribute macro would prevent the function from being compiled in a doctest.
 #[test]
 # */
-fn more_than_one_failure() -> Result<()> {
+fn simple_assertion() -> Result<()> {
     let value = 2;
-    verify_that!(value, eq(4))?;  // Fails and ends execution of the test.
-    verify_that!(value, eq(2)) // One can also just return the assertion result.
+    verify_that!(value, eq(4)) // One can also just return the last assertion.
 }
-# more_than_one_failure().unwrap_err();
 ```
 
-> In case one wants behaviour closer to other Rust test libraries, the macro
-> [`assert_that!`] has the same parameters as [`verify_that!`] but panics on
-> failure.
-
 Matchers are composable:
 
 ```
 use googletest::prelude::*;
 
 # /* The attribute macro would prevent the function from being compiled in a doctest.
-#[test]
+#[googletest::test]
 # */
-fn contains_at_least_one_item_at_least_3() -> Result<()> {
+fn contains_at_least_one_item_at_least_3() {
+# googletest::internal::test_outcome::TestOutcome::init_current_test_outcome();
     let value = vec![1, 2, 3];
-    verify_that!(value, contains(ge(3)))
+    expect_that!(value, contains(ge(3)));
+# googletest::internal::test_outcome::TestOutcome::close_current_test_outcome::<&str>(Ok(()))
+#     .unwrap();
 }
-# contains_at_least_one_item_at_least_3().unwrap();
+# contains_at_least_one_item_at_least_3();
 ```
 
 They can also be logically combined:
@@ -63,13 +92,16 @@ They can also be logically combined:
 use googletest::prelude::*;
 
 # /* The attribute macro would prevent the function from being compiled in a doctest.
-#[test]
+#[googletest::test]
 # */
-fn strictly_between_9_and_11() -> Result<()> {
+fn strictly_between_9_and_11() {
+# googletest::internal::test_outcome::TestOutcome::init_current_test_outcome();
     let value = 10;
-    verify_that!(value, gt(9).and(not(ge(11))))
+    expect_that!(value, gt(9).and(not(ge(11))));
+# googletest::internal::test_outcome::TestOutcome::close_current_test_outcome::<&str>(Ok(()))
+#     .unwrap();
 }
-# strictly_between_9_and_11().unwrap();
+# strictly_between_9_and_11();
 ```
 
 ## Available matchers
@@ -236,7 +268,7 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
  }
  ```
 
- The new matcher can then be used in `verify_that!`:
+ The new matcher can then be used in the assertion macros:
 
 ```
 # use googletest::prelude::*;
@@ -274,12 +306,15 @@ impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
 #    MyEqMatcher { expected }
 # }
 # /* The attribute macro would prevent the function from being compiled in a doctest.
-#[test]
+#[googletest::test]
 # */
-fn should_be_equal_by_my_definition() -> Result<()> {
-    verify_that!(10, eq_my_way(10))
+fn should_be_equal_by_my_definition() {
+# googletest::internal::test_outcome::TestOutcome::init_current_test_outcome();
+    expect_that!(10, eq_my_way(10));
+# googletest::internal::test_outcome::TestOutcome::close_current_test_outcome::<&str>(Ok(()))
+#     .unwrap();
 }
-# should_be_equal_by_my_definition().unwrap();
+# should_be_equal_by_my_definition();
 ```
 
 ## Non-fatal assertions
@@ -290,8 +325,8 @@ having failed, but execution continues until the test completes or otherwise
 aborts.
 
 To make a non-fatal assertion, use the macro [`expect_that!`]. The test must
-also be marked with [`googletest::test`][test] instead of the Rust-standard
-`#[test]`.
+also be marked with [`googletest::test`][crate::test] instead of the
+Rust-standard `#[test]`.
 
 ```no_run
 use googletest::prelude::*;

integration_tests/Cargo.toml

@@ -32,7 +32,7 @@ googletest = { path = "../googletest", version = "0.9.0", features = ["anyhow"]
 anyhow = "1"
 indoc = "2"
 rstest = "0.13.0"
-tokio = { version = "1", features = ["time", "macros", "rt"] }
+tokio = { version = "=1.29.1", features = ["time", "macros", "rt"] }
 
 [[bin]]
 name = "integration_tests"