]>
Commit | Line | Data |
---|---|---|
1e59de90 TL |
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 | ``` |