Replace the type parameter on Matcher with an associated type.

This has the immediate effect that the extension traits `AndMatcherExt` and `OrMatcherExt` now have no trouble working with strings. Namely, this change forces the matcher struct itself always to reference the actual type against which it matcher, either via parameterisation or by only matching against a concrete type. Because of this, the matcher declaration always carries the necessary type information so that the compiler can perform type inference. This change introduces unit tests which demonstrate this.

This same property has the drawback that matchers must frequently carry a `PhantomData` of the type against which they match. This is annoying, but not fatal.

This is of course an API-incompatible change. Downstream targets which build their own matchers will have to change the type parameter to be an associated type, and may need to make additional adjustments as outlined above. This commit shows several such examples.

This also has the effect that it is no longer possible to define a single matcher class and implement `Matcher` against several actual types with it. Only one matcher in GoogleTest -- `ContainerEqMatcher` -- did this, and a previous change modified it to have only one `Matcher` implementation with no loss of functionality.

Existing tests did not have to be changed, except for tests of some internals of matchers due to direct reference to the `Matcher` type. This suggests that the change will not break downstream _uses_ of matchers.

In the future, this should also make it possible to associate a lifetime with the actual value in such a way as to allow the property matcher to work with extractors which return data referencing the containing struct. Most likely that would require modifying the associated type to have a lifetime parameter. Currently that unfortunately does not work for us since some matchers use trait objects and generic associated types are not yet object-safe (see https://blog.rust-lang.org/2022/10/28/gats-stabilization.html#traits-with-gats-are-not-object-safe). This may change in the future.

PiperOrigin-RevId: 527884316

Author: hovinenb

README.md

@@ -138,8 +138,10 @@ struct MyEqMatcher<T> {
     expected: T,
 }
 
-impl<T: PartialEq + Debug> Matcher<T> for MyEqMatcher<T> {
-    fn matches(&self, actual: &A) -> MatcherResult {
+impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
+    type ActualT = T;
+
+    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
          (self.expected == *actual).into()
     }
 
@@ -159,7 +161,7 @@ impl<T: PartialEq + Debug> Matcher<T> for MyEqMatcher<T> {
 It is recommended to expose a function which constructs the matcher:
 
 ```rust
-pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<T> {
+pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<ActualT = T> {
     MyEqMatcher { expected }
 }
 ```

googletest/src/assertions.rs

@@ -332,7 +332,7 @@ pub mod internal {
     #[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>,
+        expected: impl Matcher<ActualT = T>,
         actual_expr: &'static str,
         source_location: SourceLocation,
     ) -> Result<(), TestAssertionFailure> {

googletest/src/lib.rs

@@ -190,8 +190,10 @@
 //!    expected: T,
 //! }
 //!
-//! impl<T: PartialEq + Debug> Matcher<T> for MyEqMatcher<T> {
-//!    fn matches(&self, actual: &T) -> MatcherResult {
+//! impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
+//!    type ActualT = T;
+//!
+//!    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
 //!        if self.expected == *actual {
 //!            MatcherResult::Matches
 //!        } else {
@@ -222,8 +224,10 @@
 //! #    expected: T,
 //! # }
 //! #
-//! # impl<T: PartialEq + Debug> Matcher<T> for MyEqMatcher<T> {
-//! #    fn matches(&self, actual: &T) -> MatcherResult {
+//! # impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
+//! #    type ActualT = T;
+//! #
+//! #    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
 //! #        if self.expected == *actual {
 //! #            MatcherResult::Matches
 //! #        } else {
@@ -243,7 +247,7 @@
 //! #    }
 //! # }
 //! #
-//! pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<T> {
+//! pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<ActualT = T> {
 //!    MyEqMatcher { expected }
 //! }
 //! ```
@@ -258,8 +262,10 @@
 //! #    expected: T,
 //! # }
 //! #
-//! # impl<T: PartialEq + Debug> Matcher<T> for MyEqMatcher<T> {
-//! #    fn matches(&self, actual: &T) -> MatcherResult {
+//! # impl<T: PartialEq + Debug> Matcher for MyEqMatcher<T> {
+//! #    type ActualT = T;
+//! #
+//! #    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
 //! #        if self.expected == *actual {
 //! #            MatcherResult::Matches
 //! #        } else {
@@ -279,7 +285,7 @@
 //! #    }
 //! # }
 //! #
-//! # pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<T> {
+//! # pub fn eq_my_way<T: PartialEq + Debug>(expected: T) -> impl Matcher<ActualT = T> {
 //! #    MyEqMatcher { expected }
 //! # }
 //! # /* The attribute macro would prevent the function from being compiled in a doctest.

googletest/src/matcher.rs

@@ -17,14 +17,17 @@ use crate::internal::test_outcome::TestAssertionFailure;
 use std::fmt::{Debug, Display, Formatter, Result};
 
 /// An interface for checking an arbitrary condition on a datum.
-pub trait Matcher<T: Debug + ?Sized> {
+pub trait Matcher {
+    /// The type against which this matcher matches.
+    type ActualT: Debug + ?Sized;
+
     /// Returns whether the condition matches the datum `actual`.
     ///
     /// The trait implementation defines what it means to "match". Often the
     /// matching condition is based on data stored in the matcher. For example,
     /// `eq` matches when its stored expected value is equal (in the sense of
     /// the `==` operator) to the value `actual`.
-    fn matches(&self, actual: &T) -> MatcherResult;
+    fn matches(&self, actual: &Self::ActualT) -> MatcherResult;
 
     /// Returns a description of `self` or a negative description if
     /// `matcher_result` is `DoesNotMatch`.
@@ -107,7 +110,7 @@ pub trait Matcher<T: Debug + ?Sized> {
     /// inner matcher and appears as follows:
     ///
     /// ```ignore
-    /// fn explain_match(&self, actual: &ActualT) -> MatchExplanation {
+    /// fn explain_match(&self, actual: &Self::ActualT) -> MatchExplanation {
     ///     self.expected.explain_match(actual.deref())
     /// }
     /// ```
@@ -117,14 +120,14 @@ pub trait Matcher<T: Debug + ?Sized> {
     /// inner matcher at a point where a relative clause would fit. For example:
     ///
     /// ```ignore
-    /// fn explain_match(&self, actual: &ActualT) -> MatchExplanation {
+    /// fn explain_match(&self, actual: &Self::ActualT) -> MatchExplanation {
     ///     MatchExplanation::create(
     ///         format!("which points to a value {}", self.expected.explain_match(actual.deref()))
     ///             //   ^^^^^^^^^^^^^^^^^^^^ Expands to "points to a value which ..."
     ///     )
     /// }
     /// ```
-    fn explain_match(&self, actual: &T) -> MatchExplanation {
+    fn explain_match(&self, actual: &Self::ActualT) -> MatchExplanation {
         MatchExplanation::create(format!("which {}", self.describe(self.matches(actual))))
     }
 }
@@ -135,7 +138,7 @@ pub trait Matcher<T: Debug + ?Sized> {
 /// The parameter `actual_expr` contains the expression which was evaluated to
 /// obtain `actual`.
 pub(crate) fn create_assertion_failure<T: Debug + ?Sized>(
-    matcher: &impl Matcher<T>,
+    matcher: &impl Matcher<ActualT = T>,
     actual: &T,
     actual_expr: &'static str,
     source_location: SourceLocation,

googletest/src/matchers/all_matcher.rs

@@ -87,20 +87,22 @@ pub mod internal {
     /// For internal use only. API stablility is not guaranteed!
     #[doc(hidden)]
     pub struct AllMatcher<'a, T: Debug + ?Sized, const N: usize> {
-        components: [&'a dyn Matcher<T>; N],
+        components: [&'a dyn Matcher<ActualT = T>; N],
     }
 
     impl<'a, T: Debug + ?Sized, const N: usize> AllMatcher<'a, T, N> {
         /// Constructs an [`AllMatcher`] with the given component matchers.
         ///
         /// Intended for use only by the [`all`] macro.
-        pub fn new(components: [&'a dyn Matcher<T>; N]) -> Self {
+        pub fn new(components: [&'a dyn Matcher<ActualT = T>; N]) -> Self {
             Self { components }
         }
     }
 
-    impl<'a, T: Debug + ?Sized, const N: usize> Matcher<T> for AllMatcher<'a, T, N> {
-        fn matches(&self, actual: &T) -> MatcherResult {
+    impl<'a, T: Debug + ?Sized, const N: usize> Matcher for AllMatcher<'a, T, N> {
+        type ActualT = T;
+
+        fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
             for component in self.components {
                 match component.matches(actual) {
                     MatcherResult::DoesNotMatch => {
@@ -112,7 +114,7 @@ pub mod internal {
             MatcherResult::Matches
         }
 
-        fn explain_match(&self, actual: &T) -> MatchExplanation {
+        fn explain_match(&self, actual: &Self::ActualT) -> MatchExplanation {
             match N {
                 0 => anything::<T>().explain_match(actual),
                 1 => self.components[0].explain_match(actual),

googletest/src/matchers/anything_matcher.rs

@@ -15,7 +15,7 @@
 use crate::matcher::{Matcher, MatcherResult};
 #[cfg(google3)]
 use googletest::*;
-use std::fmt::Debug;
+use std::{fmt::Debug, marker::PhantomData};
 
 /// Matches anything. This matcher always succeeds.
 ///
@@ -31,13 +31,15 @@ use std::fmt::Debug;
 /// # }
 /// # should_pass().unwrap();
 /// ```
-pub fn anything<T: Debug + ?Sized>() -> impl Matcher<T> {
-    Anything {}
+pub fn anything<T: Debug + ?Sized>() -> impl Matcher<ActualT = T> {
+    Anything::<T>(Default::default())
 }
 
-struct Anything {}
+struct Anything<T: ?Sized>(PhantomData<T>);
+
+impl<T: Debug + ?Sized> Matcher for Anything<T> {
+    type ActualT = T;
 
-impl<T: Debug + ?Sized> Matcher<T> for Anything {
     fn matches(&self, _: &T) -> MatcherResult {
         MatcherResult::Matches
     }

googletest/src/matchers/conjunction_matcher.rs

@@ -15,10 +15,10 @@
 use crate::matcher::{MatchExplanation, Matcher, MatcherResult};
 #[cfg(google3)]
 use googletest::*;
-use std::fmt::Debug;
+use std::{fmt::Debug, marker::PhantomData};
 
 /// Extension trait providing the [`and`][AndMatcherExt::and] method.
-pub trait AndMatcherExt<T: Debug>: Matcher<T> {
+pub trait AndMatcherExt<T: Debug>: Matcher<ActualT = T> {
     /// Constructs a matcher that matches both `self` and `right`.
     ///
     /// ```
@@ -34,26 +34,31 @@ pub trait AndMatcherExt<T: Debug>: Matcher<T> {
     // TODO(b/264518763): Replace the return type with impl Matcher and reduce
     // visibility of ConjunctionMatcher once impl in return position in trait
     // methods is stable.
-    fn and<Right: Matcher<T>>(self, right: Right) -> ConjunctionMatcher<Self, Right>
+    fn and<Right: Matcher<ActualT = T>>(self, right: Right) -> ConjunctionMatcher<T, Self, Right>
     where
         Self: Sized,
     {
-        ConjunctionMatcher { m1: self, m2: right }
+        ConjunctionMatcher { m1: self, m2: right, phantom: Default::default() }
     }
 }
 
-impl<T: Debug, M> AndMatcherExt<T> for M where M: Matcher<T> {}
+impl<T: Debug, M> AndMatcherExt<T> for M where M: Matcher<ActualT = T> {}
 
 /// Matcher created by [`AndMatcherExt::and`].
 ///
 /// **For internal use only. API stablility is not guaranteed!**
 #[doc(hidden)]
-pub struct ConjunctionMatcher<M1, M2> {
+pub struct ConjunctionMatcher<T, M1, M2> {
     m1: M1,
     m2: M2,
+    phantom: PhantomData<T>,
 }
 
-impl<T: Debug, M1: Matcher<T>, M2: Matcher<T>> Matcher<T> for ConjunctionMatcher<M1, M2> {
+impl<T: Debug, M1: Matcher<ActualT = T>, M2: Matcher<ActualT = T>> Matcher
+    for ConjunctionMatcher<T, M1, M2>
+{
+    type ActualT = T;
+
     fn matches(&self, actual: &T) -> MatcherResult {
         match (self.m1.matches(actual), self.m2.matches(actual)) {
             (MatcherResult::Matches, MatcherResult::Matches) => MatcherResult::Matches,
@@ -89,7 +94,9 @@ mod tests {
     use crate::{verify_that, Result};
     #[cfg(google3)]
     use matchers::field;
-    use matchers::{anything, contains_substring, displays_as, eq, err, not};
+    use matchers::{
+        anything, contains_substring, displays_as, ends_with, eq, err, not, starts_with,
+    };
 
     #[test]
     fn and_true_true_matches() -> Result<()> {
@@ -149,4 +156,14 @@ mod tests {
             field!(Struct.a, eq(1)).and(field!(Struct.b, eq(2))).and(field!(Struct.c, eq(3)))
         )
     }
+
+    #[test]
+    fn works_with_str_slices() -> Result<()> {
+        verify_that!("A string", starts_with("A").and(ends_with("string")))
+    }
+
+    #[test]
+    fn works_with_owned_strings() -> Result<()> {
+        verify_that!("A string".to_string(), starts_with("A").and(ends_with("string")))
+    }
 }

googletest/src/matchers/container_eq_matcher.rs

@@ -100,8 +100,8 @@ pub struct ContainerEqMatcher<ActualContainerT: ?Sized, ExpectedContainerT> {
     phantom: PhantomData<ActualContainerT>,
 }
 
-impl<ActualElementT, ActualContainerT, ExpectedElementT, ExpectedContainerT>
-    Matcher<ActualContainerT> for ContainerEqMatcher<ActualContainerT, ExpectedContainerT>
+impl<ActualElementT, ActualContainerT, ExpectedElementT, ExpectedContainerT> Matcher
+    for ContainerEqMatcher<ActualContainerT, ExpectedContainerT>
 where
     ActualElementT: PartialEq<ExpectedElementT> + Debug + ?Sized,
     ActualContainerT: PartialEq<ExpectedContainerT> + Debug + ?Sized,
@@ -110,6 +110,8 @@ where
     for<'a> &'a ActualContainerT: IntoIterator<Item = &'a ActualElementT>,
     for<'a> &'a ExpectedContainerT: IntoIterator<Item = &'a ExpectedElementT>,
 {
+    type ActualT = ActualContainerT;
+
     fn matches(&self, actual: &ActualContainerT) -> MatcherResult {
         (*actual == self.expected).into()
     }
@@ -265,7 +267,7 @@ Actual: [
     }
 
     #[test]
-    fn container_eq_matches_owned_vec_with_slice() -> Result<()> {
+    fn container_eq_matches_owned_vec_with_array() -> Result<()> {
         let vector = vec![123, 234];
         verify_that!(vector, container_eq([123, 234]))
     }