1# Matchers Reference 2 3A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or 4`EXPECT_CALL()`, or use it to validate a value directly using two macros: 5 6| Macro | Description | 7| :----------------------------------- | :------------------------------------ | 8| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. | 9| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. | 10 11{: .callout .warning} 12**WARNING:** Equality matching via `EXPECT_THAT(actual_value, expected_value)` 13is supported, however note that implicit conversions can cause surprising 14results. For example, `EXPECT_THAT(some_bool, "some string")` will compile and 15may pass unintentionally. 16 17**BEST PRACTICE:** Prefer to make the comparison explicit via 18`EXPECT_THAT(actual_value, Eq(expected_value))` or `EXPECT_EQ(actual_value, 19expected_value)`. 20 21Built-in matchers (where `argument` is the function argument, e.g. 22`actual_value` in the example above, or when used in the context of 23`EXPECT_CALL(mock_object, method(matchers))`, the arguments of `method`) are 24divided into several categories. All matchers are defined in the `::testing` 25namespace unless otherwise noted. 26 27## Wildcard 28 29Matcher | Description 30:-------------------------- | :----------------------------------------------- 31`_` | `argument` can be any value of the correct type. 32`A<type>()` or `An<type>()` | `argument` can be any value of type `type`. 33 34## Generic Comparison 35 36| Matcher | Description | 37| :--------------------- | :-------------------------------------------------- | 38| `Eq(value)` or `value` | `argument == value` | 39| `Ge(value)` | `argument >= value` | 40| `Gt(value)` | `argument > value` | 41| `Le(value)` | `argument <= value` | 42| `Lt(value)` | `argument < value` | 43| `Ne(value)` | `argument != value` | 44| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. | 45| `IsTrue()` | `argument` evaluates to `true` in a Boolean context. | 46| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). | 47| `NotNull()` | `argument` is a non-null pointer (raw or smart). | 48| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. (For testing whether an `optional<>` is set, check for equality with `nullopt`. You may need to use `Eq(nullopt)` if the inner type doesn't have `==`.)| 49| `VariantWith<T>(m)` | `argument` is `variant<>` that holds the alternative of type T with a value matching `m`. | 50| `Ref(variable)` | `argument` is a reference to `variable`. | 51| `TypedEq<type>(value)` | `argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded. | 52 53Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or 54destructed later. If the compiler complains that `value` doesn't have a public 55copy constructor, try wrap it in `std::ref()`, e.g. 56`Eq(std::ref(non_copyable_value))`. If you do that, make sure 57`non_copyable_value` is not changed afterwards, or the meaning of your matcher 58will be changed. 59 60`IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types 61that can be explicitly converted to Boolean, but are not implicitly converted to 62Boolean. In other cases, you can use the basic 63[`EXPECT_TRUE` and `EXPECT_FALSE`](assertions.md#boolean) assertions. 64 65## Floating-Point Matchers {#FpMatchers} 66 67| Matcher | Description | 68| :------------------------------- | :--------------------------------- | 69| `DoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. | 70| `FloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. | 71| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | 72| `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. | 73| `IsNan()` | `argument` is any floating-point type with a NaN value. | 74 75The above matchers use ULP-based comparison (the same as used in googletest). 76They automatically pick a reasonable error bound based on the absolute value of 77the expected value. `DoubleEq()` and `FloatEq()` conform to the IEEE standard, 78which requires comparing two NaNs for equality to return false. The 79`NanSensitive*` version instead treats two NaNs as equal, which is often what a 80user wants. 81 82| Matcher | Description | 83| :------------------------------------------------ | :----------------------- | 84| `DoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as unequal. | 85| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as unequal. | 86| `NanSensitiveDoubleNear(a_double, max_abs_error)` | `argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as equal. | 87| `NanSensitiveFloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as equal. | 88 89## String Matchers 90 91The `argument` can be either a C string or a C++ string object: 92 93| Matcher | Description | 94| :---------------------- | :------------------------------------------------- | 95| `ContainsRegex(string)` | `argument` matches the given regular expression. | 96| `EndsWith(suffix)` | `argument` ends with string `suffix`. | 97| `HasSubstr(string)` | `argument` contains `string` as a sub-string. | 98| `IsEmpty()` | `argument` is an empty string. | 99| `MatchesRegex(string)` | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. | 100| `StartsWith(prefix)` | `argument` starts with string `prefix`. | 101| `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. | 102| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring case. | 103| `StrEq(string)` | `argument` is equal to `string`. | 104| `StrNe(string)` | `argument` is not equal to `string`. | 105| `WhenBase64Unescaped(m)` | `argument` is a base-64 escaped string whose unescaped string matches `m`. The web-safe format from [RFC 4648](https://www.rfc-editor.org/rfc/rfc4648#section-5) is supported. | 106 107`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They 108use the regular expression syntax defined 109[here](../advanced.md#regular-expression-syntax). All of these matchers, except 110`ContainsRegex()` and `MatchesRegex()` work for wide strings as well. 111 112## Container Matchers 113 114Most STL-style containers support `==`, so you can use `Eq(expected_container)` 115or simply `expected_container` to match a container exactly. If you want to 116write the elements in-line, match them more flexibly, or get more informative 117messages, you can use: 118 119| Matcher | Description | 120| :---------------------------------------- | :------------------------------- | 121| `BeginEndDistanceIs(m)` | `argument` is a container whose `begin()` and `end()` iterators are separated by a number of increments matching `m`. E.g. `BeginEndDistanceIs(2)` or `BeginEndDistanceIs(Lt(2))`. For containers that define a `size()` method, `SizeIs(m)` may be more efficient. | 122| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. | 123| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. | 124| `Contains(e).Times(n)` | `argument` contains elements that match `e`, which can be either a value or a matcher, and the number of matches is `n`, which can be either a value or a matcher. Unlike the plain `Contains` and `Each` this allows to check for arbitrary occurrences including testing for absence with `Contains(e).Times(0)`. | 125| `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. | 126| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. | 127| `ElementsAreArray({e0, e1, ..., en})`, `ElementsAreArray(a_container)`, `ElementsAreArray(begin, end)`, `ElementsAreArray(array)`, or `ElementsAreArray(array, count)` | The same as `ElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. | 128| `IsEmpty()` | `argument` is an empty container (`container.empty()`). | 129| `IsSubsetOf({e0, e1, ..., en})`, `IsSubsetOf(a_container)`, `IsSubsetOf(begin, end)`, `IsSubsetOf(array)`, or `IsSubsetOf(array, count)` | `argument` matches `UnorderedElementsAre(x0, x1, ..., xk)` for some subset `{x0, x1, ..., xk}` of the expected matchers. | 130| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. | 131| `Pointwise(m, container)`, `Pointwise(m, {e0, e1, ..., en})` | `argument` contains the same number of elements as in `container`, and for all i, (the i-th element in `argument`, the i-th element in `container`) match `m`, which is a matcher on 2-tuples. E.g. `Pointwise(Le(), upper_bounds)` verifies that each element in `argument` doesn't exceed the corresponding element in `upper_bounds`. See more detail below. | 132| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. | 133| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under *some* permutation of the elements, each element matches an `ei` (for a different `i`), which can be a value or a matcher. | 134| `UnorderedElementsAreArray({e0, e1, ..., en})`, `UnorderedElementsAreArray(a_container)`, `UnorderedElementsAreArray(begin, end)`, `UnorderedElementsAreArray(array)`, or `UnorderedElementsAreArray(array, count)` | The same as `UnorderedElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, iterator range, or C-style array. | 135| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. | 136| `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(ElementsAre(1, 2, 3))` verifies that `argument` contains elements 1, 2, and 3, ignoring order. | 137| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except that the given comparator instead of `<` is used to sort `argument`. E.g. `WhenSortedBy(std::greater(), ElementsAre(3, 2, 1))`. | 138 139**Notes:** 140 141* These matchers can also match: 142 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`), 143 and 144 2. an array passed as a pointer and a count (e.g. in `Bar(const T* buffer, 145 int len)` -- see [Multi-argument Matchers](#MultiArgMatchers)). 146* The array being matched may be multi-dimensional (i.e. its elements can be 147 arrays). 148* `m` in `Pointwise(m, ...)` and `UnorderedPointwise(m, ...)` should be a 149 matcher for `::std::tuple<T, U>` where `T` and `U` are the element type of 150 the actual container and the expected container, respectively. For example, 151 to compare two `Foo` containers where `Foo` doesn't support `operator==`, 152 one might write: 153 154 ```cpp 155 MATCHER(FooEq, "") { 156 return std::get<0>(arg).Equals(std::get<1>(arg)); 157 } 158 ... 159 EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos)); 160 ``` 161 162## Member Matchers 163 164| Matcher | Description | 165| :------------------------------ | :----------------------------------------- | 166| `Field(&class::field, m)` | `argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. | 167| `Field(field_name, &class::field, m)` | The same as the two-parameter version, but provides a better error message. | 168| `Key(e)` | `argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`. | 169| `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. | 170| `FieldsAre(m...)` | `argument` is a compatible object where each field matches piecewise with the matchers `m...`. A compatible object is any that supports the `std::tuple_size<Obj>`+`get<I>(obj)` protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates. | 171| `Property(&class::property, m)` | `argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_. The method `property()` must take no argument and be declared as `const`. | 172| `Property(property_name, &class::property, m)` | The same as the two-parameter version, but provides a better error message. 173 174**Notes:** 175 176* You can use `FieldsAre()` to match any type that supports structured 177 bindings, such as `std::tuple`, `std::pair`, `std::array`, and aggregate 178 types. For example: 179 180 ```cpp 181 std::tuple<int, std::string> my_tuple{7, "hello world"}; 182 EXPECT_THAT(my_tuple, FieldsAre(Ge(0), HasSubstr("hello"))); 183 184 struct MyStruct { 185 int value = 42; 186 std::string greeting = "aloha"; 187 }; 188 MyStruct s; 189 EXPECT_THAT(s, FieldsAre(42, "aloha")); 190 ``` 191 192* Don't use `Property()` against member functions that you do not own, because 193 taking addresses of functions is fragile and generally not part of the 194 contract of the function. 195 196## Matching the Result of a Function, Functor, or Callback 197 198| Matcher | Description | 199| :--------------- | :------------------------------------------------ | 200| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. | 201| `ResultOf(result_description, f, m)` | The same as the two-parameter version, but provides a better error message. 202 203## Pointer Matchers 204 205| Matcher | Description | 206| :------------------------ | :---------------------------------------------- | 207| `Address(m)` | the result of `std::addressof(argument)` matches `m`. | 208| `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. | 209| `Pointer(m)` | `argument` (either a smart pointer or a raw pointer) contains a pointer that matches `m`. `m` will match against the raw pointer regardless of the type of `argument`. | 210| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. | 211 212## Multi-argument Matchers {#MultiArgMatchers} 213 214Technically, all matchers match a *single* value. A "multi-argument" matcher is 215just one that matches a *tuple*. The following matchers can be used to match a 216tuple `(x, y)`: 217 218Matcher | Description 219:------ | :---------- 220`Eq()` | `x == y` 221`Ge()` | `x >= y` 222`Gt()` | `x > y` 223`Le()` | `x <= y` 224`Lt()` | `x < y` 225`Ne()` | `x != y` 226 227You can use the following selectors to pick a subset of the arguments (or 228reorder them) to participate in the matching: 229 230| Matcher | Description | 231| :------------------------- | :---------------------------------------------- | 232| `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. | 233| `Args<N1, N2, ..., Nk>(m)` | The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`. | 234 235## Composite Matchers 236 237You can make a matcher from one or more other matchers: 238 239| Matcher | Description | 240| :------------------------------- | :-------------------------------------- | 241| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. | 242| `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | 243| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. | 244| `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | 245| `Not(m)` | `argument` doesn't match matcher `m`. | 246| `Conditional(cond, m1, m2)` | Matches matcher `m1` if `cond` evaluates to true, else matches `m2`.| 247 248## Adapters for Matchers 249 250| Matcher | Description | 251| :---------------------- | :------------------------------------ | 252| `MatcherCast<T>(m)` | casts matcher `m` to type `Matcher<T>`. | 253| `SafeMatcherCast<T>(m)` | [safely casts](../gmock_cook_book.md#SafeMatcherCast) matcher `m` to type `Matcher<T>`. | 254| `Truly(predicate)` | `predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor. | 255 256`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`, 257which must be a permanent callback. 258 259## Using Matchers as Predicates {#MatchersAsPredicatesCheat} 260 261| Matcher | Description | 262| :---------------------------- | :------------------------------------------ | 263| `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor. | 264| `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. | 265| `Value(value, m)` | evaluates to `true` if `value` matches `m`. | 266 267## Defining Matchers 268 269| Macro | Description | 270| :----------------------------------- | :------------------------------------ | 271| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. | 272| `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a matcher `IsDivisibleBy(n)` to match a number divisible by `n`. | 273| `MATCHER_P2(IsBetween, a, b, absl::StrCat(negation ? "isn't" : "is", " between ", PrintToString(a), " and ", PrintToString(b))) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. | 274 275**Notes:** 276 2771. The `MATCHER*` macros cannot be used inside a function or class. 2782. The matcher body must be *purely functional* (i.e. it cannot have any side 279 effect, and the result must not depend on anything other than the value 280 being matched and the matcher parameters). 2813. You can use `PrintToString(x)` to convert a value `x` of any type to a 282 string. 2834. You can use `ExplainMatchResult()` in a custom matcher to wrap another 284 matcher, for example: 285 286 ```cpp 287 MATCHER_P(NestedPropertyMatches, matcher, "") { 288 return ExplainMatchResult(matcher, arg.nested().property(), result_listener); 289 } 290 ``` 291 2925. You can use `DescribeMatcher<>` to describe another matcher. For example: 293 294 ```cpp 295 MATCHER_P(XAndYThat, matcher, 296 "X that " + DescribeMatcher<int>(matcher, negation) + 297 (negation ? " or" : " and") + " Y that " + 298 DescribeMatcher<double>(matcher, negation)) { 299 return ExplainMatchResult(matcher, arg.x(), result_listener) && 300 ExplainMatchResult(matcher, arg.y(), result_listener); 301 } 302 ``` 303