docs/reference/matchers.md

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