Include the type and variant being matched in the description of the matcher created by matches_pattern!.

Previously, the description would defer immediately to the inner matcher of the respective field or property. This was problematic when matching enum variants, since the variant itself would be left out. For example, the following code:

```
enum AnEnum {
    A(u32),
    B(u32),
}
let value = AnEnum::B(123);
verify_that!(value, matches_pattern!(AnEnum::A(eq(123)))
```

would yield the following assertion failure message:

```
Value of: value
Expected: has field `0`, which is equal to 123
Actual: AnEnum::B(123),
  which does not have field `0`
```

The failure message does not give any indication that the expected variant is `MyEnum::A` and is therefore misleading.

This change introduces a new matcher `is` which does nothing but defer to an inner matcher and add a given string to the description. With this new matcher, `matches_pattern!` now outputs the expected type or enum variant in the description:

```
Value of: value
Expected: is AnEnum :: A which has field `0`, which is equal to 123
Actual: AnEnum::B(123),
  which does not have field `0`
```

The match explanation is admittedly still rather confusing in this case, but fixing that is outside the scope of this change.

For consistency, this change also implements the new behaviour with properties as well as fields, even though properties cannot be used with enum variants.

This does not import the new matcher `is` into the list of matchers included in the prelude or the top-level list of matchers for the crate. The usefulness of `is` is fairly limited, so it does not seem worthwhile to include it. It must however have public visibility because it is used in a declarative macro.

PiperOrigin-RevId: 542850294

Author: hovinenb

googletest/src/matchers/is_matcher.rs

@@ -0,0 +1,65 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#![doc(hidden)]
+
+use crate::matcher::{Matcher, MatcherResult};
+use std::{fmt::Debug, marker::PhantomData};
+
+/// Matches precisely values matched by `inner`.
+///
+/// The returned matcher produces a description prefixed by the string
+/// `description`. This is useful in contexts where the test assertion failure
+/// output must include the additional description.
+pub fn is<'a, ActualT: Debug + 'a, InnerMatcherT: Matcher<ActualT = ActualT> + 'a>(
+    description: &'a str,
+    inner: InnerMatcherT,
+) -> impl Matcher<ActualT = ActualT> + 'a {
+    IsMatcher { description, inner, phantom: Default::default() }
+}
+
+struct IsMatcher<'a, ActualT, InnerMatcherT> {
+    description: &'a str,
+    inner: InnerMatcherT,
+    phantom: PhantomData<ActualT>,
+}
+
+impl<'a, ActualT: Debug, InnerMatcherT: Matcher<ActualT = ActualT>> Matcher
+    for IsMatcher<'a, ActualT, InnerMatcherT>
+{
+    type ActualT = ActualT;
+
+    fn matches(&self, actual: &Self::ActualT) -> MatcherResult {
+        self.inner.matches(actual)
+    }
+
+    fn describe(&self, matcher_result: MatcherResult) -> String {
+        match matcher_result {
+            MatcherResult::Matches => format!(
+                "is {} which {}",
+                self.description,
+                self.inner.describe(MatcherResult::Matches)
+            ),
+            MatcherResult::DoesNotMatch => format!(
+                "is not {} which {}",
+                self.description,
+                self.inner.describe(MatcherResult::Matches)
+            ),
+        }
+    }
+
+    fn explain_match(&self, actual: &Self::ActualT) -> String {
+        self.inner.explain_match(actual)
+    }
+}

googletest/src/matchers/matches_pattern.rs

@@ -259,21 +259,30 @@ macro_rules! matches_pattern_internal {
         [$($struct_name:tt)*],
         { $field_name:ident : $matcher:expr $(,)? }
     ) => {
-        all!(field!($($struct_name)*.$field_name, $matcher))
+        $crate::matchers::is_matcher::is(
+            stringify!($($struct_name)*),
+            all!(field!($($struct_name)*.$field_name, $matcher))
+        )
     };
 
     (
         [$($struct_name:tt)*],
         { $property_name:ident($($argument:expr),* $(,)?) : $matcher:expr $(,)? }
     ) => {
-        all!(property!($($struct_name)*.$property_name($($argument),*), $matcher))
+        $crate::matchers::is_matcher::is(
+            stringify!($($struct_name)*),
+            all!(property!($($struct_name)*.$property_name($($argument),*), $matcher))
+        )
     };
 
     (
         [$($struct_name:tt)*],
         { ref $property_name:ident($($argument:expr),* $(,)?) : $matcher:expr $(,)? }
     ) => {
-        all!(property!(ref $($struct_name)*.$property_name($($argument),*), $matcher))
+        $crate::matchers::is_matcher::is(
+            stringify!($($struct_name)*),
+            all!(property!(ref $($struct_name)*.$property_name($($argument),*), $matcher))
+        )
     };
 
     (
@@ -314,32 +323,32 @@ macro_rules! matches_pattern_internal {
         [$($struct_name:tt)*],
         { $field_name:ident : $matcher:expr $(,)? }
     ) => {
-        all!(
+        $crate::matchers::is_matcher::is(stringify!($($struct_name)*), all!(
             $($processed)*,
             field!($($struct_name)*.$field_name, $matcher)
-        )
+        ))
     };
 
     (
         all!($($processed:tt)*),
         [$($struct_name:tt)*],
         { $property_name:ident($($argument:expr),* $(,)?) : $matcher:expr $(,)? }
     ) => {
-        all!(
+        $crate::matchers::is_matcher::is(stringify!($($struct_name)*), all!(
             $($processed)*,
             property!($($struct_name)*.$property_name($($argument),*), $matcher)
-        )
+        ))
     };
 
     (
         all!($($processed:tt)*),
         [$($struct_name:tt)*],
         { ref $property_name:ident($($argument:expr),* $(,)?) : $matcher:expr $(,)? }
     ) => {
-        all!(
+        $crate::matchers::is_matcher::is(stringify!($($struct_name)*), all!(
             $($processed)*,
             property!(ref $($struct_name)*.$property_name($($argument),*), $matcher)
-        )
+        ))
     };
 
     (
@@ -401,7 +410,10 @@ macro_rules! matches_pattern_internal {
         [$($struct_name:tt)*],
         ($matcher:expr $(,)?)
     ) => {
-        all!(field!($($struct_name)*.0, $matcher))
+        $crate::matchers::is_matcher::is(
+            stringify!($($struct_name)*),
+            all!(field!($($struct_name)*.0, $matcher))
+        )
     };
 
     (
@@ -424,10 +436,10 @@ macro_rules! matches_pattern_internal {
         $field:tt,
         ($matcher:expr $(,)?)
     ) => {
-        all!(
+        $crate::matchers::is_matcher::is(stringify!($($struct_name)*), all!(
             $($processed)*,
             field!($($struct_name)*.$field, $matcher)
-        )
+        ))
     };
 
     // We need to repeat this once for every supported field position, unfortunately. There appears

googletest/src/matchers/mod.rs

@@ -32,6 +32,7 @@ pub mod field_matcher;
 pub mod ge_matcher;
 pub mod gt_matcher;
 pub mod has_entry_matcher;
+pub mod is_matcher;
 pub mod is_nan_matcher;
 pub mod le_matcher;
 pub mod len_matcher;