gmock_cheat_sheet.md 36.8 KB
Newer Older
Abseil Team's avatar
Abseil Team committed
1
# gMock Cheat Sheet
2

Abseil Team's avatar
Abseil Team committed
3
## Defining a Mock Class
4

Abseil Team's avatar
Abseil Team committed
5
### Mocking a Normal Class {#MockClass}
6
7

Given
8

9
```cpp
10
11
12
13
14
15
16
17
18
class Foo {
  ...
  virtual ~Foo();
  virtual int GetSize() const = 0;
  virtual string Describe(const char* name) = 0;
  virtual string Describe(int type) = 0;
  virtual bool Process(Bar elem, int count) = 0;
};
```
19

20
(note that `~Foo()` **must** be virtual) we can define its mock as
21

22
```cpp
23
24
25
#include "gmock/gmock.h"

class MockFoo : public Foo {
26
27
28
29
30
  ...
  MOCK_METHOD(int, GetSize, (), (const, override));
  MOCK_METHOD(string, Describe, (const char* name), (override));
  MOCK_METHOD(string, Describe, (int type), (override));
  MOCK_METHOD(bool, Process, (Bar elem, int count), (override));
31
32
33
};
```

34
35
36
37
To create a "nice" mock, which ignores all uninteresting calls, a "naggy" mock,
which warns on all uninteresting calls, or a "strict" mock, which treats them as
failures:

38
```cpp
39
40
41
42
43
44
45
using ::testing::NiceMock;
using ::testing::NaggyMock;
using ::testing::StrictMock;

NiceMock<MockFoo> nice_foo;      // The type is a subclass of MockFoo.
NaggyMock<MockFoo> naggy_foo;    // The type is a subclass of MockFoo.
StrictMock<MockFoo> strict_foo;  // The type is a subclass of MockFoo.
46
47
```

48
49
50
**Note:** A mock object is currently naggy by default. We may make it nice by
default in the future.

Abseil Team's avatar
Abseil Team committed
51
### Mocking a Class Template {#MockTemplate}
52
53

Class templates can be mocked just like any class.
54
55

To mock
56

57
```cpp
58
59
60
61
62
63
64
65
template <typename Elem>
class StackInterface {
  ...
  virtual ~StackInterface();
  virtual int GetSize() const = 0;
  virtual void Push(const Elem& x) = 0;
};
```
66
67
68
69

(note that all member functions that are mocked, including `~StackInterface()`
**must** be virtual).

70
```cpp
71
72
73
template <typename Elem>
class MockStack : public StackInterface<Elem> {
  ...
74
75
  MOCK_METHOD(int, GetSize, (), (const, override));
  MOCK_METHOD(void, Push, (const Elem& x), (override));
76
77
78
};
```

Abseil Team's avatar
Abseil Team committed
79
### Specifying Calling Conventions for Mock Functions
80
81
82
83

If your mock function doesn't use the default calling convention, you can
specify it by adding `Calltype(convention)` to `MOCK_METHOD`'s 4th parameter.
For example,
84

85
```cpp
86
87
88
  MOCK_METHOD(bool, Foo, (int n), (Calltype(STDMETHODCALLTYPE)));
  MOCK_METHOD(int, Bar, (double x, double y),
              (const, Calltype(STDMETHODCALLTYPE)));
89
```
90

91
92
where `STDMETHODCALLTYPE` is defined by `<objbase.h>` on Windows.

Abseil Team's avatar
Abseil Team committed
93
## Using Mocks in Tests {#UsingMocks}
94

95
96
97
98
99
100
101
102
103
104
105
106
107
108
The typical work flow is:

1.  Import the gMock names you need to use. All gMock symbols are in the
    `testing` namespace unless they are macros or otherwise noted.
2.  Create the mock objects.
3.  Optionally, set the default actions of the mock objects.
4.  Set your expectations on the mock objects (How will they be called? What
    will they do?).
5.  Exercise code that uses the mock objects; if necessary, check the result
    using googletest assertions.
6.  When a mock object is destructed, gMock automatically verifies that all
    expectations on it have been satisfied.

Here's an example:
109

110
111
```cpp
using ::testing::Return;                          // #1
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

TEST(BarTest, DoesThis) {
  MockFoo foo;                                    // #2

  ON_CALL(foo, GetSize())                         // #3
      .WillByDefault(Return(1));
  // ... other default actions ...

  EXPECT_CALL(foo, Describe(5))                   // #4
      .Times(3)
      .WillRepeatedly(Return("Category 5"));
  // ... other expectations ...

  EXPECT_EQ("good", MyProductionFunction(&foo));  // #5
}                                                 // #6
```

Abseil Team's avatar
Abseil Team committed
129
## Setting Default Actions {#OnCall}
130

131
132
133
134
135
gMock has a **built-in default action** for any function that returns `void`,
`bool`, a numeric value, or a pointer. In C++11, it will additionally returns
the default-constructed value, if one exists for the given type.

To customize the default action for functions with return type *`T`*:
136

137
```cpp
138
139
140
141
142
using ::testing::DefaultValue;

// Sets the default value to be returned. T must be CopyConstructible.
DefaultValue<T>::Set(value);
// Sets a factory. Will be invoked on demand. T must be MoveConstructible.
143
//  T MakeT();
144
145
146
147
148
149
DefaultValue<T>::SetFactory(&MakeT);
// ... use the mocks ...
// Resets the default value.
DefaultValue<T>::Clear();
```

150
151
Example usage:

152
```cpp
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
  // Sets the default action for return type std::unique_ptr<Buzz> to
  // creating a new Buzz every time.
  DefaultValue<std::unique_ptr<Buzz>>::SetFactory(
      [] { return MakeUnique<Buzz>(AccessLevel::kInternal); });

  // When this fires, the default action of MakeBuzz() will run, which
  // will return a new Buzz object.
  EXPECT_CALL(mock_buzzer_, MakeBuzz("hello")).Times(AnyNumber());

  auto buzz1 = mock_buzzer_.MakeBuzz("hello");
  auto buzz2 = mock_buzzer_.MakeBuzz("hello");
  EXPECT_NE(nullptr, buzz1);
  EXPECT_NE(nullptr, buzz2);
  EXPECT_NE(buzz1, buzz2);

  // Resets the default action for return type std::unique_ptr<Buzz>,
  // to avoid interfere with other tests.
  DefaultValue<std::unique_ptr<Buzz>>::Clear();
171
172
```

173
174
175
To customize the default action for a particular method of a specific mock
object, use `ON_CALL()`. `ON_CALL()` has a similar syntax to `EXPECT_CALL()`,
but it is used for setting default behaviors (when you do not require that the
Abseil Team's avatar
Abseil Team committed
176
177
mock method is called). See [here](gmock_cook_book.md#UseOnCall) for a more
detailed discussion.
178

179
```cpp
180
181
182
ON_CALL(mock-object, method(matchers))
    .With(multi-argument-matcher)   ?
    .WillByDefault(action);
183
184
```

Abseil Team's avatar
Abseil Team committed
185
## Setting Expectations {#ExpectCall}
186

187
188
`EXPECT_CALL()` sets **expectations** on a mock method (How will it be called?
What will it do?):
189

190
```cpp
191
192
193
194
195
196
197
198
EXPECT_CALL(mock-object, method (matchers)?)
     .With(multi-argument-matcher)  ?
     .Times(cardinality)            ?
     .InSequence(sequences)         *
     .After(expectations)           *
     .WillOnce(action)              *
     .WillRepeatedly(action)        ?
     .RetiresOnSaturation();        ?
199
200
```

Abseil Team's avatar
Abseil Team committed
201
202
203
204
205
206
207
208
209
For each item above, `?` means it can be used at most once, while `*` means it
can be used any number of times.

In order to pass, `EXPECT_CALL` must be used before the calls are actually made.

The `(matchers)` is a comma-separated list of matchers that correspond to each
of the arguments of `method`, and sets the expectation only for calls of
`method` that matches all of the matchers.

210
211
If `(matchers)` is omitted, the expectation is the same as if the matchers were
set to anything matchers (for example, `(_, _, _, _)` for a four-arg method).
212

213
If `Times()` is omitted, the cardinality is assumed to be:
214

215
216
217
218
219
220
221
222
223
*   `Times(1)` when there is neither `WillOnce()` nor `WillRepeatedly()`;
*   `Times(n)` when there are `n` `WillOnce()`s but no `WillRepeatedly()`, where
    `n` >= 1; or
*   `Times(AtLeast(n))` when there are `n` `WillOnce()`s and a
    `WillRepeatedly()`, where `n` >= 0.

A method with no `EXPECT_CALL()` is free to be invoked *any number of times*,
and the default action will be taken each time.

Abseil Team's avatar
Abseil Team committed
224
## Matchers {#MatcherList}
225
226

A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
Abseil Team's avatar
Abseil Team committed
227
`EXPECT_CALL()`, or use it to validate a value directly using two macros:
228

Abseil Team's avatar
Abseil Team committed
229
<!-- mdformat off(github rendering does not support multiline tables) -->
Abseil Team's avatar
Abseil Team committed
230
| Macro                                | Description                           |
231
| :----------------------------------- | :------------------------------------ |
Abseil Team's avatar
Abseil Team committed
232
233
234
| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. |
| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. |
<!-- mdformat on -->
235

Abseil Team's avatar
Abseil Team committed
236
237
238
239
240
**Note:** Although equality matching via `EXPECT_THAT(actual_value,
expected_value)` is supported, prefer to make the comparison explicit via
`EXPECT_THAT(actual_value, Eq(expected_value))` or `EXPECT_EQ(actual_value,
expected_value)`.

Abseil Team's avatar
Abseil Team committed
241
Built-in matchers (where `argument` is the function argument, e.g.
Abseil Team's avatar
Abseil Team committed
242
243
244
`actual_value` in the example above, or when used in the context of
`EXPECT_CALL(mock_object, method(matchers))`, the arguments of `method`) are
divided into several categories:
245

Abseil Team's avatar
Abseil Team committed
246
### Wildcard
247
248
249
250
251
252

Matcher                     | Description
:-------------------------- | :-----------------------------------------------
`_`                         | `argument` can be any value of the correct type.
`A<type>()` or `An<type>()` | `argument` can be any value of type `type`.

Abseil Team's avatar
Abseil Team committed
253
### Generic Comparison
254

Abseil Team's avatar
Abseil Team committed
255
<!-- mdformat off(no multiline tables) -->
256
257
258
259
260
261
262
263
| Matcher                | Description                                         |
| :--------------------- | :-------------------------------------------------- |
| `Eq(value)` or `value` | `argument == value`                                 |
| `Ge(value)`            | `argument >= value`                                 |
| `Gt(value)`            | `argument > value`                                  |
| `Le(value)`            | `argument <= value`                                 |
| `Lt(value)`            | `argument < value`                                  |
| `Ne(value)`            | `argument != value`                                 |
Abseil Team's avatar
Abseil Team committed
264
265
| `IsFalse()`            | `argument` evaluates to `false` in a Boolean context. |
| `IsTrue()`             | `argument` evaluates to `true` in a Boolean context. |
266
267
| `IsNull()`             | `argument` is a `NULL` pointer (raw or smart).      |
| `NotNull()`            | `argument` is a non-null pointer (raw or smart).    |
Abseil Team's avatar
Abseil Team committed
268
| `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 `==`.)|
Abseil Team's avatar
Abseil Team committed
269
| `VariantWith<T>(m)`    | `argument` is `variant<>` that holds the alternative of type T with a value matching `m`. |
270
| `Ref(variable)`        | `argument` is a reference to `variable`.            |
Abseil Team's avatar
Abseil Team committed
271
272
| `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. |
<!-- mdformat on -->
273
274
275

Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or
destructed later. If the compiler complains that `value` doesn't have a public
ofats's avatar
ofats committed
276
277
278
279
copy constructor, try wrap it in `std::ref()`, e.g.
`Eq(std::ref(non_copyable_value))`. If you do that, make sure
`non_copyable_value` is not changed afterwards, or the meaning of your matcher
will be changed.
280

Abseil Team's avatar
Abseil Team committed
281
282
283
`IsTrue` and `IsFalse` are useful when you need to use a matcher, or for types
that can be explicitly converted to Boolean, but are not implicitly converted to
Boolean. In other cases, you can use the basic
Abseil Team's avatar
Abseil Team committed
284
[`EXPECT_TRUE` and `EXPECT_FALSE`](primer.md#basic-assertions) assertions.
Abseil Team's avatar
Abseil Team committed
285

Abseil Team's avatar
Abseil Team committed
286
### Floating-Point Matchers {#FpMatchers}
287

Abseil Team's avatar
Abseil Team committed
288
<!-- mdformat off(no multiline tables) -->
289
290
| Matcher                          | Description                        |
| :------------------------------- | :--------------------------------- |
Abseil Team's avatar
Abseil Team committed
291
292
293
294
| `DoubleEq(a_double)`             | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. |
| `FloatEq(a_float)`               | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. |
| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. |
| `NanSensitiveFloatEq(a_float)`   | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. |
Abseil Team's avatar
Abseil Team committed
295
| `IsNan()`   | `argument` is any floating-point type with a NaN value. |
Abseil Team's avatar
Abseil Team committed
296
<!-- mdformat on -->
297
298
299
300
301
302
303
304

The above matchers use ULP-based comparison (the same as used in googletest).
They automatically pick a reasonable error bound based on the absolute value of
the expected value. `DoubleEq()` and `FloatEq()` conform to the IEEE standard,
which requires comparing two NaNs for equality to return false. The
`NanSensitive*` version instead treats two NaNs as equal, which is often what a
user wants.

Abseil Team's avatar
Abseil Team committed
305
306
307
308
309
310
311
312
<!-- mdformat off(no multiline tables) -->
| Matcher                                           | Description              |
| :------------------------------------------------ | :----------------------- |
| `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. |
| `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. |
| `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. |
| `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. |
<!-- mdformat on -->
313

Abseil Team's avatar
Abseil Team committed
314
### String Matchers
315

316
The `argument` can be either a C string or a C++ string object:
317

Abseil Team's avatar
Abseil Team committed
318
<!-- mdformat off(no multiline tables) -->
319
320
321
322
323
| Matcher                 | Description                                        |
| :---------------------- | :------------------------------------------------- |
| `ContainsRegex(string)` | `argument` matches the given regular expression.   |
| `EndsWith(suffix)`      | `argument` ends with string `suffix`.              |
| `HasSubstr(string)`     | `argument` contains `string` as a sub-string.      |
Abseil Team's avatar
Abseil Team committed
324
| `IsEmpty()`             | `argument` is an empty string.                     |
Abseil Team's avatar
Abseil Team committed
325
| `MatchesRegex(string)`  | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. |
326
327
| `StartsWith(prefix)`    | `argument` starts with string `prefix`.            |
| `StrCaseEq(string)`     | `argument` is equal to `string`, ignoring case.    |
Abseil Team's avatar
Abseil Team committed
328
| `StrCaseNe(string)`     | `argument` is not equal to `string`, ignoring case. |
329
330
| `StrEq(string)`         | `argument` is equal to `string`.                   |
| `StrNe(string)`         | `argument` is not equal to `string`.               |
Abseil Team's avatar
Abseil Team committed
331
<!-- mdformat on -->
332
333
334

`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They
use the regular expression syntax defined
Abseil Team's avatar
Abseil Team committed
335
336
[here](advanced.md#regular-expression-syntax). All of these matchers, except
`ContainsRegex()` and `MatchesRegex()` work for wide strings as well.
337

Abseil Team's avatar
Abseil Team committed
338
### Container Matchers
339
340
341
342
343
344

Most STL-style containers support `==`, so you can use `Eq(expected_container)`
or simply `expected_container` to match a container exactly. If you want to
write the elements in-line, match them more flexibly, or get more informative
messages, you can use:

Abseil Team's avatar
Abseil Team committed
345
<!-- mdformat off(no multiline tables) -->
346
347
| Matcher                                   | Description                      |
| :---------------------------------------- | :------------------------------- |
Abseil Team's avatar
Abseil Team committed
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
| `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. |
| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. |
| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. |
| `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. |
| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. |
| `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. |
| `IsEmpty()` | `argument` is an empty container (`container.empty()`). |
| `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. |
| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. |
| `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. |
| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. |
| `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. |
| `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. |
| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. |
| `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. |
| `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))`. |
<!-- mdformat on -->
365

366
**Notes:**
367

368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
*   These matchers can also match:
    1.  a native array passed by reference (e.g. in `Foo(const int (&a)[5])`),
        and
    2.  an array passed as a pointer and a count (e.g. in `Bar(const T* buffer,
        int len)` -- see [Multi-argument Matchers](#MultiArgMatchers)).
*   The array being matched may be multi-dimensional (i.e. its elements can be
    arrays).
*   `m` in `Pointwise(m, ...)` should be a matcher for `::std::tuple<T, U>`
    where `T` and `U` are the element type of the actual container and the
    expected container, respectively. For example, to compare two `Foo`
    containers where `Foo` doesn't support `operator==`, one might write:

    ```cpp
    using ::std::get;
    MATCHER(FooEq, "") {
      return std::get<0>(arg).Equals(std::get<1>(arg));
    }
    ...
    EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos));
    ```

Abseil Team's avatar
Abseil Team committed
389
### Member Matchers
390

Abseil Team's avatar
Abseil Team committed
391
<!-- mdformat off(no multiline tables) -->
392
393
| Matcher                         | Description                                |
| :------------------------------ | :----------------------------------------- |
Abseil Team's avatar
Abseil Team committed
394
| `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_. |
Abseil Team's avatar
Abseil Team committed
395
| `Field(field_name, &class::field, m)` | The same as the two-parameter version, but provides a better error message. |
Abseil Team's avatar
Abseil Team committed
396
397
| `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`. |
| `Pair(m1, m2)`                  | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. |
Abseil Team's avatar
Abseil Team committed
398
| `FieldsAre(m...)`                   | `argument` is a compatible object where each field matches piecewise with `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. |
Abseil Team's avatar
Abseil Team committed
399
| `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_. |
Abseil Team's avatar
Abseil Team committed
400
| `Property(property_name, &class::property, m)` | The same as the two-parameter version, but provides a better error message.
Abseil Team's avatar
Abseil Team committed
401
<!-- mdformat on -->
402

Abseil Team's avatar
Abseil Team committed
403
### Matching the Result of a Function, Functor, or Callback
404

Abseil Team's avatar
Abseil Team committed
405
<!-- mdformat off(no multiline tables) -->
406
407
| Matcher          | Description                                       |
| :--------------- | :------------------------------------------------ |
Abseil Team's avatar
Abseil Team committed
408
409
| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. |
<!-- mdformat on -->
410

Abseil Team's avatar
Abseil Team committed
411
### Pointer Matchers
412

Abseil Team's avatar
Abseil Team committed
413
<!-- mdformat off(no multiline tables) -->
414
415
| Matcher                   | Description                                     |
| :------------------------ | :---------------------------------------------- |
Abseil Team's avatar
Abseil Team committed
416
| `Address(m)`              | the result of `std::addressof(argument)` matches `m`. |
Abseil Team's avatar
Abseil Team committed
417
| `Pointee(m)`              | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. |
Abseil Team's avatar
Abseil Team committed
418
| `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`. |
Abseil Team's avatar
Abseil Team committed
419
420
| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. |
<!-- mdformat on -->
421

Abseil Team's avatar
Abseil Team committed
422
### Multi-argument Matchers {#MultiArgMatchers}
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439

Technically, all matchers match a *single* value. A "multi-argument" matcher is
just one that matches a *tuple*. The following matchers can be used to match a
tuple `(x, y)`:

Matcher | Description
:------ | :----------
`Eq()`  | `x == y`
`Ge()`  | `x >= y`
`Gt()`  | `x > y`
`Le()`  | `x <= y`
`Lt()`  | `x < y`
`Ne()`  | `x != y`

You can use the following selectors to pick a subset of the arguments (or
reorder them) to participate in the matching:

Abseil Team's avatar
Abseil Team committed
440
<!-- mdformat off(no multiline tables) -->
441
442
| Matcher                    | Description                                     |
| :------------------------- | :---------------------------------------------- |
Abseil Team's avatar
Abseil Team committed
443
444
445
| `AllArgs(m)`               | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. |
| `Args<N1, N2, ..., Nk>(m)` | The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`. |
<!-- mdformat on -->
446

Abseil Team's avatar
Abseil Team committed
447
### Composite Matchers
448
449
450

You can make a matcher from one or more other matchers:

Abseil Team's avatar
Abseil Team committed
451
<!-- mdformat off(no multiline tables) -->
452
453
| Matcher                          | Description                             |
| :------------------------------- | :-------------------------------------- |
Abseil Team's avatar
Abseil Team committed
454
455
456
457
458
459
| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. |
| `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. |
| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. |
| `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. |
| `Not(m)` | `argument` doesn't match matcher `m`. |
<!-- mdformat on -->
460

Abseil Team's avatar
Abseil Team committed
461
### Adapters for Matchers
462

Abseil Team's avatar
Abseil Team committed
463
<!-- mdformat off(no multiline tables) -->
464
465
| Matcher                 | Description                           |
| :---------------------- | :------------------------------------ |
Abseil Team's avatar
Abseil Team committed
466
| `MatcherCast<T>(m)`     | casts matcher `m` to type `Matcher<T>`. |
Abseil Team's avatar
Abseil Team committed
467
| `SafeMatcherCast<T>(m)` | [safely casts](gmock_cook_book.md#casting-matchers) matcher `m` to type `Matcher<T>`. |
Abseil Team's avatar
Abseil Team committed
468
469
| `Truly(predicate)`      | `predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor. |
<!-- mdformat on -->
470
471
472
473

`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`,
which must be a permanent callback.

Abseil Team's avatar
Abseil Team committed
474
### Using Matchers as Predicates {#MatchersAsPredicatesCheat}
475

Abseil Team's avatar
Abseil Team committed
476
<!-- mdformat off(no multiline tables) -->
477
478
| Matcher                       | Description                                 |
| :---------------------------- | :------------------------------------------ |
Abseil Team's avatar
Abseil Team committed
479
480
481
482
| `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor. |
| `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. |
| `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
<!-- mdformat on -->
483

Abseil Team's avatar
Abseil Team committed
484
### Defining Matchers
485

Abseil Team's avatar
Abseil Team committed
486
<!-- mdformat off(no multiline tables) -->
487
488
| Matcher                              | Description                           |
| :----------------------------------- | :------------------------------------ |
Abseil Team's avatar
Abseil Team committed
489
| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. |
Abseil Team's avatar
Abseil Team committed
490
| `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`. |
Abseil Team's avatar
Abseil Team committed
491
| `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`]. |
Abseil Team's avatar
Abseil Team committed
492
<!-- mdformat on -->
493
494
495

**Notes:**

496
1.  The `MATCHER*` macros cannot be used inside a function or class.
497
2.  The matcher body must be *purely functional* (i.e. it cannot have any side
498
499
    effect, and the result must not depend on anything other than the value
    being matched and the matcher parameters).
500
3.  You can use `PrintToString(x)` to convert a value `x` of any type to a
501
    string.
502

Abseil Team's avatar
Abseil Team committed
503
## Actions {#ActionList}
504
505
506

**Actions** specify what a mock function should do when invoked.

Abseil Team's avatar
Abseil Team committed
507
### Returning a Value
508

Abseil Team's avatar
Abseil Team committed
509
<!-- mdformat off(no multiline tables) -->
Abseil Team's avatar
Abseil Team committed
510
511
512
513
514
515
516
517
518
519
520
|                                   |                                               |
| :-------------------------------- | :-------------------------------------------- |
| `Return()`                        | Return from a `void` mock function.           |
| `Return(value)`                   | Return `value`. If the type of `value` is     different to the mock function's return type, `value` is converted to the latter type <i>at the time the expectation is set</i>, not when the action is executed. |
| `ReturnArg<N>()`                  | Return the `N`-th (0-based) argument.         |
| `ReturnNew<T>(a1, ..., ak)`       | Return `new T(a1, ..., ak)`; a different      object is created each time. |
| `ReturnNull()`                    | Return a null pointer.                        |
| `ReturnPointee(ptr)`              | Return the value pointed to by `ptr`.         |
| `ReturnRef(variable)`             | Return a reference to `variable`.             |
| `ReturnRefOfCopy(value)`          | Return a reference to a copy of `value`; the  copy lives as long as the action. |
| `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. |
Abseil Team's avatar
Abseil Team committed
521
<!-- mdformat on -->
522

Abseil Team's avatar
Abseil Team committed
523
### Side Effects
524

Abseil Team's avatar
Abseil Team committed
525
<!-- mdformat off(no multiline tables) -->
526
|                                    |                                         |
527
| :--------------------------------- | :-------------------------------------- |
Abseil Team's avatar
Abseil Team committed
528
529
530
531
| `Assign(&variable, value)` | Assign `value` to variable. |
| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. |
| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. |
| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. |
Abseil Team's avatar
Abseil Team committed
532
| `SetArgReferee<N>(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. |
Abseil Team's avatar
Abseil Team committed
533
534
535
536
537
538
| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. |
| `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. |
| `SetArrayArgument<N>(first, last)` | Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range. |
| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. |
| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. |
<!-- mdformat on -->
539

Abseil Team's avatar
Abseil Team committed
540
### Using a Function, Functor, or Lambda as an Action
541
542

In the following, by "callable" we mean a free function, `std::function`,
Abseil Team's avatar
Abseil Team committed
543
functor, or lambda.
544

Abseil Team's avatar
Abseil Team committed
545
<!-- mdformat off(no multiline tables) -->
546
|                                     |                                        |
547
| :---------------------------------- | :------------------------------------- |
Abseil Team's avatar
Abseil Team committed
548
549
550
551
552
553
554
| `f` | Invoke f with the arguments passed to the mock function, where f is a callable. |
| `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. |
| `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. |
| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. |
| `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. |
| `InvokeArgument<N>(arg1, arg2, ..., argk)` | Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments. |
<!-- mdformat on -->
555
556
557
558
559
560

The return value of the invoked function is used as the return value of the
action.

When defining a callable to be used with `Invoke*()`, you can declare any unused
parameters as `Unused`:
561

562
```cpp
563
564
565
566
using ::testing::Invoke;
double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); }
...
EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance));
567
568
```

569
570
571
`Invoke(callback)` and `InvokeWithoutArgs(callback)` take ownership of
`callback`, which must be permanent. The type of `callback` must be a base
callback type instead of a derived one, e.g.
572

573
574
575
```cpp
  BlockingClosure* done = new BlockingClosure;
  ... Invoke(done) ...;  // This won't compile!
576

577
578
579
  Closure* done2 = new BlockingClosure;
  ... Invoke(done2) ...;  // This works.
```
580

581
In `InvokeArgument<N>(...)`, if an argument needs to be passed by reference,
ofats's avatar
ofats committed
582
wrap it inside `std::ref()`. For example,
583

584
585
586
```cpp
using ::testing::InvokeArgument;
...
ofats's avatar
ofats committed
587
InvokeArgument<2>(5, string("Hi"), std::ref(foo))
588
```
589

590
591
592
calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by
value, and `foo` by reference.

Abseil Team's avatar
Abseil Team committed
593
### Default Action
594

Abseil Team's avatar
Abseil Team committed
595
<!-- mdformat off(no multiline tables) -->
596
597
| Matcher       | Description                                            |
| :------------ | :----------------------------------------------------- |
Abseil Team's avatar
Abseil Team committed
598
599
| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). |
<!-- mdformat on -->
600
601
602
603

**Note:** due to technical reasons, `DoDefault()` cannot be used inside a
composite action - trying to do so will result in a run-time error.

Abseil Team's avatar
Abseil Team committed
604
### Composite Actions
605

Abseil Team's avatar
Abseil Team committed
606
<!-- mdformat off(no multiline tables) -->
607
|                                |                                             |
608
| :----------------------------- | :------------------------------------------ |
Abseil Team's avatar
Abseil Team committed
609
| `DoAll(a1, a2, ..., an)`       | Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void and will receive a  readonly view of the arguments. |
Abseil Team's avatar
Abseil Team committed
610
611
612
613
614
| `IgnoreResult(a)`              | Perform action `a` and ignore its result. `a` must not return void. |
| `WithArg<N>(a)`                | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. |
| `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. |
| `WithoutArgs(a)`               | Perform action `a` without any arguments. |
<!-- mdformat on -->
615

Abseil Team's avatar
Abseil Team committed
616
### Defining Actions
617

Abseil Team's avatar
Abseil Team committed
618
<!-- mdformat off(no multiline tables) -->
619
|                                    |                                         |
620
| :--------------------------------- | :-------------------------------------- |
Abseil Team's avatar
Abseil Team committed
621
622
623
624
| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. |
| `ACTION_P(Plus, n) { return arg0 + n; }` | Defines an action `Plus(n)` to return the sum of the mock function's argument #0 and `n`. |
| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. |
<!-- mdformat on -->
625
626
627

The `ACTION*` macros cannot be used inside a function or class.

Abseil Team's avatar
Abseil Team committed
628
## Cardinalities {#CardinalityList}
629

630
631
These are used in `Times()` to specify how many times a mock function will be
called:
632

Abseil Team's avatar
Abseil Team committed
633
<!-- mdformat off(no multiline tables) -->
634
|                   |                                                        |
635
636
637
638
| :---------------- | :----------------------------------------------------- |
| `AnyNumber()`     | The function can be called any number of times.        |
| `AtLeast(n)`      | The call is expected at least `n` times.               |
| `AtMost(n)`       | The call is expected at most `n` times.                |
Abseil Team's avatar
Abseil Team committed
639
640
641
| `Between(m, n)`   | The call is expected between `m` and `n` (inclusive) times. |
| `Exactly(n) or n` | The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0. |
<!-- mdformat on -->
642

Abseil Team's avatar
Abseil Team committed
643
## Expectation Order
644

645
646
647
By default, the expectations can be matched in *any* order. If some or all
expectations must be matched in a given order, there are two ways to specify it.
They can be used either independently or together.
648

Abseil Team's avatar
Abseil Team committed
649
### The After Clause {#AfterClause}
650

651
```cpp
652
653
654
655
656
using ::testing::Expectation;
...
Expectation init_x = EXPECT_CALL(foo, InitX());
Expectation init_y = EXPECT_CALL(foo, InitY());
EXPECT_CALL(foo, Bar())
657
     .After(init_x, init_y);
658
659
```

660
661
662
663
664
says that `Bar()` can be called only after both `InitX()` and `InitY()` have
been called.

If you don't know how many pre-requisites an expectation has when you write it,
you can use an `ExpectationSet` to collect them:
665

666
```cpp
667
668
669
670
671
672
673
using ::testing::ExpectationSet;
...
ExpectationSet all_inits;
for (int i = 0; i < element_count; i++) {
  all_inits += EXPECT_CALL(foo, InitElement(i));
}
EXPECT_CALL(foo, Bar())
674
     .After(all_inits);
675
676
```

677
678
679
680
681
says that `Bar()` can be called only after all elements have been initialized
(but we don't care about which elements get initialized before the others).

Modifying an `ExpectationSet` after using it in an `.After()` doesn't affect the
meaning of the `.After()`.
682

Abseil Team's avatar
Abseil Team committed
683
### Sequences {#UsingSequences}
684

685
686
687
688
When you have a long chain of sequential expectations, it's easier to specify
the order using **sequences**, which don't require you to given each expectation
in the chain a different name. *All expected calls* in the same sequence must
occur in the order they are specified.
689

690
```cpp
691
using ::testing::Return;
692
693
694
695
696
697
698
699
700
701
702
703
704
using ::testing::Sequence;
Sequence s1, s2;
...
EXPECT_CALL(foo, Reset())
    .InSequence(s1, s2)
    .WillOnce(Return(true));
EXPECT_CALL(foo, GetSize())
    .InSequence(s1)
    .WillOnce(Return(1));
EXPECT_CALL(foo, Describe(A<const char*>()))
    .InSequence(s2)
    .WillOnce(Return("dummy"));
```
705
706
707

says that `Reset()` must be called before *both* `GetSize()` *and* `Describe()`,
and the latter two can occur in any order.
708
709

To put many expectations in a sequence conveniently:
710

711
```cpp
712
713
using ::testing::InSequence;
{
714
  InSequence seq;
715
716
717
718
719
720
721
722

  EXPECT_CALL(...)...;
  EXPECT_CALL(...)...;
  ...
  EXPECT_CALL(...)...;
}
```

723
724
725
says that all expected calls in the scope of `seq` must occur in strict order.
The name `seq` is irrelevant.

Abseil Team's avatar
Abseil Team committed
726
## Verifying and Resetting a Mock
727
728
729

gMock will verify the expectations on a mock object when it is destructed, or
you can do it earlier:
730

731
```cpp
732
733
734
using ::testing::Mock;
...
// Verifies and removes the expectations on mock_obj;
735
// returns true if and only if successful.
736
737
738
739
Mock::VerifyAndClearExpectations(&mock_obj);
...
// Verifies and removes the expectations on mock_obj;
// also removes the default actions set by ON_CALL();
740
// returns true if and only if successful.
741
742
743
Mock::VerifyAndClear(&mock_obj);
```

744
745
746
You can also tell gMock that a mock object can be leaked and doesn't need to be
verified:

747
```cpp
748
749
750
Mock::AllowLeak(&mock_obj);
```

Abseil Team's avatar
Abseil Team committed
751
## Mock Classes
752
753

gMock defines a convenient mock class template
754

755
```cpp
756
757
class MockFunction<R(A1, ..., An)> {
 public:
758
  MOCK_METHOD(R, Call, (A1, ..., An));
759
760
};
```
761

Abseil Team's avatar
Abseil Team committed
762
763
See this [recipe](gmock_cook_book.md#using-check-points) for one application of
it.
764

Abseil Team's avatar
Abseil Team committed
765
## Flags
766

Abseil Team's avatar
Abseil Team committed
767
<!-- mdformat off(no multiline tables) -->
768
769
| Flag                           | Description                               |
| :----------------------------- | :---------------------------------------- |
Abseil Team's avatar
Abseil Team committed
770
771
772
| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. |
| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. |
<!-- mdformat on -->