Merge pull request #260 from google:impl-matcher-for-tuples

PiperOrigin-RevId: 548131226

Author: copybara-github

googletest/crate_docs.md

@@ -118,7 +118,6 @@ The following matchers are provided in GoogleTest Rust:
 | [`starts_with`]      | A string starting with the given prefix.                                 |
 | [`subset_of`]        | A container all of whose elements are contained in the argument.         |
 | [`superset_of`]      | A container containing all elements of the argument.                     |
-| [`tuple!`]           | A tuple whose elements the arguments match.                              |
 | [`unordered_elements_are!`] | A container whose elements the arguments match, in any order.     |
 
 [`anything`]: matchers::anything

googletest/src/assertions.rs

@@ -58,6 +58,62 @@
 ///     `verify_that!(actual, elements_are![m1, m2, ...])`
 ///   * `verify_that!(actual, {m1, m2, ...})` is equivalent to
 ///     `verify_that!(actual, unordered_elements_are![m1, m2, ...])`
+///
+/// ## Matching against tuples
+///
+/// One can match against a tuple by constructing a tuple of matchers as
+/// follows:
+///
+/// ```
+/// # use googletest::prelude::*;
+/// # fn should_pass() -> Result<()> {
+/// verify_that!((123, 456), (eq(123), eq(456)))?; // Passes
+/// #     Ok(())
+/// # }
+/// # fn should_fail() -> Result<()> {
+/// verify_that!((123, 456), (eq(123), eq(0)))?; // Fails: second matcher does not match
+/// #     Ok(())
+/// # }
+/// # should_pass().unwrap();
+/// # should_fail().unwrap_err();
+/// ```
+///
+/// This also works with composed matchers:
+///
+/// ```
+/// # use googletest::prelude::*;
+/// # fn should_pass() -> Result<()> {
+/// verify_that!((123, 456), not((eq(456), eq(123))))?; // Passes
+/// #     Ok(())
+/// # }
+/// # should_pass().unwrap();
+/// ```
+///
+/// Matchers must correspond to the actual tuple in count and type. Otherwise
+/// the test will fail to compile.
+///
+/// ```compile_fail
+/// # use googletest::prelude::*;
+/// # fn should_not_compile() -> Result<()> {
+/// verify_that!((123, 456), (eq(123),))?; // Does not compile: wrong tuple size
+/// verify_that!((123, "A string"), (eq(123), eq(456)))?; // Does not compile: wrong type
+/// #     Ok(())
+/// # }
+/// ```
+///
+/// All fields must be covered by matchers. Use
+/// [`anything`][crate::matchers::anything] for fields which are not relevant
+/// for the test.
+///
+/// ```
+/// # use googletest::prelude::*;
+/// verify_that!((123, 456), (eq(123), anything()))
+/// #     .unwrap();
+/// ```
+///
+/// This supports tuples of up to 12 elements. Tuples longer than that do not
+/// automatically inherit the `Debug` trait from their members, so are generally
+/// not supported; see [Rust by Example](https://doc.rust-lang.org/rust-by-example/primitives/tuples.html#tuples).
 #[macro_export]
 macro_rules! verify_that {
     ($actual:expr, [$($expecteds:expr),+]) => {

googletest/src/lib.rs

@@ -51,7 +51,7 @@ pub mod prelude {
     // Matcher macros
     pub use super::{
         all, contains_each, elements_are, field, is_contained_in, matches_pattern, pat, pointwise,
-        property, tuple, unordered_elements_are,
+        property, unordered_elements_are,
     };
 }