Fold the Describe trait into the Matcher trait.

This simplifies the implementation of matchers, since only one trait must be implemented.

On the downside, testing the describe method directly can be a bit more awkward due to the additional type annotations which are needed. However, this should not be a major problem in practice outside the library itself.

This change breaks API compatibility: existing matchers must be modified. In most cases it suffices to move the implementation of the Describe trait into that of the Matcher trait and remove the Describe implementation and references to it.

PiperOrigin-RevId: 503969016

Author: hovinenb

README.md

@@ -131,8 +131,7 @@ fn struct_has_expected_values() -> Result<()> {
 ## Writing matchers
 
 One can extend the library by writing additional matchers. To do so, create a
-struct holding the matcher's data and have it implement the traits [`Matcher`]
-and [`Describe`]:
+struct holding the matcher's data and have it implement the trait [`Matcher`]:
 
 ```rust
 struct MyEqMatcher<T> {
@@ -143,9 +142,7 @@ impl<T: PartialEq + Debug> Matcher<T> for MyEqMatcher<T> {
     fn matches(&self, actual: &A) -> MatcherResult {
         if self.expected == *actual { MatcherResult::Matches } else { MatcherResult::DoesNotMatch }
     }
-}
 
-impl<T: Debug> Describe for MyEqMatcher<T> {
     fn describe(&self, matcher_result: MatcherResult) -> String {
         match matcher_result {
             MatcherResult::Matches => {

googletest/src/matcher.rs

@@ -17,7 +17,7 @@ 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>: Describe {
+pub trait Matcher<T: Debug + ?Sized> {
     /// Returns whether the condition matches the datum `actual`.
     ///
     /// The trait implementation defines what it means to "match". Often the
@@ -34,10 +34,7 @@ pub trait Matcher<T: Debug + ?Sized>: Describe {
     fn explain_match(&self, actual: &T) -> MatchExplanation {
         MatchExplanation::create(format!("which {}", self.describe(self.matches(actual))))
     }
-}
 
-/// An interface to describe matchers, depending on `matcher_result`.
-pub trait Describe {
     /// Returns a description of `self` or a negative description if
     /// `matcher_result` is `DoesNotMatch`.
     ///

googletest/src/matchers/all_matcher.rs

@@ -54,7 +54,7 @@ pub mod internal {
     use crate as googletest;
     #[cfg(google3)]
     use anything_matcher::anything;
-    use googletest::matcher::{Describe, MatchExplanation, Matcher, MatcherResult};
+    use googletest::matcher::{MatchExplanation, Matcher, MatcherResult};
     #[cfg(not(google3))]
     use googletest::matchers::anything;
     use std::fmt::Debug;
@@ -107,9 +107,7 @@ pub mod internal {
                 }
             }
         }
-    }
 
-    impl<'a, T: Debug + ?Sized, const N: usize> Describe for AllMatcher<'a, T, N> {
         fn describe(&self, matcher_result: MatcherResult) -> String {
             match N {
                 0 => anything::<T>().describe(matcher_result),
@@ -130,10 +128,13 @@ mod tests {
     use super::*;
     #[cfg(not(google3))]
     use crate as googletest;
-    use googletest::matcher::{Describe, MatcherResult};
     #[cfg(not(google3))]
     use googletest::matchers;
-    use googletest::{google_test, matcher::Matcher, verify_that, Result};
+    use googletest::{
+        google_test,
+        matcher::{Matcher, MatcherResult},
+        verify_that, Result,
+    };
     use matchers::{contains_substring, displays_as, ends_with, eq, not, starts_with};
 
     #[google_test]

googletest/src/matchers/anything_matcher.rs

@@ -14,7 +14,7 @@
 
 #[cfg(not(google3))]
 use crate as googletest;
-use googletest::matcher::{Describe, Matcher, MatcherResult};
+use googletest::matcher::{Matcher, MatcherResult};
 use std::fmt::Debug;
 
 /// Matches anything. This matcher always succeeds.
@@ -36,9 +36,7 @@ impl<T: Debug + ?Sized> Matcher<T> for Anything {
     fn matches(&self, _: &T) -> MatcherResult {
         MatcherResult::Matches
     }
-}
 
-impl Describe for Anything {
     fn describe(&self, matcher_result: MatcherResult) -> String {
         match matcher_result {
             MatcherResult::Matches => "is anything".to_string(),

googletest/src/matchers/conjunction_matcher.rs

@@ -14,7 +14,7 @@
 
 #[cfg(not(google3))]
 use crate as googletest;
-use googletest::matcher::{Describe, MatchExplanation, Matcher, MatcherResult};
+use googletest::matcher::{MatchExplanation, Matcher, MatcherResult};
 use std::fmt::Debug;
 
 /// Extension trait providing the [`and`][AndMatcherExt::and] method.
@@ -68,9 +68,7 @@ impl<T: Debug, M1: Matcher<T>, M2: Matcher<T>> Matcher<T> for ConjunctionMatcher
             ),
         }
     }
-}
 
-impl<M1: Describe, M2: Describe> Describe for ConjunctionMatcher<M1, M2> {
     fn describe(&self, matcher_result: MatcherResult) -> String {
         format!("{}, and {}", self.m1.describe(matcher_result), self.m2.describe(matcher_result))
     }

googletest/src/matchers/container_eq_matcher.rs

@@ -14,7 +14,7 @@
 
 #[cfg(not(google3))]
 use crate as googletest;
-use googletest::matcher::{Describe, MatchExplanation, Matcher, MatcherResult};
+use googletest::matcher::{MatchExplanation, Matcher, MatcherResult};
 use std::fmt::Debug;
 use std::iter::zip;
 
@@ -92,6 +92,10 @@ where
     fn explain_match(&self, actual: &ContainerT) -> MatchExplanation {
         self.explain_match_impl(actual)
     }
+
+    fn describe(&self, matcher_result: MatcherResult) -> String {
+        self.describe_impl(matcher_result)
+    }
 }
 
 impl<T: PartialEq + Debug, const N: usize> Matcher<Vec<T>> for ContainerEqMatcher<[T; N]> {
@@ -106,6 +110,10 @@ impl<T: PartialEq + Debug, const N: usize> Matcher<Vec<T>> for ContainerEqMatche
     fn explain_match(&self, actual: &Vec<T>) -> MatchExplanation {
         self.explain_match_impl(actual)
     }
+
+    fn describe(&self, matcher_result: MatcherResult) -> String {
+        self.describe_impl(matcher_result)
+    }
 }
 
 impl<T: PartialEq + Debug, const N: usize> Matcher<[T]> for ContainerEqMatcher<[T; N]> {
@@ -116,6 +124,10 @@ impl<T: PartialEq + Debug, const N: usize> Matcher<[T]> for ContainerEqMatcher<[
     fn explain_match(&self, actual: &[T]) -> MatchExplanation {
         self.explain_match_impl(actual)
     }
+
+    fn describe(&self, matcher_result: MatcherResult) -> String {
+        self.describe_impl(matcher_result)
+    }
 }
 
 impl<const N: usize> Matcher<Vec<String>> for ContainerEqMatcher<[&str; N]> {
@@ -137,6 +149,10 @@ impl<const N: usize> Matcher<Vec<String>> for ContainerEqMatcher<[&str; N]> {
             self.get_unexpected_string_items(actual),
         )
     }
+
+    fn describe(&self, matcher_result: MatcherResult) -> String {
+        self.describe_impl(matcher_result)
+    }
 }
 
 impl<T: PartialEq + Debug, ExpectedT: Debug> ContainerEqMatcher<ExpectedT>
@@ -171,6 +187,15 @@ where
     }
 }
 
+impl<ExpectedT: Debug> ContainerEqMatcher<ExpectedT> {
+    fn describe_impl(&self, matcher_result: MatcherResult) -> String {
+        match matcher_result {
+            MatcherResult::Matches => format!("is equal to {:?}", self.expected),
+            MatcherResult::DoesNotMatch => format!("isn't equal to {:?}", self.expected),
+        }
+    }
+}
+
 fn build_explanation<T: Debug, U: Debug>(missing: Vec<T>, unexpected: Vec<U>) -> MatchExplanation {
     match (missing.len(), unexpected.len()) {
         // TODO(b/261175849) add more data here (out of order elements, duplicated elements, etc...)
@@ -222,15 +247,6 @@ impl<const N: usize> ContainerEqMatcher<[&str; N]> {
     }
 }
 
-impl<T: Debug> Describe for ContainerEqMatcher<T> {
-    fn describe(&self, matcher_result: MatcherResult) -> String {
-        match matcher_result {
-            MatcherResult::Matches => format!("is equal to {:?}", self.expected),
-            MatcherResult::DoesNotMatch => format!("isn't equal to {:?}", self.expected),
-        }
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;

googletest/src/matchers/contains_matcher.rs

@@ -14,7 +14,7 @@
 
 #[cfg(not(google3))]
 use crate as googletest;
-use googletest::matcher::{Describe, MatchExplanation, Matcher, MatcherResult};
+use googletest::matcher::{MatchExplanation, Matcher, MatcherResult};
 use std::fmt::Debug;
 
 /// Matches an iterable type whose elements contain a value matched by `inner`.
@@ -97,9 +97,7 @@ where
             (_, None) => MatchExplanation::create("which contains a matching element".to_string()),
         }
     }
-}
 
-impl<InnerMatcherT: Describe> Describe for ContainsMatcher<InnerMatcherT> {
     fn describe(&self, matcher_result: MatcherResult) -> String {
         match (matcher_result, &self.count) {
             (MatcherResult::Matches, Some(count)) => format!(
@@ -146,7 +144,7 @@ mod tests {
     use crate as googletest;
     #[cfg(not(google3))]
     use googletest::matchers;
-    use googletest::{google_test, verify_that, Result};
+    use googletest::{google_test, matcher::Matcher, verify_that, Result};
     use matchers::{displays_as, eq};
 
     #[google_test]
@@ -226,7 +224,7 @@ mod tests {
         let matcher = contains(eq(1));
 
         verify_that!(
-            matcher.describe(MatcherResult::Matches),
+            <ContainsMatcher<_> as Matcher<Vec<i32>>>::describe(&matcher, MatcherResult::Matches),
             eq("contains at least one element which is equal to 1")
         )
     }
@@ -236,7 +234,7 @@ mod tests {
         let matcher = contains(eq(1)).times(eq(2));
 
         verify_that!(
-            matcher.describe(MatcherResult::Matches),
+            <ContainsMatcher<_> as Matcher<Vec<i32>>>::describe(&matcher, MatcherResult::Matches),
             eq("contains n elements which is equal to 1\n  where n is equal to 2")
         )
     }

googletest/src/matchers/contains_regex_matcher.rs

@@ -14,7 +14,7 @@
 
 #[cfg(not(google3))]
 use crate as googletest;
-use googletest::matcher::{Describe, Matcher, MatcherResult};
+use googletest::matcher::{Matcher, MatcherResult};
 use regex::Regex;
 use std::fmt::Debug;
 use std::ops::Deref;
@@ -60,9 +60,7 @@ impl<ActualT: AsRef<str> + Debug + ?Sized> Matcher<ActualT> for ContainsRegexMat
             MatcherResult::DoesNotMatch
         }
     }
-}
 
-impl Describe for ContainsRegexMatcher {
     fn describe(&self, matcher_result: MatcherResult) -> String {
         match matcher_result {
             MatcherResult::Matches => {
@@ -82,7 +80,7 @@ mod tests {
     use crate as googletest;
     #[cfg(not(google3))]
     use googletest::matchers;
-    use googletest::{google_test, verify_that, Result};
+    use googletest::{google_test, matcher::Matcher, verify_that, Result};
     use matchers::eq;
 
     #[google_test]
@@ -131,7 +129,7 @@ mod tests {
         let matcher = contains_regex("\n");
 
         verify_that!(
-            matcher.describe(MatcherResult::Matches),
+            <ContainsRegexMatcher as Matcher<&str>>::describe(&matcher, MatcherResult::Matches),
             eq("contains the regular expression \"\\n\"")
         )
     }

googletest/src/matchers/contains_substring_matcher.rs

@@ -14,7 +14,7 @@
 
 #[cfg(not(google3))]
 use crate as googletest;
-use googletest::matcher::{Describe, Matcher, MatcherResult};
+use googletest::matcher::{Matcher, MatcherResult};
 use std::fmt::Debug;
 use std::ops::Deref;
 
@@ -60,9 +60,7 @@ where
             MatcherResult::DoesNotMatch
         }
     }
-}
 
-impl<SubstringT: Deref<Target = str>> Describe for ContainsSubstringMatcher<SubstringT> {
     fn describe(&self, matcher_result: MatcherResult) -> String {
         match matcher_result {
             MatcherResult::Matches => format!("contains substring {:#?}", self.substring.deref()),
@@ -128,6 +126,12 @@ mod tests {
     fn contains_substring_displays_quoted_debug_of_substring() -> Result<()> {
         let matcher = contains_substring("\n");
 
-        verify_that!(matcher.describe(MatcherResult::Matches), eq("contains substring \"\\n\""))
+        verify_that!(
+            <ContainsSubstringMatcher<&str> as Matcher<&str>>::describe(
+                &matcher,
+                MatcherResult::Matches
+            ),
+            eq("contains substring \"\\n\"")
+        )
     }
 }

googletest/src/matchers/disjunction_matcher.rs

@@ -14,7 +14,7 @@
 
 #[cfg(not(google3))]
 use crate as googletest;
-use googletest::matcher::{Describe, MatchExplanation, Matcher, MatcherResult};
+use googletest::matcher::{MatchExplanation, Matcher, MatcherResult};
 use std::fmt::Debug;
 
 /// Extension trait providing the [`or`][OrMatcherExt::or] method.
@@ -66,9 +66,7 @@ impl<T: Debug, M1: Matcher<T>, M2: Matcher<T>> Matcher<T> for DisjunctionMatcher
             self.m2.explain_match(actual)
         ))
     }
-}
 
-impl<M1: Describe, M2: Describe> Describe for DisjunctionMatcher<M1, M2> {
     fn describe(&self, matcher_result: MatcherResult) -> String {
         format!("{}, or {}", self.m1.describe(matcher_result), self.m2.describe(matcher_result))
     }