Debian Codegraph @

LspCpp/third_party/uri/deps/docs/gmock_cook_book.md

raw
1 # gMock Cookbook
2
3 You can find recipes for using gMock here. If you haven't yet, please read
4 [the dummy guide](gmock_for_dummies.md) first to make sure you understand the
5 basics.
6
7 {: .callout .note}
8 **Note:** gMock lives in the `testing` name space. For readability, it is
9 recommended to write `using ::testing::Foo;` once in your file before using the
10 name `Foo` defined by gMock. We omit such `using` statements in this section for
11 brevity, but you should do it in your own code.
12
13 ## Creating Mock Classes
14
15 Mock classes are defined as normal classes, using the `MOCK_METHOD` macro to
16 generate mocked methods. The macro gets 3 or 4 parameters:
17
18 ```cpp
19 class MyMock {
20 public:
21 MOCK_METHOD(ReturnType, MethodName, (Args...));
22 MOCK_METHOD(ReturnType, MethodName, (Args...), (Specs...));
23 };
24 ```
25
26 The first 3 parameters are simply the method declaration, split into 3 parts.
27 The 4th parameter accepts a closed list of qualifiers, which affect the
28 generated method:
29
30 * **`const`** - Makes the mocked method a `const` method. Required if
31 overriding a `const` method.
32 * **`override`** - Marks the method with `override`. Recommended if overriding
33 a `virtual` method.
34 * **`noexcept`** - Marks the method with `noexcept`. Required if overriding a
35 `noexcept` method.
36 * **`Calltype(...)`** - Sets the call type for the method (e.g. to
37 `STDMETHODCALLTYPE`), useful in Windows.
38 * **`ref(...)`** - Marks the method with the reference qualification
39 specified. Required if overriding a method that has reference
40 qualifications. Eg `ref(&)` or `ref(&&)`.
41
42 ### Dealing with unprotected commas
43
44 Unprotected commas, i.e. commas which are not surrounded by parentheses, prevent
45 `MOCK_METHOD` from parsing its arguments correctly:
46
47 {: .bad}
48 ```cpp
49 class MockFoo {
50 public:
51 MOCK_METHOD(std::pair<bool, int>, GetPair, ()); // Won't compile!
52 MOCK_METHOD(bool, CheckMap, (std::map<int, double>, bool)); // Won't compile!
53 };
54 ```
55
56 Solution 1 - wrap with parentheses:
57
58 {: .good}
59 ```cpp
60 class MockFoo {
61 public:
62 MOCK_METHOD((std::pair<bool, int>), GetPair, ());
63 MOCK_METHOD(bool, CheckMap, ((std::map<int, double>), bool));
64 };
65 ```
66
67 Note that wrapping a return or argument type with parentheses is, in general,
68 invalid C++. `MOCK_METHOD` removes the parentheses.
69
70 Solution 2 - define an alias:
71
72 {: .good}
73 ```cpp
74 class MockFoo {
75 public:
76 using BoolAndInt = std::pair<bool, int>;
77 MOCK_METHOD(BoolAndInt, GetPair, ());
78 using MapIntDouble = std::map<int, double>;
79 MOCK_METHOD(bool, CheckMap, (MapIntDouble, bool));
80 };
81 ```
82
83 ### Mocking Private or Protected Methods
84
85 You must always put a mock method definition (`MOCK_METHOD`) in a `public:`
86 section of the mock class, regardless of the method being mocked being `public`,
87 `protected`, or `private` in the base class. This allows `ON_CALL` and
88 `EXPECT_CALL` to reference the mock function from outside of the mock class.
89 (Yes, C++ allows a subclass to change the access level of a virtual function in
90 the base class.) Example:
91
92 ```cpp
93 class Foo {
94 public:
95 ...
96 virtual bool Transform(Gadget* g) = 0;
97
98 protected:
99 virtual void Resume();
100
101 private:
102 virtual int GetTimeOut();
103 };
104
105 class MockFoo : public Foo {
106 public:
107 ...
108 MOCK_METHOD(bool, Transform, (Gadget* g), (override));
109
110 // The following must be in the public section, even though the
111 // methods are protected or private in the base class.
112 MOCK_METHOD(void, Resume, (), (override));
113 MOCK_METHOD(int, GetTimeOut, (), (override));
114 };
115 ```
116
117 ### Mocking Overloaded Methods
118
119 You can mock overloaded functions as usual. No special attention is required:
120
121 ```cpp
122 class Foo {
123 ...
124
125 // Must be virtual as we'll inherit from Foo.
126 virtual ~Foo();
127
128 // Overloaded on the types and/or numbers of arguments.
129 virtual int Add(Element x);
130 virtual int Add(int times, Element x);
131
132 // Overloaded on the const-ness of this object.
133 virtual Bar& GetBar();
134 virtual const Bar& GetBar() const;
135 };
136
137 class MockFoo : public Foo {
138 ...
139 MOCK_METHOD(int, Add, (Element x), (override));
140 MOCK_METHOD(int, Add, (int times, Element x), (override));
141
142 MOCK_METHOD(Bar&, GetBar, (), (override));
143 MOCK_METHOD(const Bar&, GetBar, (), (const, override));
144 };
145 ```
146
147 {: .callout .note}
148 **Note:** if you don't mock all versions of the overloaded method, the compiler
149 will give you a warning about some methods in the base class being hidden. To
150 fix that, use `using` to bring them in scope:
151
152 ```cpp
153 class MockFoo : public Foo {
154 ...
155 using Foo::Add;
156 MOCK_METHOD(int, Add, (Element x), (override));
157 // We don't want to mock int Add(int times, Element x);
158 ...
159 };
160 ```
161
162 ### Mocking Class Templates
163
164 You can mock class templates just like any class.
165
166 ```cpp
167 template <typename Elem>
168 class StackInterface {
169 ...
170 // Must be virtual as we'll inherit from StackInterface.
171 virtual ~StackInterface();
172
173 virtual int GetSize() const = 0;
174 virtual void Push(const Elem& x) = 0;
175 };
176
177 template <typename Elem>
178 class MockStack : public StackInterface<Elem> {
179 ...
180 MOCK_METHOD(int, GetSize, (), (override));
181 MOCK_METHOD(void, Push, (const Elem& x), (override));
182 };
183 ```
184
185 ### Mocking Non-virtual Methods {#MockingNonVirtualMethods}
186
187 gMock can mock non-virtual functions to be used in Hi-perf dependency injection.
188
189 In this case, instead of sharing a common base class with the real class, your
190 mock class will be *unrelated* to the real class, but contain methods with the
191 same signatures. The syntax for mocking non-virtual methods is the *same* as
192 mocking virtual methods (just don't add `override`):
193
194 ```cpp
195 // A simple packet stream class. None of its members is virtual.
196 class ConcretePacketStream {
197 public:
198 void AppendPacket(Packet* new_packet);
199 const Packet* GetPacket(size_t packet_number) const;
200 size_t NumberOfPackets() const;
201 ...
202 };
203
204 // A mock packet stream class. It inherits from no other, but defines
205 // GetPacket() and NumberOfPackets().
206 class MockPacketStream {
207 public:
208 MOCK_METHOD(const Packet*, GetPacket, (size_t packet_number), (const));
209 MOCK_METHOD(size_t, NumberOfPackets, (), (const));
210 ...
211 };
212 ```
213
214 Note that the mock class doesn't define `AppendPacket()`, unlike the real class.
215 That's fine as long as the test doesn't need to call it.
216
217 Next, you need a way to say that you want to use `ConcretePacketStream` in
218 production code, and use `MockPacketStream` in tests. Since the functions are
219 not virtual and the two classes are unrelated, you must specify your choice at
220 *compile time* (as opposed to run time).
221
222 One way to do it is to templatize your code that needs to use a packet stream.
223 More specifically, you will give your code a template type argument for the type
224 of the packet stream. In production, you will instantiate your template with
225 `ConcretePacketStream` as the type argument. In tests, you will instantiate the
226 same template with `MockPacketStream`. For example, you may write:
227
228 ```cpp
229 template <class PacketStream>
230 void CreateConnection(PacketStream* stream) { ... }
231
232 template <class PacketStream>
233 class PacketReader {
234 public:
235 void ReadPackets(PacketStream* stream, size_t packet_num);
236 };
237 ```
238
239 Then you can use `CreateConnection<ConcretePacketStream>()` and
240 `PacketReader<ConcretePacketStream>` in production code, and use
241 `CreateConnection<MockPacketStream>()` and `PacketReader<MockPacketStream>` in
242 tests.
243
244 ```cpp
245 MockPacketStream mock_stream;
246 EXPECT_CALL(mock_stream, ...)...;
247 .. set more expectations on mock_stream ...
248 PacketReader<MockPacketStream> reader(&mock_stream);
249 ... exercise reader ...
250 ```
251
252 ### Mocking Free Functions
253
254 It is not possible to directly mock a free function (i.e. a C-style function or
255 a static method). If you need to, you can rewrite your code to use an interface
256 (abstract class).
257
258 Instead of calling a free function (say, `OpenFile`) directly, introduce an
259 interface for it and have a concrete subclass that calls the free function:
260
261 ```cpp
262 class FileInterface {
263 public:
264 ...
265 virtual bool Open(const char* path, const char* mode) = 0;
266 };
267
268 class File : public FileInterface {
269 public:
270 ...
271 bool Open(const char* path, const char* mode) override {
272 return OpenFile(path, mode);
273 }
274 };
275 ```
276
277 Your code should talk to `FileInterface` to open a file. Now it's easy to mock
278 out the function.
279
280 This may seem like a lot of hassle, but in practice you often have multiple
281 related functions that you can put in the same interface, so the per-function
282 syntactic overhead will be much lower.
283
284 If you are concerned about the performance overhead incurred by virtual
285 functions, and profiling confirms your concern, you can combine this with the
286 recipe for [mocking non-virtual methods](#MockingNonVirtualMethods).
287
288 ### Old-Style `MOCK_METHODn` Macros
289
290 Before the generic `MOCK_METHOD` macro
291 [was introduced in 2018](https://github.com/google/googletest/commit/c5f08bf91944ce1b19bcf414fa1760e69d20afc2),
292 mocks where created using a family of macros collectively called `MOCK_METHODn`.
293 These macros are still supported, though migration to the new `MOCK_METHOD` is
294 recommended.
295
296 The macros in the `MOCK_METHODn` family differ from `MOCK_METHOD`:
297
298 * The general structure is `MOCK_METHODn(MethodName, ReturnType(Args))`,
299 instead of `MOCK_METHOD(ReturnType, MethodName, (Args))`.
300 * The number `n` must equal the number of arguments.
301 * When mocking a const method, one must use `MOCK_CONST_METHODn`.
302 * When mocking a class template, the macro name must be suffixed with `_T`.
303 * In order to specify the call type, the macro name must be suffixed with
304 `_WITH_CALLTYPE`, and the call type is the first macro argument.
305
306 Old macros and their new equivalents:
307
308 <table>
309 <tr><th colspan=2>Simple</th></tr>
310 <tr>
311 <td>Old</td>
312 <td><code>MOCK_METHOD1(Foo, bool(int))</code></td>
313 </tr>
314 <tr>
315 <td>New</td>
316 <td><code>MOCK_METHOD(bool, Foo, (int))</code></td>
317 </tr>
318
319 <tr><th colspan=2>Const Method</th></tr>
320 <tr>
321 <td>Old</td>
322 <td><code>MOCK_CONST_METHOD1(Foo, bool(int))</code></td>
323 </tr>
324 <tr>
325 <td>New</td>
326 <td><code>MOCK_METHOD(bool, Foo, (int), (const))</code></td>
327 </tr>
328
329 <tr><th colspan=2>Method in a Class Template</th></tr>
330 <tr>
331 <td>Old</td>
332 <td><code>MOCK_METHOD1_T(Foo, bool(int))</code></td>
333 </tr>
334 <tr>
335 <td>New</td>
336 <td><code>MOCK_METHOD(bool, Foo, (int))</code></td>
337 </tr>
338
339 <tr><th colspan=2>Const Method in a Class Template</th></tr>
340 <tr>
341 <td>Old</td>
342 <td><code>MOCK_CONST_METHOD1_T(Foo, bool(int))</code></td>
343 </tr>
344 <tr>
345 <td>New</td>
346 <td><code>MOCK_METHOD(bool, Foo, (int), (const))</code></td>
347 </tr>
348
349 <tr><th colspan=2>Method with Call Type</th></tr>
350 <tr>
351 <td>Old</td>
352 <td><code>MOCK_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
353 </tr>
354 <tr>
355 <td>New</td>
356 <td><code>MOCK_METHOD(bool, Foo, (int), (Calltype(STDMETHODCALLTYPE)))</code></td>
357 </tr>
358
359 <tr><th colspan=2>Const Method with Call Type</th></tr>
360 <tr>
361 <td>Old</td>
362 <td><code>MOCK_CONST_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
363 </tr>
364 <tr>
365 <td>New</td>
366 <td><code>MOCK_METHOD(bool, Foo, (int), (const, Calltype(STDMETHODCALLTYPE)))</code></td>
367 </tr>
368
369 <tr><th colspan=2>Method with Call Type in a Class Template</th></tr>
370 <tr>
371 <td>Old</td>
372 <td><code>MOCK_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
373 </tr>
374 <tr>
375 <td>New</td>
376 <td><code>MOCK_METHOD(bool, Foo, (int), (Calltype(STDMETHODCALLTYPE)))</code></td>
377 </tr>
378
379 <tr><th colspan=2>Const Method with Call Type in a Class Template</th></tr>
380 <tr>
381 <td>Old</td>
382 <td><code>MOCK_CONST_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
383 </tr>
384 <tr>
385 <td>New</td>
386 <td><code>MOCK_METHOD(bool, Foo, (int), (const, Calltype(STDMETHODCALLTYPE)))</code></td>
387 </tr>
388 </table>
389
390 ### The Nice, the Strict, and the Naggy {#NiceStrictNaggy}
391
392 If a mock method has no `EXPECT_CALL` spec but is called, we say that it's an
393 "uninteresting call", and the default action (which can be specified using
394 `ON_CALL()`) of the method will be taken. Currently, an uninteresting call will
395 also by default cause gMock to print a warning. (In the future, we might remove
396 this warning by default.)
397
398 However, sometimes you may want to ignore these uninteresting calls, and
399 sometimes you may want to treat them as errors. gMock lets you make the decision
400 on a per-mock-object basis.
401
402 Suppose your test uses a mock class `MockFoo`:
403
404 ```cpp
405 TEST(...) {
406 MockFoo mock_foo;
407 EXPECT_CALL(mock_foo, DoThis());
408 ... code that uses mock_foo ...
409 }
410 ```
411
412 If a method of `mock_foo` other than `DoThis()` is called, you will get a
413 warning. However, if you rewrite your test to use `NiceMock<MockFoo>` instead,
414 you can suppress the warning:
415
416 ```cpp
417 using ::testing::NiceMock;
418
419 TEST(...) {
420 NiceMock<MockFoo> mock_foo;
421 EXPECT_CALL(mock_foo, DoThis());
422 ... code that uses mock_foo ...
423 }
424 ```
425
426 `NiceMock<MockFoo>` is a subclass of `MockFoo`, so it can be used wherever
427 `MockFoo` is accepted.
428
429 It also works if `MockFoo`'s constructor takes some arguments, as
430 `NiceMock<MockFoo>` "inherits" `MockFoo`'s constructors:
431
432 ```cpp
433 using ::testing::NiceMock;
434
435 TEST(...) {
436 NiceMock<MockFoo> mock_foo(5, "hi"); // Calls MockFoo(5, "hi").
437 EXPECT_CALL(mock_foo, DoThis());
438 ... code that uses mock_foo ...
439 }
440 ```
441
442 The usage of `StrictMock` is similar, except that it makes all uninteresting
443 calls failures:
444
445 ```cpp
446 using ::testing::StrictMock;
447
448 TEST(...) {
449 StrictMock<MockFoo> mock_foo;
450 EXPECT_CALL(mock_foo, DoThis());
451 ... code that uses mock_foo ...
452
453 // The test will fail if a method of mock_foo other than DoThis()
454 // is called.
455 }
456 ```
457
458 {: .callout .note}
459 NOTE: `NiceMock` and `StrictMock` only affects *uninteresting* calls (calls of
460 *methods* with no expectations); they do not affect *unexpected* calls (calls of
461 methods with expectations, but they don't match). See
462 [Understanding Uninteresting vs Unexpected Calls](#uninteresting-vs-unexpected).
463
464 There are some caveats though (sadly they are side effects of C++'s
465 limitations):
466
467 1. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` only work for mock methods
468 defined using the `MOCK_METHOD` macro **directly** in the `MockFoo` class.
469 If a mock method is defined in a **base class** of `MockFoo`, the "nice" or
470 "strict" modifier may not affect it, depending on the compiler. In
471 particular, nesting `NiceMock` and `StrictMock` (e.g.
472 `NiceMock<StrictMock<MockFoo> >`) is **not** supported.
473 2. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` may not work correctly if the
474 destructor of `MockFoo` is not virtual. We would like to fix this, but it
475 requires cleaning up existing tests.
476
477 Finally, you should be **very cautious** about when to use naggy or strict
478 mocks, as they tend to make tests more brittle and harder to maintain. When you
479 refactor your code without changing its externally visible behavior, ideally you
480 shouldn't need to update any tests. If your code interacts with a naggy mock,
481 however, you may start to get spammed with warnings as the result of your
482 change. Worse, if your code interacts with a strict mock, your tests may start
483 to fail and you'll be forced to fix them. Our general recommendation is to use
484 nice mocks (not yet the default) most of the time, use naggy mocks (the current
485 default) when developing or debugging tests, and use strict mocks only as the
486 last resort.
487
488 ### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces}
489
490 Sometimes a method has a long list of arguments that is mostly uninteresting.
491 For example:
492
493 ```cpp
494 class LogSink {
495 public:
496 ...
497 virtual void send(LogSeverity severity, const char* full_filename,
498 const char* base_filename, int line,
499 const struct tm* tm_time,
500 const char* message, size_t message_len) = 0;
501 };
502 ```
503
504 This method's argument list is lengthy and hard to work with (the `message`
505 argument is not even 0-terminated). If we mock it as is, using the mock will be
506 awkward. If, however, we try to simplify this interface, we'll need to fix all
507 clients depending on it, which is often infeasible.
508
509 The trick is to redispatch the method in the mock class:
510
511 ```cpp
512 class ScopedMockLog : public LogSink {
513 public:
514 ...
515 void send(LogSeverity severity, const char* full_filename,
516 const char* base_filename, int line, const tm* tm_time,
517 const char* message, size_t message_len) override {
518 // We are only interested in the log severity, full file name, and
519 // log message.
520 Log(severity, full_filename, std::string(message, message_len));
521 }
522
523 // Implements the mock method:
524 //
525 // void Log(LogSeverity severity,
526 // const string& file_path,
527 // const string& message);
528 MOCK_METHOD(void, Log,
529 (LogSeverity severity, const string& file_path,
530 const string& message));
531 };
532 ```
533
534 By defining a new mock method with a trimmed argument list, we make the mock
535 class more user-friendly.
536
537 This technique may also be applied to make overloaded methods more amenable to
538 mocking. For example, when overloads have been used to implement default
539 arguments:
540
541 ```cpp
542 class MockTurtleFactory : public TurtleFactory {
543 public:
544 Turtle* MakeTurtle(int length, int weight) override { ... }
545 Turtle* MakeTurtle(int length, int weight, int speed) override { ... }
546
547 // the above methods delegate to this one:
548 MOCK_METHOD(Turtle*, DoMakeTurtle, ());
549 };
550 ```
551
552 This allows tests that don't care which overload was invoked to avoid specifying
553 argument matchers:
554
555 ```cpp
556 ON_CALL(factory, DoMakeTurtle)
557 .WillByDefault(Return(MakeMockTurtle()));
558 ```
559
560 ### Alternative to Mocking Concrete Classes
561
562 Often you may find yourself using classes that don't implement interfaces. In
563 order to test your code that uses such a class (let's call it `Concrete`), you
564 may be tempted to make the methods of `Concrete` virtual and then mock it.
565
566 Try not to do that.
567
568 Making a non-virtual function virtual is a big decision. It creates an extension
569 point where subclasses can tweak your class' behavior. This weakens your control
570 on the class because now it's harder to maintain the class invariants. You
571 should make a function virtual only when there is a valid reason for a subclass
572 to override it.
573
574 Mocking concrete classes directly is problematic as it creates a tight coupling
575 between the class and the tests - any small change in the class may invalidate
576 your tests and make test maintenance a pain.
577
578 To avoid such problems, many programmers have been practicing "coding to
579 interfaces": instead of talking to the `Concrete` class, your code would define
580 an interface and talk to it. Then you implement that interface as an adaptor on
581 top of `Concrete`. In tests, you can easily mock that interface to observe how
582 your code is doing.
583
584 This technique incurs some overhead:
585
586 * You pay the cost of virtual function calls (usually not a problem).
587 * There is more abstraction for the programmers to learn.
588
589 However, it can also bring significant benefits in addition to better
590 testability:
591
592 * `Concrete`'s API may not fit your problem domain very well, as you may not
593 be the only client it tries to serve. By designing your own interface, you
594 have a chance to tailor it to your need - you may add higher-level
595 functionalities, rename stuff, etc instead of just trimming the class. This
596 allows you to write your code (user of the interface) in a more natural way,
597 which means it will be more readable, more maintainable, and you'll be more
598 productive.
599 * If `Concrete`'s implementation ever has to change, you don't have to rewrite
600 everywhere it is used. Instead, you can absorb the change in your
601 implementation of the interface, and your other code and tests will be
602 insulated from this change.
603
604 Some people worry that if everyone is practicing this technique, they will end
605 up writing lots of redundant code. This concern is totally understandable.
606 However, there are two reasons why it may not be the case:
607
608 * Different projects may need to use `Concrete` in different ways, so the best
609 interfaces for them will be different. Therefore, each of them will have its
610 own domain-specific interface on top of `Concrete`, and they will not be the
611 same code.
612 * If enough projects want to use the same interface, they can always share it,
613 just like they have been sharing `Concrete`. You can check in the interface
614 and the adaptor somewhere near `Concrete` (perhaps in a `contrib`
615 sub-directory) and let many projects use it.
616
617 You need to weigh the pros and cons carefully for your particular problem, but
618 I'd like to assure you that the Java community has been practicing this for a
619 long time and it's a proven effective technique applicable in a wide variety of
620 situations. :-)
621
622 ### Delegating Calls to a Fake {#DelegatingToFake}
623
624 Some times you have a non-trivial fake implementation of an interface. For
625 example:
626
627 ```cpp
628 class Foo {
629 public:
630 virtual ~Foo() {}
631 virtual char DoThis(int n) = 0;
632 virtual void DoThat(const char* s, int* p) = 0;
633 };
634
635 class FakeFoo : public Foo {
636 public:
637 char DoThis(int n) override {
638 return (n > 0) ? '+' :
639 (n < 0) ? '-' : '0';
640 }
641
642 void DoThat(const char* s, int* p) override {
643 *p = strlen(s);
644 }
645 };
646 ```
647
648 Now you want to mock this interface such that you can set expectations on it.
649 However, you also want to use `FakeFoo` for the default behavior, as duplicating
650 it in the mock object is, well, a lot of work.
651
652 When you define the mock class using gMock, you can have it delegate its default
653 action to a fake class you already have, using this pattern:
654
655 ```cpp
656 class MockFoo : public Foo {
657 public:
658 // Normal mock method definitions using gMock.
659 MOCK_METHOD(char, DoThis, (int n), (override));
660 MOCK_METHOD(void, DoThat, (const char* s, int* p), (override));
661
662 // Delegates the default actions of the methods to a FakeFoo object.
663 // This must be called *before* the custom ON_CALL() statements.
664 void DelegateToFake() {
665 ON_CALL(*this, DoThis).WillByDefault([this](int n) {
666 return fake_.DoThis(n);
667 });
668 ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) {
669 fake_.DoThat(s, p);
670 });
671 }
672
673 private:
674 FakeFoo fake_; // Keeps an instance of the fake in the mock.
675 };
676 ```
677
678 With that, you can use `MockFoo` in your tests as usual. Just remember that if
679 you don't explicitly set an action in an `ON_CALL()` or `EXPECT_CALL()`, the
680 fake will be called upon to do it.:
681
682 ```cpp
683 using ::testing::_;
684
685 TEST(AbcTest, Xyz) {
686 MockFoo foo;
687
688 foo.DelegateToFake(); // Enables the fake for delegation.
689
690 // Put your ON_CALL(foo, ...)s here, if any.
691
692 // No action specified, meaning to use the default action.
693 EXPECT_CALL(foo, DoThis(5));
694 EXPECT_CALL(foo, DoThat(_, _));
695
696 int n = 0;
697 EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked.
698 foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked.
699 EXPECT_EQ(2, n);
700 }
701 ```
702
703 **Some tips:**
704
705 * If you want, you can still override the default action by providing your own
706 `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`.
707 * In `DelegateToFake()`, you only need to delegate the methods whose fake
708 implementation you intend to use.
709
710 * The general technique discussed here works for overloaded methods, but
711 you'll need to tell the compiler which version you mean. To disambiguate a
712 mock function (the one you specify inside the parentheses of `ON_CALL()`),
713 use [this technique](#SelectOverload); to disambiguate a fake function (the
714 one you place inside `Invoke()`), use a `static_cast` to specify the
715 function's type. For instance, if class `Foo` has methods `char DoThis(int
716 n)` and `bool DoThis(double x) const`, and you want to invoke the latter,
717 you need to write `Invoke(&fake_, static_cast<bool (FakeFoo::*)(double)
718 const>(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)`
719 (The strange-looking thing inside the angled brackets of `static_cast` is
720 the type of a function pointer to the second `DoThis()` method.).
721
722 * Having to mix a mock and a fake is often a sign of something gone wrong.
723 Perhaps you haven't got used to the interaction-based way of testing yet. Or
724 perhaps your interface is taking on too many roles and should be split up.
725 Therefore, **don't abuse this**. We would only recommend to do it as an
726 intermediate step when you are refactoring your code.
727
728 Regarding the tip on mixing a mock and a fake, here's an example on why it may
729 be a bad sign: Suppose you have a class `System` for low-level system
730 operations. In particular, it does file and I/O operations. And suppose you want
731 to test how your code uses `System` to do I/O, and you just want the file
732 operations to work normally. If you mock out the entire `System` class, you'll
733 have to provide a fake implementation for the file operation part, which
734 suggests that `System` is taking on too many roles.
735
736 Instead, you can define a `FileOps` interface and an `IOOps` interface and split
737 `System`'s functionalities into the two. Then you can mock `IOOps` without
738 mocking `FileOps`.
739
740 ### Delegating Calls to a Real Object
741
742 When using testing doubles (mocks, fakes, stubs, and etc), sometimes their
743 behaviors will differ from those of the real objects. This difference could be
744 either intentional (as in simulating an error such that you can test the error
745 handling code) or unintentional. If your mocks have different behaviors than the
746 real objects by mistake, you could end up with code that passes the tests but
747 fails in production.
748
749 You can use the *delegating-to-real* technique to ensure that your mock has the
750 same behavior as the real object while retaining the ability to validate calls.
751 This technique is very similar to the [delegating-to-fake](#DelegatingToFake)
752 technique, the difference being that we use a real object instead of a fake.
753 Here's an example:
754
755 ```cpp
756 using ::testing::AtLeast;
757
758 class MockFoo : public Foo {
759 public:
760 MockFoo() {
761 // By default, all calls are delegated to the real object.
762 ON_CALL(*this, DoThis).WillByDefault([this](int n) {
763 return real_.DoThis(n);
764 });
765 ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) {
766 real_.DoThat(s, p);
767 });
768 ...
769 }
770 MOCK_METHOD(char, DoThis, ...);
771 MOCK_METHOD(void, DoThat, ...);
772 ...
773 private:
774 Foo real_;
775 };
776
777 ...
778 MockFoo mock;
779 EXPECT_CALL(mock, DoThis())
780 .Times(3);
781 EXPECT_CALL(mock, DoThat("Hi"))
782 .Times(AtLeast(1));
783 ... use mock in test ...
784 ```
785
786 With this, gMock will verify that your code made the right calls (with the right
787 arguments, in the right order, called the right number of times, etc), and a
788 real object will answer the calls (so the behavior will be the same as in
789 production). This gives you the best of both worlds.
790
791 ### Delegating Calls to a Parent Class
792
793 Ideally, you should code to interfaces, whose methods are all pure virtual. In
794 reality, sometimes you do need to mock a virtual method that is not pure (i.e,
795 it already has an implementation). For example:
796
797 ```cpp
798 class Foo {
799 public:
800 virtual ~Foo();
801
802 virtual void Pure(int n) = 0;
803 virtual int Concrete(const char* str) { ... }
804 };
805
806 class MockFoo : public Foo {
807 public:
808 // Mocking a pure method.
809 MOCK_METHOD(void, Pure, (int n), (override));
810 // Mocking a concrete method. Foo::Concrete() is shadowed.
811 MOCK_METHOD(int, Concrete, (const char* str), (override));
812 };
813 ```
814
815 Sometimes you may want to call `Foo::Concrete()` instead of
816 `MockFoo::Concrete()`. Perhaps you want to do it as part of a stub action, or
817 perhaps your test doesn't need to mock `Concrete()` at all (but it would be
818 oh-so painful to have to define a new mock class whenever you don't need to mock
819 one of its methods).
820
821 You can call `Foo::Concrete()` inside an action by:
822
823 ```cpp
824 ...
825 EXPECT_CALL(foo, Concrete).WillOnce([&foo](const char* str) {
826 return foo.Foo::Concrete(str);
827 });
828 ```
829
830 or tell the mock object that you don't want to mock `Concrete()`:
831
832 ```cpp
833 ...
834 ON_CALL(foo, Concrete).WillByDefault([&foo](const char* str) {
835 return foo.Foo::Concrete(str);
836 });
837 ```
838
839 (Why don't we just write `{ return foo.Concrete(str); }`? If you do that,
840 `MockFoo::Concrete()` will be called (and cause an infinite recursion) since
841 `Foo::Concrete()` is virtual. That's just how C++ works.)
842
843 ## Using Matchers
844
845 ### Matching Argument Values Exactly
846
847 You can specify exactly which arguments a mock method is expecting:
848
849 ```cpp
850 using ::testing::Return;
851 ...
852 EXPECT_CALL(foo, DoThis(5))
853 .WillOnce(Return('a'));
854 EXPECT_CALL(foo, DoThat("Hello", bar));
855 ```
856
857 ### Using Simple Matchers
858
859 You can use matchers to match arguments that have a certain property:
860
861 ```cpp
862 using ::testing::NotNull;
863 using ::testing::Return;
864 ...
865 EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5.
866 .WillOnce(Return('a'));
867 EXPECT_CALL(foo, DoThat("Hello", NotNull()));
868 // The second argument must not be NULL.
869 ```
870
871 A frequently used matcher is `_`, which matches anything:
872
873 ```cpp
874 EXPECT_CALL(foo, DoThat(_, NotNull()));
875 ```
876
877 ### Combining Matchers {#CombiningMatchers}
878
879 You can build complex matchers from existing ones using `AllOf()`,
880 `AllOfArray()`, `AnyOf()`, `AnyOfArray()` and `Not()`:
881
882 ```cpp
883 using ::testing::AllOf;
884 using ::testing::Gt;
885 using ::testing::HasSubstr;
886 using ::testing::Ne;
887 using ::testing::Not;
888 ...
889 // The argument must be > 5 and != 10.
890 EXPECT_CALL(foo, DoThis(AllOf(Gt(5),
891 Ne(10))));
892
893 // The first argument must not contain sub-string "blah".
894 EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")),
895 NULL));
896 ```
897
898 Matchers are function objects, and parametrized matchers can be composed just
899 like any other function. However because their types can be long and rarely
900 provide meaningful information, it can be easier to express them with C++14
901 generic lambdas to avoid specifying types. For example,
902
903 ```cpp
904 using ::testing::Contains;
905 using ::testing::Property;
906
907 inline constexpr auto HasFoo = [](const auto& f) {
908 return Property(&MyClass::foo, Contains(f));
909 };
910 ...
911 EXPECT_THAT(x, HasFoo("blah"));
912 ```
913
914 ### Casting Matchers {#SafeMatcherCast}
915
916 gMock matchers are statically typed, meaning that the compiler can catch your
917 mistake if you use a matcher of the wrong type (for example, if you use `Eq(5)`
918 to match a `string` argument). Good for you!
919
920 Sometimes, however, you know what you're doing and want the compiler to give you
921 some slack. One example is that you have a matcher for `long` and the argument
922 you want to match is `int`. While the two types aren't exactly the same, there
923 is nothing really wrong with using a `Matcher<long>` to match an `int` - after
924 all, we can first convert the `int` argument to a `long` losslessly before
925 giving it to the matcher.
926
927 To support this need, gMock gives you the `SafeMatcherCast<T>(m)` function. It
928 casts a matcher `m` to type `Matcher<T>`. To ensure safety, gMock checks that
929 (let `U` be the type `m` accepts :
930
931 1. Type `T` can be *implicitly* cast to type `U`;
932 2. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and
933 floating-point numbers), the conversion from `T` to `U` is not lossy (in
934 other words, any value representable by `T` can also be represented by `U`);
935 and
936 3. When `U` is a reference, `T` must also be a reference (as the underlying
937 matcher may be interested in the address of the `U` value).
938
939 The code won't compile if any of these conditions isn't met.
940
941 Here's one example:
942
943 ```cpp
944 using ::testing::SafeMatcherCast;
945
946 // A base class and a child class.
947 class Base { ... };
948 class Derived : public Base { ... };
949
950 class MockFoo : public Foo {
951 public:
952 MOCK_METHOD(void, DoThis, (Derived* derived), (override));
953 };
954
955 ...
956 MockFoo foo;
957 // m is a Matcher<Base*> we got from somewhere.
958 EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m)));
959 ```
960
961 If you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar function
962 `MatcherCast<T>(m)`. The difference is that `MatcherCast` works as long as you
963 can `static_cast` type `T` to type `U`.
964
965 `MatcherCast` essentially lets you bypass C++'s type system (`static_cast` isn't
966 always safe as it could throw away information, for example), so be careful not
967 to misuse/abuse it.
968
969 ### Selecting Between Overloaded Functions {#SelectOverload}
970
971 If you expect an overloaded function to be called, the compiler may need some
972 help on which overloaded version it is.
973
974 To disambiguate functions overloaded on the const-ness of this object, use the
975 `Const()` argument wrapper.
976
977 ```cpp
978 using ::testing::ReturnRef;
979
980 class MockFoo : public Foo {
981 ...
982 MOCK_METHOD(Bar&, GetBar, (), (override));
983 MOCK_METHOD(const Bar&, GetBar, (), (const, override));
984 };
985
986 ...
987 MockFoo foo;
988 Bar bar1, bar2;
989 EXPECT_CALL(foo, GetBar()) // The non-const GetBar().
990 .WillOnce(ReturnRef(bar1));
991 EXPECT_CALL(Const(foo), GetBar()) // The const GetBar().
992 .WillOnce(ReturnRef(bar2));
993 ```
994
995 (`Const()` is defined by gMock and returns a `const` reference to its argument.)
996
997 To disambiguate overloaded functions with the same number of arguments but
998 different argument types, you may need to specify the exact type of a matcher,
999 either by wrapping your matcher in `Matcher<type>()`, or using a matcher whose
1000 type is fixed (`TypedEq<type>`, `An<type>()`, etc):
1001
1002 ```cpp
1003 using ::testing::An;
1004 using ::testing::Matcher;
1005 using ::testing::TypedEq;
1006
1007 class MockPrinter : public Printer {
1008 public:
1009 MOCK_METHOD(void, Print, (int n), (override));
1010 MOCK_METHOD(void, Print, (char c), (override));
1011 };
1012
1013 TEST(PrinterTest, Print) {
1014 MockPrinter printer;
1015
1016 EXPECT_CALL(printer, Print(An<int>())); // void Print(int);
1017 EXPECT_CALL(printer, Print(Matcher<int>(Lt(5)))); // void Print(int);
1018 EXPECT_CALL(printer, Print(TypedEq<char>('a'))); // void Print(char);
1019
1020 printer.Print(3);
1021 printer.Print(6);
1022 printer.Print('a');
1023 }
1024 ```
1025
1026 ### Performing Different Actions Based on the Arguments
1027
1028 When a mock method is called, the *last* matching expectation that's still
1029 active will be selected (think "newer overrides older"). So, you can make a
1030 method do different things depending on its argument values like this:
1031
1032 ```cpp
1033 using ::testing::_;
1034 using ::testing::Lt;
1035 using ::testing::Return;
1036 ...
1037 // The default case.
1038 EXPECT_CALL(foo, DoThis(_))
1039 .WillRepeatedly(Return('b'));
1040 // The more specific case.
1041 EXPECT_CALL(foo, DoThis(Lt(5)))
1042 .WillRepeatedly(Return('a'));
1043 ```
1044
1045 Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will be
1046 returned; otherwise `'b'` will be returned.
1047
1048 ### Matching Multiple Arguments as a Whole
1049
1050 Sometimes it's not enough to match the arguments individually. For example, we
1051 may want to say that the first argument must be less than the second argument.
1052 The `With()` clause allows us to match all arguments of a mock function as a
1053 whole. For example,
1054
1055 ```cpp
1056 using ::testing::_;
1057 using ::testing::Ne;
1058 using ::testing::Lt;
1059 ...
1060 EXPECT_CALL(foo, InRange(Ne(0), _))
1061 .With(Lt());
1062 ```
1063
1064 says that the first argument of `InRange()` must not be 0, and must be less than
1065 the second argument.
1066
1067 The expression inside `With()` must be a matcher of type `Matcher<std::tuple<A1,
1068 ..., An>>`, where `A1`, ..., `An` are the types of the function arguments.
1069
1070 You can also write `AllArgs(m)` instead of `m` inside `.With()`. The two forms
1071 are equivalent, but `.With(AllArgs(Lt()))` is more readable than `.With(Lt())`.
1072
1073 You can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments (as a
1074 tuple) against `m`. For example,
1075
1076 ```cpp
1077 using ::testing::_;
1078 using ::testing::AllOf;
1079 using ::testing::Args;
1080 using ::testing::Lt;
1081 ...
1082 EXPECT_CALL(foo, Blah)
1083 .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt())));
1084 ```
1085
1086 says that `Blah` will be called with arguments `x`, `y`, and `z` where `x < y <
1087 z`. Note that in this example, it wasn't necessary to specify the positional
1088 matchers.
1089
1090 As a convenience and example, gMock provides some matchers for 2-tuples,
1091 including the `Lt()` matcher above. See
1092 [Multi-argument Matchers](reference/matchers.md#MultiArgMatchers) for the
1093 complete list.
1094
1095 Note that if you want to pass the arguments to a predicate of your own (e.g.
1096 `.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be written to
1097 take a `std::tuple` as its argument; gMock will pass the `n` selected arguments
1098 as *one* single tuple to the predicate.
1099
1100 ### Using Matchers as Predicates
1101
1102 Have you noticed that a matcher is just a fancy predicate that also knows how to
1103 describe itself? Many existing algorithms take predicates as arguments (e.g.
1104 those defined in STL's `<algorithm>` header), and it would be a shame if gMock
1105 matchers were not allowed to participate.
1106
1107 Luckily, you can use a matcher where a unary predicate functor is expected by
1108 wrapping it inside the `Matches()` function. For example,
1109
1110 ```cpp
1111 #include <algorithm>
1112 #include <vector>
1113
1114 using ::testing::Matches;
1115 using ::testing::Ge;
1116
1117 vector<int> v;
1118 ...
1119 // How many elements in v are >= 10?
1120 const int count = count_if(v.begin(), v.end(), Matches(Ge(10)));
1121 ```
1122
1123 Since you can build complex matchers from simpler ones easily using gMock, this
1124 gives you a way to conveniently construct composite predicates (doing the same
1125 using STL's `<functional>` header is just painful). For example, here's a
1126 predicate that's satisfied by any number that is >= 0, <= 100, and != 50:
1127
1128 ```cpp
1129 using testing::AllOf;
1130 using testing::Ge;
1131 using testing::Le;
1132 using testing::Matches;
1133 using testing::Ne;
1134 ...
1135 Matches(AllOf(Ge(0), Le(100), Ne(50)))
1136 ```
1137
1138 ### Using Matchers in googletest Assertions
1139
1140 See [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) in the Assertions
1141 Reference.
1142
1143 ### Using Predicates as Matchers
1144
1145 gMock provides a set of built-in matchers for matching arguments with expected
1146 values—see the [Matchers Reference](reference/matchers.md) for more information.
1147 In case you find the built-in set lacking, you can use an arbitrary unary
1148 predicate function or functor as a matcher - as long as the predicate accepts a
1149 value of the type you want. You do this by wrapping the predicate inside the
1150 `Truly()` function, for example:
1151
1152 ```cpp
1153 using ::testing::Truly;
1154
1155 int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; }
1156 ...
1157 // Bar() must be called with an even number.
1158 EXPECT_CALL(foo, Bar(Truly(IsEven)));
1159 ```
1160
1161 Note that the predicate function / functor doesn't have to return `bool`. It
1162 works as long as the return value can be used as the condition in in statement
1163 `if (condition) ...`.
1164
1165 ### Matching Arguments that Are Not Copyable
1166
1167 When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of
1168 `bar`. When `Foo()` is called later, gMock compares the argument to `Foo()` with
1169 the saved copy of `bar`. This way, you don't need to worry about `bar` being
1170 modified or destroyed after the `EXPECT_CALL()` is executed. The same is true
1171 when you use matchers like `Eq(bar)`, `Le(bar)`, and so on.
1172
1173 But what if `bar` cannot be copied (i.e. has no copy constructor)? You could
1174 define your own matcher function or callback and use it with `Truly()`, as the
1175 previous couple of recipes have shown. Or, you may be able to get away from it
1176 if you can guarantee that `bar` won't be changed after the `EXPECT_CALL()` is
1177 executed. Just tell gMock that it should save a reference to `bar`, instead of a
1178 copy of it. Here's how:
1179
1180 ```cpp
1181 using ::testing::Eq;
1182 using ::testing::Lt;
1183 ...
1184 // Expects that Foo()'s argument == bar.
1185 EXPECT_CALL(mock_obj, Foo(Eq(std::ref(bar))));
1186
1187 // Expects that Foo()'s argument < bar.
1188 EXPECT_CALL(mock_obj, Foo(Lt(std::ref(bar))));
1189 ```
1190
1191 Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the
1192 result is undefined.
1193
1194 ### Validating a Member of an Object
1195
1196 Often a mock function takes a reference to object as an argument. When matching
1197 the argument, you may not want to compare the entire object against a fixed
1198 object, as that may be over-specification. Instead, you may need to validate a
1199 certain member variable or the result of a certain getter method of the object.
1200 You can do this with `Field()` and `Property()`. More specifically,
1201
1202 ```cpp
1203 Field(&Foo::bar, m)
1204 ```
1205
1206 is a matcher that matches a `Foo` object whose `bar` member variable satisfies
1207 matcher `m`.
1208
1209 ```cpp
1210 Property(&Foo::baz, m)
1211 ```
1212
1213 is a matcher that matches a `Foo` object whose `baz()` method returns a value
1214 that satisfies matcher `m`.
1215
1216 For example:
1217
1218 | Expression | Description |
1219 | :--------------------------- | :--------------------------------------- |
1220 | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. |
1221 | `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. |
1222
1223 Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument
1224 and be declared as `const`. Don't use `Property()` against member functions that
1225 you do not own, because taking addresses of functions is fragile and generally
1226 not part of the contract of the function.
1227
1228 `Field()` and `Property()` can also match plain pointers to objects. For
1229 instance,
1230
1231 ```cpp
1232 using ::testing::Field;
1233 using ::testing::Ge;
1234 ...
1235 Field(&Foo::number, Ge(3))
1236 ```
1237
1238 matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, the match
1239 will always fail regardless of the inner matcher.
1240
1241 What if you want to validate more than one members at the same time? Remember
1242 that there are [`AllOf()` and `AllOfArray()`](#CombiningMatchers).
1243
1244 Finally `Field()` and `Property()` provide overloads that take the field or
1245 property names as the first argument to include it in the error message. This
1246 can be useful when creating combined matchers.
1247
1248 ```cpp
1249 using ::testing::AllOf;
1250 using ::testing::Field;
1251 using ::testing::Matcher;
1252 using ::testing::SafeMatcherCast;
1253
1254 Matcher<Foo> IsFoo(const Foo& foo) {
1255 return AllOf(Field("some_field", &Foo::some_field, foo.some_field),
1256 Field("other_field", &Foo::other_field, foo.other_field),
1257 Field("last_field", &Foo::last_field, foo.last_field));
1258 }
1259 ```
1260
1261 ### Validating the Value Pointed to by a Pointer Argument
1262
1263 C++ functions often take pointers as arguments. You can use matchers like
1264 `IsNull()`, `NotNull()`, and other comparison matchers to match a pointer, but
1265 what if you want to make sure the value *pointed to* by the pointer, instead of
1266 the pointer itself, has a certain property? Well, you can use the `Pointee(m)`
1267 matcher.
1268
1269 `Pointee(m)` matches a pointer if and only if `m` matches the value the pointer
1270 points to. For example:
1271
1272 ```cpp
1273 using ::testing::Ge;
1274 using ::testing::Pointee;
1275 ...
1276 EXPECT_CALL(foo, Bar(Pointee(Ge(3))));
1277 ```
1278
1279 expects `foo.Bar()` to be called with a pointer that points to a value greater
1280 than or equal to 3.
1281
1282 One nice thing about `Pointee()` is that it treats a `NULL` pointer as a match
1283 failure, so you can write `Pointee(m)` instead of
1284
1285 ```cpp
1286 using ::testing::AllOf;
1287 using ::testing::NotNull;
1288 using ::testing::Pointee;
1289 ...
1290 AllOf(NotNull(), Pointee(m))
1291 ```
1292
1293 without worrying that a `NULL` pointer will crash your test.
1294
1295 Also, did we tell you that `Pointee()` works with both raw pointers **and**
1296 smart pointers (`std::unique_ptr`, `std::shared_ptr`, etc)?
1297
1298 What if you have a pointer to pointer? You guessed it - you can use nested
1299 `Pointee()` to probe deeper inside the value. For example,
1300 `Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer that points
1301 to a number less than 3 (what a mouthful...).
1302
1303 ### Testing a Certain Property of an Object
1304
1305 Sometimes you want to specify that an object argument has a certain property,
1306 but there is no existing matcher that does this. If you want good error
1307 messages, you should [define a matcher](#NewMatchers). If you want to do it
1308 quick and dirty, you could get away with writing an ordinary function.
1309
1310 Let's say you have a mock function that takes an object of type `Foo`, which has
1311 an `int bar()` method and an `int baz()` method, and you want to constrain that
1312 the argument's `bar()` value plus its `baz()` value is a given number. Here's
1313 how you can define a matcher to do it:
1314
1315 ```cpp
1316 using ::testing::Matcher;
1317
1318 class BarPlusBazEqMatcher {
1319 public:
1320 explicit BarPlusBazEqMatcher(int expected_sum)
1321 : expected_sum_(expected_sum) {}
1322
1323 bool MatchAndExplain(const Foo& foo,
1324 std::ostream* /* listener */) const {
1325 return (foo.bar() + foo.baz()) == expected_sum_;
1326 }
1327
1328 void DescribeTo(std::ostream& os) const {
1329 os << "bar() + baz() equals " << expected_sum_;
1330 }
1331
1332 void DescribeNegationTo(std::ostream& os) const {
1333 os << "bar() + baz() does not equal " << expected_sum_;
1334 }
1335 private:
1336 const int expected_sum_;
1337 };
1338
1339 Matcher<const Foo&> BarPlusBazEq(int expected_sum) {
1340 return BarPlusBazEqMatcher(expected_sum);
1341 }
1342
1343 ...
1344 EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...;
1345 ```
1346
1347 ### Matching Containers
1348
1349 Sometimes an STL container (e.g. list, vector, map, ...) is passed to a mock
1350 function and you may want to validate it. Since most STL containers support the
1351 `==` operator, you can write `Eq(expected_container)` or simply
1352 `expected_container` to match a container exactly.
1353
1354 Sometimes, though, you may want to be more flexible (for example, the first
1355 element must be an exact match, but the second element can be any positive
1356 number, and so on). Also, containers used in tests often have a small number of
1357 elements, and having to define the expected container out-of-line is a bit of a
1358 hassle.
1359
1360 You can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in such
1361 cases:
1362
1363 ```cpp
1364 using ::testing::_;
1365 using ::testing::ElementsAre;
1366 using ::testing::Gt;
1367 ...
1368 MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override));
1369 ...
1370 EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5)));
1371 ```
1372
1373 The above matcher says that the container must have 4 elements, which must be 1,
1374 greater than 0, anything, and 5 respectively.
1375
1376 If you instead write:
1377
1378 ```cpp
1379 using ::testing::_;
1380 using ::testing::Gt;
1381 using ::testing::UnorderedElementsAre;
1382 ...
1383 MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override));
1384 ...
1385 EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5)));
1386 ```
1387
1388 It means that the container must have 4 elements, which (under some permutation)
1389 must be 1, greater than 0, anything, and 5 respectively.
1390
1391 As an alternative you can place the arguments in a C-style array and use
1392 `ElementsAreArray()` or `UnorderedElementsAreArray()` instead:
1393
1394 ```cpp
1395 using ::testing::ElementsAreArray;
1396 ...
1397 // ElementsAreArray accepts an array of element values.
1398 const int expected_vector1[] = {1, 5, 2, 4, ...};
1399 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1)));
1400
1401 // Or, an array of element matchers.
1402 Matcher<int> expected_vector2[] = {1, Gt(2), _, 3, ...};
1403 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2)));
1404 ```
1405
1406 In case the array needs to be dynamically created (and therefore the array size
1407 cannot be inferred by the compiler), you can give `ElementsAreArray()` an
1408 additional argument to specify the array size:
1409
1410 ```cpp
1411 using ::testing::ElementsAreArray;
1412 ...
1413 int* const expected_vector3 = new int[count];
1414 ... fill expected_vector3 with values ...
1415 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count)));
1416 ```
1417
1418 Use `Pair` when comparing maps or other associative containers.
1419
1420 {% raw %}
1421
1422 ```cpp
1423 using testing::ElementsAre;
1424 using testing::Pair;
1425 ...
1426 std::map<string, int> m = {{"a", 1}, {"b", 2}, {"c", 3}};
1427 EXPECT_THAT(m, ElementsAre(Pair("a", 1), Pair("b", 2), Pair("c", 3)));
1428 ```
1429
1430 {% endraw %}
1431
1432 **Tips:**
1433
1434 * `ElementsAre*()` can be used to match *any* container that implements the
1435 STL iterator pattern (i.e. it has a `const_iterator` type and supports
1436 `begin()/end()`), not just the ones defined in STL. It will even work with
1437 container types yet to be written - as long as they follows the above
1438 pattern.
1439 * You can use nested `ElementsAre*()` to match nested (multi-dimensional)
1440 containers.
1441 * If the container is passed by pointer instead of by reference, just write
1442 `Pointee(ElementsAre*(...))`.
1443 * The order of elements *matters* for `ElementsAre*()`. If you are using it
1444 with containers whose element order are undefined (e.g. `hash_map`) you
1445 should use `WhenSorted` around `ElementsAre`.
1446
1447 ### Sharing Matchers
1448
1449 Under the hood, a gMock matcher object consists of a pointer to a ref-counted
1450 implementation object. Copying matchers is allowed and very efficient, as only
1451 the pointer is copied. When the last matcher that references the implementation
1452 object dies, the implementation object will be deleted.
1453
1454 Therefore, if you have some complex matcher that you want to use again and
1455 again, there is no need to build it every time. Just assign it to a matcher
1456 variable and use that variable repeatedly! For example,
1457
1458 ```cpp
1459 using ::testing::AllOf;
1460 using ::testing::Gt;
1461 using ::testing::Le;
1462 using ::testing::Matcher;
1463 ...
1464 Matcher<int> in_range = AllOf(Gt(5), Le(10));
1465 ... use in_range as a matcher in multiple EXPECT_CALLs ...
1466 ```
1467
1468 ### Matchers must have no side-effects {#PureMatchers}
1469
1470 {: .callout .warning}
1471 WARNING: gMock does not guarantee when or how many times a matcher will be
1472 invoked. Therefore, all matchers must be *purely functional*: they cannot have
1473 any side effects, and the match result must not depend on anything other than
1474 the matcher's parameters and the value being matched.
1475
1476 This requirement must be satisfied no matter how a matcher is defined (e.g., if
1477 it is one of the standard matchers, or a custom matcher). In particular, a
1478 matcher can never call a mock function, as that will affect the state of the
1479 mock object and gMock.
1480
1481 ## Setting Expectations
1482
1483 ### Knowing When to Expect {#UseOnCall}
1484
1485 **`ON_CALL`** is likely the *single most under-utilized construct* in gMock.
1486
1487 There are basically two constructs for defining the behavior of a mock object:
1488 `ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when
1489 a mock method is called, but <em>doesn't imply any expectation on the method
1490 being called</em>. `EXPECT_CALL` not only defines the behavior, but also sets an
1491 expectation that <em>the method will be called with the given arguments, for the
1492 given number of times</em> (and *in the given order* when you specify the order
1493 too).
1494
1495 Since `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every
1496 `EXPECT_CALL` adds a constraint on the behavior of the code under test. Having
1497 more constraints than necessary is *baaad* - even worse than not having enough
1498 constraints.
1499
1500 This may be counter-intuitive. How could tests that verify more be worse than
1501 tests that verify less? Isn't verification the whole point of tests?
1502
1503 The answer lies in *what* a test should verify. **A good test verifies the
1504 contract of the code.** If a test over-specifies, it doesn't leave enough
1505 freedom to the implementation. As a result, changing the implementation without
1506 breaking the contract (e.g. refactoring and optimization), which should be
1507 perfectly fine to do, can break such tests. Then you have to spend time fixing
1508 them, only to see them broken again the next time the implementation is changed.
1509
1510 Keep in mind that one doesn't have to verify more than one property in one test.
1511 In fact, **it's a good style to verify only one thing in one test.** If you do
1512 that, a bug will likely break only one or two tests instead of dozens (which
1513 case would you rather debug?). If you are also in the habit of giving tests
1514 descriptive names that tell what they verify, you can often easily guess what's
1515 wrong just from the test log itself.
1516
1517 So use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend
1518 to verify that the call is made. For example, you may have a bunch of `ON_CALL`s
1519 in your test fixture to set the common mock behavior shared by all tests in the
1520 same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s
1521 to verify different aspects of the code's behavior. Compared with the style
1522 where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more
1523 resilient to implementational changes (and thus less likely to require
1524 maintenance) and makes the intent of the tests more obvious (so they are easier
1525 to maintain when you do need to maintain them).
1526
1527 If you are bothered by the "Uninteresting mock function call" message printed
1528 when a mock method without an `EXPECT_CALL` is called, you may use a `NiceMock`
1529 instead to suppress all such messages for the mock object, or suppress the
1530 message for specific methods by adding `EXPECT_CALL(...).Times(AnyNumber())`. DO
1531 NOT suppress it by blindly adding an `EXPECT_CALL(...)`, or you'll have a test
1532 that's a pain to maintain.
1533
1534 ### Ignoring Uninteresting Calls
1535
1536 If you are not interested in how a mock method is called, just don't say
1537 anything about it. In this case, if the method is ever called, gMock will
1538 perform its default action to allow the test program to continue. If you are not
1539 happy with the default action taken by gMock, you can override it using
1540 `DefaultValue<T>::Set()` (described [here](#DefaultValue)) or `ON_CALL()`.
1541
1542 Please note that once you expressed interest in a particular mock method (via
1543 `EXPECT_CALL()`), all invocations to it must match some expectation. If this
1544 function is called but the arguments don't match any `EXPECT_CALL()` statement,
1545 it will be an error.
1546
1547 ### Disallowing Unexpected Calls
1548
1549 If a mock method shouldn't be called at all, explicitly say so:
1550
1551 ```cpp
1552 using ::testing::_;
1553 ...
1554 EXPECT_CALL(foo, Bar(_))
1555 .Times(0);
1556 ```
1557
1558 If some calls to the method are allowed, but the rest are not, just list all the
1559 expected calls:
1560
1561 ```cpp
1562 using ::testing::AnyNumber;
1563 using ::testing::Gt;
1564 ...
1565 EXPECT_CALL(foo, Bar(5));
1566 EXPECT_CALL(foo, Bar(Gt(10)))
1567 .Times(AnyNumber());
1568 ```
1569
1570 A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` statements
1571 will be an error.
1572
1573 ### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected}
1574
1575 *Uninteresting* calls and *unexpected* calls are different concepts in gMock.
1576 *Very* different.
1577
1578 A call `x.Y(...)` is **uninteresting** if there's *not even a single*
1579 `EXPECT_CALL(x, Y(...))` set. In other words, the test isn't interested in the
1580 `x.Y()` method at all, as evident in that the test doesn't care to say anything
1581 about it.
1582
1583 A call `x.Y(...)` is **unexpected** if there are *some* `EXPECT_CALL(x,
1584 Y(...))`s set, but none of them matches the call. Put another way, the test is
1585 interested in the `x.Y()` method (therefore it explicitly sets some
1586 `EXPECT_CALL` to verify how it's called); however, the verification fails as the
1587 test doesn't expect this particular call to happen.
1588
1589 **An unexpected call is always an error,** as the code under test doesn't behave
1590 the way the test expects it to behave.
1591
1592 **By default, an uninteresting call is not an error,** as it violates no
1593 constraint specified by the test. (gMock's philosophy is that saying nothing
1594 means there is no constraint.) However, it leads to a warning, as it *might*
1595 indicate a problem (e.g. the test author might have forgotten to specify a
1596 constraint).
1597
1598 In gMock, `NiceMock` and `StrictMock` can be used to make a mock class "nice" or
1599 "strict". How does this affect uninteresting calls and unexpected calls?
1600
1601 A **nice mock** suppresses uninteresting call *warnings*. It is less chatty than
1602 the default mock, but otherwise is the same. If a test fails with a default
1603 mock, it will also fail using a nice mock instead. And vice versa. Don't expect
1604 making a mock nice to change the test's result.
1605
1606 A **strict mock** turns uninteresting call warnings into errors. So making a
1607 mock strict may change the test's result.
1608
1609 Let's look at an example:
1610
1611 ```cpp
1612 TEST(...) {
1613 NiceMock<MockDomainRegistry> mock_registry;
1614 EXPECT_CALL(mock_registry, GetDomainOwner("google.com"))
1615 .WillRepeatedly(Return("Larry Page"));
1616
1617 // Use mock_registry in code under test.
1618 ... &mock_registry ...
1619 }
1620 ```
1621
1622 The sole `EXPECT_CALL` here says that all calls to `GetDomainOwner()` must have
1623 `"google.com"` as the argument. If `GetDomainOwner("yahoo.com")` is called, it
1624 will be an unexpected call, and thus an error. *Having a nice mock doesn't
1625 change the severity of an unexpected call.*
1626
1627 So how do we tell gMock that `GetDomainOwner()` can be called with some other
1628 arguments as well? The standard technique is to add a "catch all" `EXPECT_CALL`:
1629
1630 ```cpp
1631 EXPECT_CALL(mock_registry, GetDomainOwner(_))
1632 .Times(AnyNumber()); // catches all other calls to this method.
1633 EXPECT_CALL(mock_registry, GetDomainOwner("google.com"))
1634 .WillRepeatedly(Return("Larry Page"));
1635 ```
1636
1637 Remember that `_` is the wildcard matcher that matches anything. With this, if
1638 `GetDomainOwner("google.com")` is called, it will do what the second
1639 `EXPECT_CALL` says; if it is called with a different argument, it will do what
1640 the first `EXPECT_CALL` says.
1641
1642 Note that the order of the two `EXPECT_CALL`s is important, as a newer
1643 `EXPECT_CALL` takes precedence over an older one.
1644
1645 For more on uninteresting calls, nice mocks, and strict mocks, read
1646 ["The Nice, the Strict, and the Naggy"](#NiceStrictNaggy).
1647
1648 ### Ignoring Uninteresting Arguments {#ParameterlessExpectations}
1649
1650 If your test doesn't care about the parameters (it only cares about the number
1651 or order of calls), you can often simply omit the parameter list:
1652
1653 ```cpp
1654 // Expect foo.Bar( ... ) twice with any arguments.
1655 EXPECT_CALL(foo, Bar).Times(2);
1656
1657 // Delegate to the given method whenever the factory is invoked.
1658 ON_CALL(foo_factory, MakeFoo)
1659 .WillByDefault(&BuildFooForTest);
1660 ```
1661
1662 This functionality is only available when a method is not overloaded; to prevent
1663 unexpected behavior it is a compilation error to try to set an expectation on a
1664 method where the specific overload is ambiguous. You can work around this by
1665 supplying a [simpler mock interface](#SimplerInterfaces) than the mocked class
1666 provides.
1667
1668 This pattern is also useful when the arguments are interesting, but match logic
1669 is substantially complex. You can leave the argument list unspecified and use
1670 SaveArg actions to [save the values for later verification](#SaveArgVerify). If
1671 you do that, you can easily differentiate calling the method the wrong number of
1672 times from calling it with the wrong arguments.
1673
1674 ### Expecting Ordered Calls {#OrderedCalls}
1675
1676 Although an `EXPECT_CALL()` statement defined later takes precedence when gMock
1677 tries to match a function call with an expectation, by default calls don't have
1678 to happen in the order `EXPECT_CALL()` statements are written. For example, if
1679 the arguments match the matchers in the second `EXPECT_CALL()`, but not those in
1680 the first and third, then the second expectation will be used.
1681
1682 If you would rather have all calls occur in the order of the expectations, put
1683 the `EXPECT_CALL()` statements in a block where you define a variable of type
1684 `InSequence`:
1685
1686 ```cpp
1687 using ::testing::_;
1688 using ::testing::InSequence;
1689
1690 {
1691 InSequence s;
1692
1693 EXPECT_CALL(foo, DoThis(5));
1694 EXPECT_CALL(bar, DoThat(_))
1695 .Times(2);
1696 EXPECT_CALL(foo, DoThis(6));
1697 }
1698 ```
1699
1700 In this example, we expect a call to `foo.DoThis(5)`, followed by two calls to
1701 `bar.DoThat()` where the argument can be anything, which are in turn followed by
1702 a call to `foo.DoThis(6)`. If a call occurred out-of-order, gMock will report an
1703 error.
1704
1705 ### Expecting Partially Ordered Calls {#PartialOrder}
1706
1707 Sometimes requiring everything to occur in a predetermined order can lead to
1708 brittle tests. For example, we may care about `A` occurring before both `B` and
1709 `C`, but aren't interested in the relative order of `B` and `C`. In this case,
1710 the test should reflect our real intent, instead of being overly constraining.
1711
1712 gMock allows you to impose an arbitrary DAG (directed acyclic graph) on the
1713 calls. One way to express the DAG is to use the
1714 [`After` clause](reference/mocking.md#EXPECT_CALL.After) of `EXPECT_CALL`.
1715
1716 Another way is via the `InSequence()` clause (not the same as the `InSequence`
1717 class), which we borrowed from jMock 2. It's less flexible than `After()`, but
1718 more convenient when you have long chains of sequential calls, as it doesn't
1719 require you to come up with different names for the expectations in the chains.
1720 Here's how it works:
1721
1722 If we view `EXPECT_CALL()` statements as nodes in a graph, and add an edge from
1723 node A to node B wherever A must occur before B, we can get a DAG. We use the
1724 term "sequence" to mean a directed path in this DAG. Now, if we decompose the
1725 DAG into sequences, we just need to know which sequences each `EXPECT_CALL()`
1726 belongs to in order to be able to reconstruct the original DAG.
1727
1728 So, to specify the partial order on the expectations we need to do two things:
1729 first to define some `Sequence` objects, and then for each `EXPECT_CALL()` say
1730 which `Sequence` objects it is part of.
1731
1732 Expectations in the same sequence must occur in the order they are written. For
1733 example,
1734
1735 ```cpp
1736 using ::testing::Sequence;
1737 ...
1738 Sequence s1, s2;
1739
1740 EXPECT_CALL(foo, A())
1741 .InSequence(s1, s2);
1742 EXPECT_CALL(bar, B())
1743 .InSequence(s1);
1744 EXPECT_CALL(bar, C())
1745 .InSequence(s2);
1746 EXPECT_CALL(foo, D())
1747 .InSequence(s2);
1748 ```
1749
1750 specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> C -> D`):
1751
1752 ```text
1753 +---> B
1754 |
1755 A ---|
1756 |
1757 +---> C ---> D
1758 ```
1759
1760 This means that A must occur before B and C, and C must occur before D. There's
1761 no restriction about the order other than these.
1762
1763 ### Controlling When an Expectation Retires
1764
1765 When a mock method is called, gMock only considers expectations that are still
1766 active. An expectation is active when created, and becomes inactive (aka
1767 *retires*) when a call that has to occur later has occurred. For example, in
1768
1769 ```cpp
1770 using ::testing::_;
1771 using ::testing::Sequence;
1772 ...
1773 Sequence s1, s2;
1774
1775 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1
1776 .Times(AnyNumber())
1777 .InSequence(s1, s2);
1778 EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2
1779 .InSequence(s1);
1780 EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3
1781 .InSequence(s2);
1782 ```
1783
1784 as soon as either #2 or #3 is matched, #1 will retire. If a warning `"File too
1785 large."` is logged after this, it will be an error.
1786
1787 Note that an expectation doesn't retire automatically when it's saturated. For
1788 example,
1789
1790 ```cpp
1791 using ::testing::_;
1792 ...
1793 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1794 EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2
1795 ```
1796
1797 says that there will be exactly one warning with the message `"File too
1798 large."`. If the second warning contains this message too, #2 will match again
1799 and result in an upper-bound-violated error.
1800
1801 If this is not what you want, you can ask an expectation to retire as soon as it
1802 becomes saturated:
1803
1804 ```cpp
1805 using ::testing::_;
1806 ...
1807 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1808 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2
1809 .RetiresOnSaturation();
1810 ```
1811
1812 Here #2 can be used only once, so if you have two warnings with the message
1813 `"File too large."`, the first will match #2 and the second will match #1 -
1814 there will be no error.
1815
1816 ## Using Actions
1817
1818 ### Returning References from Mock Methods
1819
1820 If a mock function's return type is a reference, you need to use `ReturnRef()`
1821 instead of `Return()` to return a result:
1822
1823 ```cpp
1824 using ::testing::ReturnRef;
1825
1826 class MockFoo : public Foo {
1827 public:
1828 MOCK_METHOD(Bar&, GetBar, (), (override));
1829 };
1830 ...
1831 MockFoo foo;
1832 Bar bar;
1833 EXPECT_CALL(foo, GetBar())
1834 .WillOnce(ReturnRef(bar));
1835 ...
1836 ```
1837
1838 ### Returning Live Values from Mock Methods
1839
1840 The `Return(x)` action saves a copy of `x` when the action is created, and
1841 always returns the same value whenever it's executed. Sometimes you may want to
1842 instead return the *live* value of `x` (i.e. its value at the time when the
1843 action is *executed*.). Use either `ReturnRef()` or `ReturnPointee()` for this
1844 purpose.
1845
1846 If the mock function's return type is a reference, you can do it using
1847 `ReturnRef(x)`, as shown in the previous recipe ("Returning References from Mock
1848 Methods"). However, gMock doesn't let you use `ReturnRef()` in a mock function
1849 whose return type is not a reference, as doing that usually indicates a user
1850 error. So, what shall you do?
1851
1852 Though you may be tempted, DO NOT use `std::ref()`:
1853
1854 ```cpp
1855 using testing::Return;
1856
1857 class MockFoo : public Foo {
1858 public:
1859 MOCK_METHOD(int, GetValue, (), (override));
1860 };
1861 ...
1862 int x = 0;
1863 MockFoo foo;
1864 EXPECT_CALL(foo, GetValue())
1865 .WillRepeatedly(Return(std::ref(x))); // Wrong!
1866 x = 42;
1867 EXPECT_EQ(42, foo.GetValue());
1868 ```
1869
1870 Unfortunately, it doesn't work here. The above code will fail with error:
1871
1872 ```text
1873 Value of: foo.GetValue()
1874 Actual: 0
1875 Expected: 42
1876 ```
1877
1878 The reason is that `Return(*value*)` converts `value` to the actual return type
1879 of the mock function at the time when the action is *created*, not when it is
1880 *executed*. (This behavior was chosen for the action to be safe when `value` is
1881 a proxy object that references some temporary objects.) As a result,
1882 `std::ref(x)` is converted to an `int` value (instead of a `const int&`) when
1883 the expectation is set, and `Return(std::ref(x))` will always return 0.
1884
1885 `ReturnPointee(pointer)` was provided to solve this problem specifically. It
1886 returns the value pointed to by `pointer` at the time the action is *executed*:
1887
1888 ```cpp
1889 using testing::ReturnPointee;
1890 ...
1891 int x = 0;
1892 MockFoo foo;
1893 EXPECT_CALL(foo, GetValue())
1894 .WillRepeatedly(ReturnPointee(&x)); // Note the & here.
1895 x = 42;
1896 EXPECT_EQ(42, foo.GetValue()); // This will succeed now.
1897 ```
1898
1899 ### Combining Actions
1900
1901 Want to do more than one thing when a function is called? That's fine. `DoAll()`
1902 allow you to do sequence of actions every time. Only the return value of the
1903 last action in the sequence will be used.
1904
1905 ```cpp
1906 using ::testing::_;
1907 using ::testing::DoAll;
1908
1909 class MockFoo : public Foo {
1910 public:
1911 MOCK_METHOD(bool, Bar, (int n), (override));
1912 };
1913 ...
1914 EXPECT_CALL(foo, Bar(_))
1915 .WillOnce(DoAll(action_1,
1916 action_2,
1917 ...
1918 action_n));
1919 ```
1920
1921 ### Verifying Complex Arguments {#SaveArgVerify}
1922
1923 If you want to verify that a method is called with a particular argument but the
1924 match criteria is complex, it can be difficult to distinguish between
1925 cardinality failures (calling the method the wrong number of times) and argument
1926 match failures. Similarly, if you are matching multiple parameters, it may not
1927 be easy to distinguishing which argument failed to match. For example:
1928
1929 ```cpp
1930 // Not ideal: this could fail because of a problem with arg1 or arg2, or maybe
1931 // just the method wasn't called.
1932 EXPECT_CALL(foo, SendValues(_, ElementsAre(1, 4, 4, 7), EqualsProto( ... )));
1933 ```
1934
1935 You can instead save the arguments and test them individually:
1936
1937 ```cpp
1938 EXPECT_CALL(foo, SendValues)
1939 .WillOnce(DoAll(SaveArg<1>(&actual_array), SaveArg<2>(&actual_proto)));
1940 ... run the test
1941 EXPECT_THAT(actual_array, ElementsAre(1, 4, 4, 7));
1942 EXPECT_THAT(actual_proto, EqualsProto( ... ));
1943 ```
1944
1945 ### Mocking Side Effects {#MockingSideEffects}
1946
1947 Sometimes a method exhibits its effect not via returning a value but via side
1948 effects. For example, it may change some global state or modify an output
1949 argument. To mock side effects, in general you can define your own action by
1950 implementing `::testing::ActionInterface`.
1951
1952 If all you need to do is to change an output argument, the built-in
1953 `SetArgPointee()` action is convenient:
1954
1955 ```cpp
1956 using ::testing::_;
1957 using ::testing::SetArgPointee;
1958
1959 class MockMutator : public Mutator {
1960 public:
1961 MOCK_METHOD(void, Mutate, (bool mutate, int* value), (override));
1962 ...
1963 }
1964 ...
1965 MockMutator mutator;
1966 EXPECT_CALL(mutator, Mutate(true, _))
1967 .WillOnce(SetArgPointee<1>(5));
1968 ```
1969
1970 In this example, when `mutator.Mutate()` is called, we will assign 5 to the
1971 `int` variable pointed to by argument #1 (0-based).
1972
1973 `SetArgPointee()` conveniently makes an internal copy of the value you pass to
1974 it, removing the need to keep the value in scope and alive. The implication
1975 however is that the value must have a copy constructor and assignment operator.
1976
1977 If the mock method also needs to return a value as well, you can chain
1978 `SetArgPointee()` with `Return()` using `DoAll()`, remembering to put the
1979 `Return()` statement last:
1980
1981 ```cpp
1982 using ::testing::_;
1983 using ::testing::DoAll;
1984 using ::testing::Return;
1985 using ::testing::SetArgPointee;
1986
1987 class MockMutator : public Mutator {
1988 public:
1989 ...
1990 MOCK_METHOD(bool, MutateInt, (int* value), (override));
1991 }
1992 ...
1993 MockMutator mutator;
1994 EXPECT_CALL(mutator, MutateInt(_))
1995 .WillOnce(DoAll(SetArgPointee<0>(5),
1996 Return(true)));
1997 ```
1998
1999 Note, however, that if you use the `ReturnOKWith()` method, it will override the
2000 values provided by `SetArgPointee()` in the response parameters of your function
2001 call.
2002
2003 If the output argument is an array, use the `SetArrayArgument<N>(first, last)`
2004 action instead. It copies the elements in source range `[first, last)` to the
2005 array pointed to by the `N`-th (0-based) argument:
2006
2007 ```cpp
2008 using ::testing::NotNull;
2009 using ::testing::SetArrayArgument;
2010
2011 class MockArrayMutator : public ArrayMutator {
2012 public:
2013 MOCK_METHOD(void, Mutate, (int* values, int num_values), (override));
2014 ...
2015 }
2016 ...
2017 MockArrayMutator mutator;
2018 int values[5] = {1, 2, 3, 4, 5};
2019 EXPECT_CALL(mutator, Mutate(NotNull(), 5))
2020 .WillOnce(SetArrayArgument<0>(values, values + 5));
2021 ```
2022
2023 This also works when the argument is an output iterator:
2024
2025 ```cpp
2026 using ::testing::_;
2027 using ::testing::SetArrayArgument;
2028
2029 class MockRolodex : public Rolodex {
2030 public:
2031 MOCK_METHOD(void, GetNames, (std::back_insert_iterator<vector<string>>),
2032 (override));
2033 ...
2034 }
2035 ...
2036 MockRolodex rolodex;
2037 vector<string> names = {"George", "John", "Thomas"};
2038 EXPECT_CALL(rolodex, GetNames(_))
2039 .WillOnce(SetArrayArgument<0>(names.begin(), names.end()));
2040 ```
2041
2042 ### Changing a Mock Object's Behavior Based on the State
2043
2044 If you expect a call to change the behavior of a mock object, you can use
2045 `::testing::InSequence` to specify different behaviors before and after the
2046 call:
2047
2048 ```cpp
2049 using ::testing::InSequence;
2050 using ::testing::Return;
2051
2052 ...
2053 {
2054 InSequence seq;
2055 EXPECT_CALL(my_mock, IsDirty())
2056 .WillRepeatedly(Return(true));
2057 EXPECT_CALL(my_mock, Flush());
2058 EXPECT_CALL(my_mock, IsDirty())
2059 .WillRepeatedly(Return(false));
2060 }
2061 my_mock.FlushIfDirty();
2062 ```
2063
2064 This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called
2065 and return `false` afterwards.
2066
2067 If the behavior change is more complex, you can store the effects in a variable
2068 and make a mock method get its return value from that variable:
2069
2070 ```cpp
2071 using ::testing::_;
2072 using ::testing::SaveArg;
2073 using ::testing::Return;
2074
2075 ACTION_P(ReturnPointee, p) { return *p; }
2076 ...
2077 int previous_value = 0;
2078 EXPECT_CALL(my_mock, GetPrevValue)
2079 .WillRepeatedly(ReturnPointee(&previous_value));
2080 EXPECT_CALL(my_mock, UpdateValue)
2081 .WillRepeatedly(SaveArg<0>(&previous_value));
2082 my_mock.DoSomethingToUpdateValue();
2083 ```
2084
2085 Here `my_mock.GetPrevValue()` will always return the argument of the last
2086 `UpdateValue()` call.
2087
2088 ### Setting the Default Value for a Return Type {#DefaultValue}
2089
2090 If a mock method's return type is a built-in C++ type or pointer, by default it
2091 will return 0 when invoked. Also, in C++ 11 and above, a mock method whose
2092 return type has a default constructor will return a default-constructed value by
2093 default. You only need to specify an action if this default value doesn't work
2094 for you.
2095
2096 Sometimes, you may want to change this default value, or you may want to specify
2097 a default value for types gMock doesn't know about. You can do this using the
2098 `::testing::DefaultValue` class template:
2099
2100 ```cpp
2101 using ::testing::DefaultValue;
2102
2103 class MockFoo : public Foo {
2104 public:
2105 MOCK_METHOD(Bar, CalculateBar, (), (override));
2106 };
2107
2108
2109 ...
2110 Bar default_bar;
2111 // Sets the default return value for type Bar.
2112 DefaultValue<Bar>::Set(default_bar);
2113
2114 MockFoo foo;
2115
2116 // We don't need to specify an action here, as the default
2117 // return value works for us.
2118 EXPECT_CALL(foo, CalculateBar());
2119
2120 foo.CalculateBar(); // This should return default_bar.
2121
2122 // Unsets the default return value.
2123 DefaultValue<Bar>::Clear();
2124 ```
2125
2126 Please note that changing the default value for a type can make your tests hard
2127 to understand. We recommend you to use this feature judiciously. For example,
2128 you may want to make sure the `Set()` and `Clear()` calls are right next to the
2129 code that uses your mock.
2130
2131 ### Setting the Default Actions for a Mock Method
2132
2133 You've learned how to change the default value of a given type. However, this
2134 may be too coarse for your purpose: perhaps you have two mock methods with the
2135 same return type and you want them to have different behaviors. The `ON_CALL()`
2136 macro allows you to customize your mock's behavior at the method level:
2137
2138 ```cpp
2139 using ::testing::_;
2140 using ::testing::AnyNumber;
2141 using ::testing::Gt;
2142 using ::testing::Return;
2143 ...
2144 ON_CALL(foo, Sign(_))
2145 .WillByDefault(Return(-1));
2146 ON_CALL(foo, Sign(0))
2147 .WillByDefault(Return(0));
2148 ON_CALL(foo, Sign(Gt(0)))
2149 .WillByDefault(Return(1));
2150
2151 EXPECT_CALL(foo, Sign(_))
2152 .Times(AnyNumber());
2153
2154 foo.Sign(5); // This should return 1.
2155 foo.Sign(-9); // This should return -1.
2156 foo.Sign(0); // This should return 0.
2157 ```
2158
2159 As you may have guessed, when there are more than one `ON_CALL()` statements,
2160 the newer ones in the order take precedence over the older ones. In other words,
2161 the **last** one that matches the function arguments will be used. This matching
2162 order allows you to set up the common behavior in a mock object's constructor or
2163 the test fixture's set-up phase and specialize the mock's behavior later.
2164
2165 Note that both `ON_CALL` and `EXPECT_CALL` have the same "later statements take
2166 precedence" rule, but they don't interact. That is, `EXPECT_CALL`s have their
2167 own precedence order distinct from the `ON_CALL` precedence order.
2168
2169 ### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions}
2170
2171 If the built-in actions don't suit you, you can use an existing callable
2172 (function, `std::function`, method, functor, lambda) as an action.
2173
2174 ```cpp
2175 using ::testing::_; using ::testing::Invoke;
2176
2177 class MockFoo : public Foo {
2178 public:
2179 MOCK_METHOD(int, Sum, (int x, int y), (override));
2180 MOCK_METHOD(bool, ComplexJob, (int x), (override));
2181 };
2182
2183 int CalculateSum(int x, int y) { return x + y; }
2184 int Sum3(int x, int y, int z) { return x + y + z; }
2185
2186 class Helper {
2187 public:
2188 bool ComplexJob(int x);
2189 };
2190
2191 ...
2192 MockFoo foo;
2193 Helper helper;
2194 EXPECT_CALL(foo, Sum(_, _))
2195 .WillOnce(&CalculateSum)
2196 .WillRepeatedly(Invoke(NewPermanentCallback(Sum3, 1)));
2197 EXPECT_CALL(foo, ComplexJob(_))
2198 .WillOnce(Invoke(&helper, &Helper::ComplexJob))
2199 .WillOnce([] { return true; })
2200 .WillRepeatedly([](int x) { return x > 0; });
2201
2202 foo.Sum(5, 6); // Invokes CalculateSum(5, 6).
2203 foo.Sum(2, 3); // Invokes Sum3(1, 2, 3).
2204 foo.ComplexJob(10); // Invokes helper.ComplexJob(10).
2205 foo.ComplexJob(-1); // Invokes the inline lambda.
2206 ```
2207
2208 The only requirement is that the type of the function, etc must be *compatible*
2209 with the signature of the mock function, meaning that the latter's arguments (if
2210 it takes any) can be implicitly converted to the corresponding arguments of the
2211 former, and the former's return type can be implicitly converted to that of the
2212 latter. So, you can invoke something whose type is *not* exactly the same as the
2213 mock function, as long as it's safe to do so - nice, huh?
2214
2215 Note that:
2216
2217 * The action takes ownership of the callback and will delete it when the
2218 action itself is destructed.
2219 * If the type of a callback is derived from a base callback type `C`, you need
2220 to implicitly cast it to `C` to resolve the overloading, e.g.
2221
2222 ```cpp
2223 using ::testing::Invoke;
2224 ...
2225 ResultCallback<bool>* is_ok = ...;
2226 ... Invoke(is_ok) ...; // This works.
2227
2228 BlockingClosure* done = new BlockingClosure;
2229 ... Invoke(implicit_cast<Closure*>(done)) ...; // The cast is necessary.
2230 ```
2231
2232 ### Using Functions with Extra Info as Actions
2233
2234 The function or functor you call using `Invoke()` must have the same number of
2235 arguments as the mock function you use it for. Sometimes you may have a function
2236 that takes more arguments, and you are willing to pass in the extra arguments
2237 yourself to fill the gap. You can do this in gMock using callbacks with
2238 pre-bound arguments. Here's an example:
2239
2240 ```cpp
2241 using ::testing::Invoke;
2242
2243 class MockFoo : public Foo {
2244 public:
2245 MOCK_METHOD(char, DoThis, (int n), (override));
2246 };
2247
2248 char SignOfSum(int x, int y) {
2249 const int sum = x + y;
2250 return (sum > 0) ? '+' : (sum < 0) ? '-' : '0';
2251 }
2252
2253 TEST_F(FooTest, Test) {
2254 MockFoo foo;
2255
2256 EXPECT_CALL(foo, DoThis(2))
2257 .WillOnce(Invoke(NewPermanentCallback(SignOfSum, 5)));
2258 EXPECT_EQ('+', foo.DoThis(2)); // Invokes SignOfSum(5, 2).
2259 }
2260 ```
2261
2262 ### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments
2263
2264 `Invoke()` passes the mock function's arguments to the function, etc being
2265 invoked such that the callee has the full context of the call to work with. If
2266 the invoked function is not interested in some or all of the arguments, it can
2267 simply ignore them.
2268
2269 Yet, a common pattern is that a test author wants to invoke a function without
2270 the arguments of the mock function. She could do that using a wrapper function
2271 that throws away the arguments before invoking an underlining nullary function.
2272 Needless to say, this can be tedious and obscures the intent of the test.
2273
2274 There are two solutions to this problem. First, you can pass any callable of
2275 zero args as an action. Alternatively, use `InvokeWithoutArgs()`, which is like
2276 `Invoke()` except that it doesn't pass the mock function's arguments to the
2277 callee. Here's an example of each:
2278
2279 ```cpp
2280 using ::testing::_;
2281 using ::testing::InvokeWithoutArgs;
2282
2283 class MockFoo : public Foo {
2284 public:
2285 MOCK_METHOD(bool, ComplexJob, (int n), (override));
2286 };
2287
2288 bool Job1() { ... }
2289 bool Job2(int n, char c) { ... }
2290
2291 ...
2292 MockFoo foo;
2293 EXPECT_CALL(foo, ComplexJob(_))
2294 .WillOnce([] { Job1(); });
2295 .WillOnce(InvokeWithoutArgs(NewPermanentCallback(Job2, 5, 'a')));
2296
2297 foo.ComplexJob(10); // Invokes Job1().
2298 foo.ComplexJob(20); // Invokes Job2(5, 'a').
2299 ```
2300
2301 Note that:
2302
2303 * The action takes ownership of the callback and will delete it when the
2304 action itself is destructed.
2305 * If the type of a callback is derived from a base callback type `C`, you need
2306 to implicitly cast it to `C` to resolve the overloading, e.g.
2307
2308 ```cpp
2309 using ::testing::InvokeWithoutArgs;
2310 ...
2311 ResultCallback<bool>* is_ok = ...;
2312 ... InvokeWithoutArgs(is_ok) ...; // This works.
2313
2314 BlockingClosure* done = ...;
2315 ... InvokeWithoutArgs(implicit_cast<Closure*>(done)) ...;
2316 // The cast is necessary.
2317 ```
2318
2319 ### Invoking an Argument of the Mock Function
2320
2321 Sometimes a mock function will receive a function pointer, a functor (in other
2322 words, a "callable") as an argument, e.g.
2323
2324 ```cpp
2325 class MockFoo : public Foo {
2326 public:
2327 MOCK_METHOD(bool, DoThis, (int n, (ResultCallback1<bool, int>* callback)),
2328 (override));
2329 };
2330 ```
2331
2332 and you may want to invoke this callable argument:
2333
2334 ```cpp
2335 using ::testing::_;
2336 ...
2337 MockFoo foo;
2338 EXPECT_CALL(foo, DoThis(_, _))
2339 .WillOnce(...);
2340 // Will execute callback->Run(5), where callback is the
2341 // second argument DoThis() receives.
2342 ```
2343
2344 {: .callout .note}
2345 NOTE: The section below is legacy documentation from before C++ had lambdas:
2346
2347 Arghh, you need to refer to a mock function argument but C++ has no lambda
2348 (yet), so you have to define your own action. :-( Or do you really?
2349
2350 Well, gMock has an action to solve *exactly* this problem:
2351
2352 ```cpp
2353 InvokeArgument<N>(arg_1, arg_2, ..., arg_m)
2354 ```
2355
2356 will invoke the `N`-th (0-based) argument the mock function receives, with
2357 `arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is a function
2358 pointer, a functor, or a callback. gMock handles them all.
2359
2360 With that, you could write:
2361
2362 ```cpp
2363 using ::testing::_;
2364 using ::testing::InvokeArgument;
2365 ...
2366 EXPECT_CALL(foo, DoThis(_, _))
2367 .WillOnce(InvokeArgument<1>(5));
2368 // Will execute callback->Run(5), where callback is the
2369 // second argument DoThis() receives.
2370 ```
2371
2372 What if the callable takes an argument by reference? No problem - just wrap it
2373 inside `std::ref()`:
2374
2375 ```cpp
2376 ...
2377 MOCK_METHOD(bool, Bar,
2378 ((ResultCallback2<bool, int, const Helper&>* callback)),
2379 (override));
2380 ...
2381 using ::testing::_;
2382 using ::testing::InvokeArgument;
2383 ...
2384 MockFoo foo;
2385 Helper helper;
2386 ...
2387 EXPECT_CALL(foo, Bar(_))
2388 .WillOnce(InvokeArgument<0>(5, std::ref(helper)));
2389 // std::ref(helper) guarantees that a reference to helper, not a copy of
2390 // it, will be passed to the callback.
2391 ```
2392
2393 What if the callable takes an argument by reference and we do **not** wrap the
2394 argument in `std::ref()`? Then `InvokeArgument()` will *make a copy* of the
2395 argument, and pass a *reference to the copy*, instead of a reference to the
2396 original value, to the callable. This is especially handy when the argument is a
2397 temporary value:
2398
2399 ```cpp
2400 ...
2401 MOCK_METHOD(bool, DoThat, (bool (*f)(const double& x, const string& s)),
2402 (override));
2403 ...
2404 using ::testing::_;
2405 using ::testing::InvokeArgument;
2406 ...
2407 MockFoo foo;
2408 ...
2409 EXPECT_CALL(foo, DoThat(_))
2410 .WillOnce(InvokeArgument<0>(5.0, string("Hi")));
2411 // Will execute (*f)(5.0, string("Hi")), where f is the function pointer
2412 // DoThat() receives. Note that the values 5.0 and string("Hi") are
2413 // temporary and dead once the EXPECT_CALL() statement finishes. Yet
2414 // it's fine to perform this action later, since a copy of the values
2415 // are kept inside the InvokeArgument action.
2416 ```
2417
2418 ### Ignoring an Action's Result
2419
2420 Sometimes you have an action that returns *something*, but you need an action
2421 that returns `void` (perhaps you want to use it in a mock function that returns
2422 `void`, or perhaps it needs to be used in `DoAll()` and it's not the last in the
2423 list). `IgnoreResult()` lets you do that. For example:
2424
2425 ```cpp
2426 using ::testing::_;
2427 using ::testing::DoAll;
2428 using ::testing::IgnoreResult;
2429 using ::testing::Return;
2430
2431 int Process(const MyData& data);
2432 string DoSomething();
2433
2434 class MockFoo : public Foo {
2435 public:
2436 MOCK_METHOD(void, Abc, (const MyData& data), (override));
2437 MOCK_METHOD(bool, Xyz, (), (override));
2438 };
2439
2440 ...
2441 MockFoo foo;
2442 EXPECT_CALL(foo, Abc(_))
2443 // .WillOnce(Invoke(Process));
2444 // The above line won't compile as Process() returns int but Abc() needs
2445 // to return void.
2446 .WillOnce(IgnoreResult(Process));
2447 EXPECT_CALL(foo, Xyz())
2448 .WillOnce(DoAll(IgnoreResult(DoSomething),
2449 // Ignores the string DoSomething() returns.
2450 Return(true)));
2451 ```
2452
2453 Note that you **cannot** use `IgnoreResult()` on an action that already returns
2454 `void`. Doing so will lead to ugly compiler errors.
2455
2456 ### Selecting an Action's Arguments {#SelectingArgs}
2457
2458 Say you have a mock function `Foo()` that takes seven arguments, and you have a
2459 custom action that you want to invoke when `Foo()` is called. Trouble is, the
2460 custom action only wants three arguments:
2461
2462 ```cpp
2463 using ::testing::_;
2464 using ::testing::Invoke;
2465 ...
2466 MOCK_METHOD(bool, Foo,
2467 (bool visible, const string& name, int x, int y,
2468 (const map<pair<int, int>>), double& weight, double min_weight,
2469 double max_wight));
2470 ...
2471 bool IsVisibleInQuadrant1(bool visible, int x, int y) {
2472 return visible && x >= 0 && y >= 0;
2473 }
2474 ...
2475 EXPECT_CALL(mock, Foo)
2476 .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-(
2477 ```
2478
2479 To please the compiler God, you need to define an "adaptor" that has the same
2480 signature as `Foo()` and calls the custom action with the right arguments:
2481
2482 ```cpp
2483 using ::testing::_;
2484 using ::testing::Invoke;
2485 ...
2486 bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y,
2487 const map<pair<int, int>, double>& weight,
2488 double min_weight, double max_wight) {
2489 return IsVisibleInQuadrant1(visible, x, y);
2490 }
2491 ...
2492 EXPECT_CALL(mock, Foo)
2493 .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works.
2494 ```
2495
2496 But isn't this awkward?
2497
2498 gMock provides a generic *action adaptor*, so you can spend your time minding
2499 more important business than writing your own adaptors. Here's the syntax:
2500
2501 ```cpp
2502 WithArgs<N1, N2, ..., Nk>(action)
2503 ```
2504
2505 creates an action that passes the arguments of the mock function at the given
2506 indices (0-based) to the inner `action` and performs it. Using `WithArgs`, our
2507 original example can be written as:
2508
2509 ```cpp
2510 using ::testing::_;
2511 using ::testing::Invoke;
2512 using ::testing::WithArgs;
2513 ...
2514 EXPECT_CALL(mock, Foo)
2515 .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); // No need to define your own adaptor.
2516 ```
2517
2518 For better readability, gMock also gives you:
2519
2520 * `WithoutArgs(action)` when the inner `action` takes *no* argument, and
2521 * `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes
2522 *one* argument.
2523
2524 As you may have realized, `InvokeWithoutArgs(...)` is just syntactic sugar for
2525 `WithoutArgs(Invoke(...))`.
2526
2527 Here are more tips:
2528
2529 * The inner action used in `WithArgs` and friends does not have to be
2530 `Invoke()` -- it can be anything.
2531 * You can repeat an argument in the argument list if necessary, e.g.
2532 `WithArgs<2, 3, 3, 5>(...)`.
2533 * You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`.
2534 * The types of the selected arguments do *not* have to match the signature of
2535 the inner action exactly. It works as long as they can be implicitly
2536 converted to the corresponding arguments of the inner action. For example,
2537 if the 4-th argument of the mock function is an `int` and `my_action` takes
2538 a `double`, `WithArg<4>(my_action)` will work.
2539
2540 ### Ignoring Arguments in Action Functions
2541
2542 The [selecting-an-action's-arguments](#SelectingArgs) recipe showed us one way
2543 to make a mock function and an action with incompatible argument lists fit
2544 together. The downside is that wrapping the action in `WithArgs<...>()` can get
2545 tedious for people writing the tests.
2546
2547 If you are defining a function (or method, functor, lambda, callback) to be used
2548 with `Invoke*()`, and you are not interested in some of its arguments, an
2549 alternative to `WithArgs` is to declare the uninteresting arguments as `Unused`.
2550 This makes the definition less cluttered and less fragile in case the types of
2551 the uninteresting arguments change. It could also increase the chance the action
2552 function can be reused. For example, given
2553
2554 ```cpp
2555 public:
2556 MOCK_METHOD(double, Foo, double(const string& label, double x, double y),
2557 (override));
2558 MOCK_METHOD(double, Bar, (int index, double x, double y), (override));
2559 ```
2560
2561 instead of
2562
2563 ```cpp
2564 using ::testing::_;
2565 using ::testing::Invoke;
2566
2567 double DistanceToOriginWithLabel(const string& label, double x, double y) {
2568 return sqrt(x*x + y*y);
2569 }
2570 double DistanceToOriginWithIndex(int index, double x, double y) {
2571 return sqrt(x*x + y*y);
2572 }
2573 ...
2574 EXPECT_CALL(mock, Foo("abc", _, _))
2575 .WillOnce(Invoke(DistanceToOriginWithLabel));
2576 EXPECT_CALL(mock, Bar(5, _, _))
2577 .WillOnce(Invoke(DistanceToOriginWithIndex));
2578 ```
2579
2580 you could write
2581
2582 ```cpp
2583 using ::testing::_;
2584 using ::testing::Invoke;
2585 using ::testing::Unused;
2586
2587 double DistanceToOrigin(Unused, double x, double y) {
2588 return sqrt(x*x + y*y);
2589 }
2590 ...
2591 EXPECT_CALL(mock, Foo("abc", _, _))
2592 .WillOnce(Invoke(DistanceToOrigin));
2593 EXPECT_CALL(mock, Bar(5, _, _))
2594 .WillOnce(Invoke(DistanceToOrigin));
2595 ```
2596
2597 ### Sharing Actions
2598
2599 Just like matchers, a gMock action object consists of a pointer to a ref-counted
2600 implementation object. Therefore copying actions is also allowed and very
2601 efficient. When the last action that references the implementation object dies,
2602 the implementation object will be deleted.
2603
2604 If you have some complex action that you want to use again and again, you may
2605 not have to build it from scratch every time. If the action doesn't have an
2606 internal state (i.e. if it always does the same thing no matter how many times
2607 it has been called), you can assign it to an action variable and use that
2608 variable repeatedly. For example:
2609
2610 ```cpp
2611 using ::testing::Action;
2612 using ::testing::DoAll;
2613 using ::testing::Return;
2614 using ::testing::SetArgPointee;
2615 ...
2616 Action<bool(int*)> set_flag = DoAll(SetArgPointee<0>(5),
2617 Return(true));
2618 ... use set_flag in .WillOnce() and .WillRepeatedly() ...
2619 ```
2620
2621 However, if the action has its own state, you may be surprised if you share the
2622 action object. Suppose you have an action factory `IncrementCounter(init)` which
2623 creates an action that increments and returns a counter whose initial value is
2624 `init`, using two actions created from the same expression and using a shared
2625 action will exhibit different behaviors. Example:
2626
2627 ```cpp
2628 EXPECT_CALL(foo, DoThis())
2629 .WillRepeatedly(IncrementCounter(0));
2630 EXPECT_CALL(foo, DoThat())
2631 .WillRepeatedly(IncrementCounter(0));
2632 foo.DoThis(); // Returns 1.
2633 foo.DoThis(); // Returns 2.
2634 foo.DoThat(); // Returns 1 - Blah() uses a different
2635 // counter than Bar()'s.
2636 ```
2637
2638 versus
2639
2640 ```cpp
2641 using ::testing::Action;
2642 ...
2643 Action<int()> increment = IncrementCounter(0);
2644 EXPECT_CALL(foo, DoThis())
2645 .WillRepeatedly(increment);
2646 EXPECT_CALL(foo, DoThat())
2647 .WillRepeatedly(increment);
2648 foo.DoThis(); // Returns 1.
2649 foo.DoThis(); // Returns 2.
2650 foo.DoThat(); // Returns 3 - the counter is shared.
2651 ```
2652
2653 ### Testing Asynchronous Behavior
2654
2655 One oft-encountered problem with gMock is that it can be hard to test
2656 asynchronous behavior. Suppose you had a `EventQueue` class that you wanted to
2657 test, and you created a separate `EventDispatcher` interface so that you could
2658 easily mock it out. However, the implementation of the class fired all the
2659 events on a background thread, which made test timings difficult. You could just
2660 insert `sleep()` statements and hope for the best, but that makes your test
2661 behavior nondeterministic. A better way is to use gMock actions and
2662 `Notification` objects to force your asynchronous test to behave synchronously.
2663
2664 ```cpp
2665 class MockEventDispatcher : public EventDispatcher {
2666 MOCK_METHOD(bool, DispatchEvent, (int32), (override));
2667 };
2668
2669 TEST(EventQueueTest, EnqueueEventTest) {
2670 MockEventDispatcher mock_event_dispatcher;
2671 EventQueue event_queue(&mock_event_dispatcher);
2672
2673 const int32 kEventId = 321;
2674 absl::Notification done;
2675 EXPECT_CALL(mock_event_dispatcher, DispatchEvent(kEventId))
2676 .WillOnce([&done] { done.Notify(); });
2677
2678 event_queue.EnqueueEvent(kEventId);
2679 done.WaitForNotification();
2680 }
2681 ```
2682
2683 In the example above, we set our normal gMock expectations, but then add an
2684 additional action to notify the `Notification` object. Now we can just call
2685 `Notification::WaitForNotification()` in the main thread to wait for the
2686 asynchronous call to finish. After that, our test suite is complete and we can
2687 safely exit.
2688
2689 {: .callout .note}
2690 Note: this example has a downside: namely, if the expectation is not satisfied,
2691 our test will run forever. It will eventually time-out and fail, but it will
2692 take longer and be slightly harder to debug. To alleviate this problem, you can
2693 use `WaitForNotificationWithTimeout(ms)` instead of `WaitForNotification()`.
2694
2695 ## Misc Recipes on Using gMock
2696
2697 ### Mocking Methods That Use Move-Only Types
2698
2699 C++11 introduced *move-only types*. A move-only-typed value can be moved from
2700 one object to another, but cannot be copied. `std::unique_ptr<T>` is probably
2701 the most commonly used move-only type.
2702
2703 Mocking a method that takes and/or returns move-only types presents some
2704 challenges, but nothing insurmountable. This recipe shows you how you can do it.
2705 Note that the support for move-only method arguments was only introduced to
2706 gMock in April 2017; in older code, you may find more complex
2707 [workarounds](#LegacyMoveOnly) for lack of this feature.
2708
2709 Let’s say we are working on a fictional project that lets one post and share
2710 snippets called “buzzes”. Your code uses these types:
2711
2712 ```cpp
2713 enum class AccessLevel { kInternal, kPublic };
2714
2715 class Buzz {
2716 public:
2717 explicit Buzz(AccessLevel access) { ... }
2718 ...
2719 };
2720
2721 class Buzzer {
2722 public:
2723 virtual ~Buzzer() {}
2724 virtual std::unique_ptr<Buzz> MakeBuzz(StringPiece text) = 0;
2725 virtual bool ShareBuzz(std::unique_ptr<Buzz> buzz, int64_t timestamp) = 0;
2726 ...
2727 };
2728 ```
2729
2730 A `Buzz` object represents a snippet being posted. A class that implements the
2731 `Buzzer` interface is capable of creating and sharing `Buzz`es. Methods in
2732 `Buzzer` may return a `unique_ptr<Buzz>` or take a `unique_ptr<Buzz>`. Now we
2733 need to mock `Buzzer` in our tests.
2734
2735 To mock a method that accepts or returns move-only types, you just use the
2736 familiar `MOCK_METHOD` syntax as usual:
2737
2738 ```cpp
2739 class MockBuzzer : public Buzzer {
2740 public:
2741 MOCK_METHOD(std::unique_ptr<Buzz>, MakeBuzz, (StringPiece text), (override));
2742 MOCK_METHOD(bool, ShareBuzz, (std::unique_ptr<Buzz> buzz, int64_t timestamp),
2743 (override));
2744 };
2745 ```
2746
2747 Now that we have the mock class defined, we can use it in tests. In the
2748 following code examples, we assume that we have defined a `MockBuzzer` object
2749 named `mock_buzzer_`:
2750
2751 ```cpp
2752 MockBuzzer mock_buzzer_;
2753 ```
2754
2755 First let’s see how we can set expectations on the `MakeBuzz()` method, which
2756 returns a `unique_ptr<Buzz>`.
2757
2758 As usual, if you set an expectation without an action (i.e. the `.WillOnce()` or
2759 `.WillRepeatedly()` clause), when that expectation fires, the default action for
2760 that method will be taken. Since `unique_ptr<>` has a default constructor that
2761 returns a null `unique_ptr`, that’s what you’ll get if you don’t specify an
2762 action:
2763
2764 ```cpp
2765 // Use the default action.
2766 EXPECT_CALL(mock_buzzer_, MakeBuzz("hello"));
2767
2768 // Triggers the previous EXPECT_CALL.
2769 EXPECT_EQ(nullptr, mock_buzzer_.MakeBuzz("hello"));
2770 ```
2771
2772 If you are not happy with the default action, you can tweak it as usual; see
2773 [Setting Default Actions](#OnCall).
2774
2775 If you just need to return a pre-defined move-only value, you can use the
2776 `Return(ByMove(...))` action:
2777
2778 ```cpp
2779 // When this fires, the unique_ptr<> specified by ByMove(...) will
2780 // be returned.
2781 EXPECT_CALL(mock_buzzer_, MakeBuzz("world"))
2782 .WillOnce(Return(ByMove(MakeUnique<Buzz>(AccessLevel::kInternal))));
2783
2784 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("world"));
2785 ```
2786
2787 Note that `ByMove()` is essential here - if you drop it, the code won’t compile.
2788
2789 Quiz time! What do you think will happen if a `Return(ByMove(...))` action is
2790 performed more than once (e.g. you write `...
2791 .WillRepeatedly(Return(ByMove(...)));`)? Come think of it, after the first time
2792 the action runs, the source value will be consumed (since it’s a move-only
2793 value), so the next time around, there’s no value to move from -- you’ll get a
2794 run-time error that `Return(ByMove(...))` can only be run once.
2795
2796 If you need your mock method to do more than just moving a pre-defined value,
2797 remember that you can always use a lambda or a callable object, which can do
2798 pretty much anything you want:
2799
2800 ```cpp
2801 EXPECT_CALL(mock_buzzer_, MakeBuzz("x"))
2802 .WillRepeatedly([](StringPiece text) {
2803 return MakeUnique<Buzz>(AccessLevel::kInternal);
2804 });
2805
2806 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x"));
2807 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x"));
2808 ```
2809
2810 Every time this `EXPECT_CALL` fires, a new `unique_ptr<Buzz>` will be created
2811 and returned. You cannot do this with `Return(ByMove(...))`.
2812
2813 That covers returning move-only values; but how do we work with methods
2814 accepting move-only arguments? The answer is that they work normally, although
2815 some actions will not compile when any of method's arguments are move-only. You
2816 can always use `Return`, or a [lambda or functor](#FunctionsAsActions):
2817
2818 ```cpp
2819 using ::testing::Unused;
2820
2821 EXPECT_CALL(mock_buzzer_, ShareBuzz(NotNull(), _)).WillOnce(Return(true));
2822 EXPECT_TRUE(mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal)),
2823 0);
2824
2825 EXPECT_CALL(mock_buzzer_, ShareBuzz(_, _)).WillOnce(
2826 [](std::unique_ptr<Buzz> buzz, Unused) { return buzz != nullptr; });
2827 EXPECT_FALSE(mock_buzzer_.ShareBuzz(nullptr, 0));
2828 ```
2829
2830 Many built-in actions (`WithArgs`, `WithoutArgs`,`DeleteArg`, `SaveArg`, ...)
2831 could in principle support move-only arguments, but the support for this is not
2832 implemented yet. If this is blocking you, please file a bug.
2833
2834 A few actions (e.g. `DoAll`) copy their arguments internally, so they can never
2835 work with non-copyable objects; you'll have to use functors instead.
2836
2837 #### Legacy workarounds for move-only types {#LegacyMoveOnly}
2838
2839 Support for move-only function arguments was only introduced to gMock in April
2840 of 2017. In older code, you may encounter the following workaround for the lack
2841 of this feature (it is no longer necessary - we're including it just for
2842 reference):
2843
2844 ```cpp
2845 class MockBuzzer : public Buzzer {
2846 public:
2847 MOCK_METHOD(bool, DoShareBuzz, (Buzz* buzz, Time timestamp));
2848 bool ShareBuzz(std::unique_ptr<Buzz> buzz, Time timestamp) override {
2849 return DoShareBuzz(buzz.get(), timestamp);
2850 }
2851 };
2852 ```
2853
2854 The trick is to delegate the `ShareBuzz()` method to a mock method (let’s call
2855 it `DoShareBuzz()`) that does not take move-only parameters. Then, instead of
2856 setting expectations on `ShareBuzz()`, you set them on the `DoShareBuzz()` mock
2857 method:
2858
2859 ```cpp
2860 MockBuzzer mock_buzzer_;
2861 EXPECT_CALL(mock_buzzer_, DoShareBuzz(NotNull(), _));
2862
2863 // When one calls ShareBuzz() on the MockBuzzer like this, the call is
2864 // forwarded to DoShareBuzz(), which is mocked. Therefore this statement
2865 // will trigger the above EXPECT_CALL.
2866 mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal), 0);
2867 ```
2868
2869 ### Making the Compilation Faster
2870
2871 Believe it or not, the *vast majority* of the time spent on compiling a mock
2872 class is in generating its constructor and destructor, as they perform
2873 non-trivial tasks (e.g. verification of the expectations). What's more, mock
2874 methods with different signatures have different types and thus their
2875 constructors/destructors need to be generated by the compiler separately. As a
2876 result, if you mock many different types of methods, compiling your mock class
2877 can get really slow.
2878
2879 If you are experiencing slow compilation, you can move the definition of your
2880 mock class' constructor and destructor out of the class body and into a `.cc`
2881 file. This way, even if you `#include` your mock class in N files, the compiler
2882 only needs to generate its constructor and destructor once, resulting in a much
2883 faster compilation.
2884
2885 Let's illustrate the idea using an example. Here's the definition of a mock
2886 class before applying this recipe:
2887
2888 ```cpp
2889 // File mock_foo.h.
2890 ...
2891 class MockFoo : public Foo {
2892 public:
2893 // Since we don't declare the constructor or the destructor,
2894 // the compiler will generate them in every translation unit
2895 // where this mock class is used.
2896
2897 MOCK_METHOD(int, DoThis, (), (override));
2898 MOCK_METHOD(bool, DoThat, (const char* str), (override));
2899 ... more mock methods ...
2900 };
2901 ```
2902
2903 After the change, it would look like:
2904
2905 ```cpp
2906 // File mock_foo.h.
2907 ...
2908 class MockFoo : public Foo {
2909 public:
2910 // The constructor and destructor are declared, but not defined, here.
2911 MockFoo();
2912 virtual ~MockFoo();
2913
2914 MOCK_METHOD(int, DoThis, (), (override));
2915 MOCK_METHOD(bool, DoThat, (const char* str), (override));
2916 ... more mock methods ...
2917 };
2918 ```
2919
2920 and
2921
2922 ```cpp
2923 // File mock_foo.cc.
2924 #include "path/to/mock_foo.h"
2925
2926 // The definitions may appear trivial, but the functions actually do a
2927 // lot of things through the constructors/destructors of the member
2928 // variables used to implement the mock methods.
2929 MockFoo::MockFoo() {}
2930 MockFoo::~MockFoo() {}
2931 ```
2932
2933 ### Forcing a Verification
2934
2935 When it's being destroyed, your friendly mock object will automatically verify
2936 that all expectations on it have been satisfied, and will generate googletest
2937 failures if not. This is convenient as it leaves you with one less thing to
2938 worry about. That is, unless you are not sure if your mock object will be
2939 destroyed.
2940
2941 How could it be that your mock object won't eventually be destroyed? Well, it
2942 might be created on the heap and owned by the code you are testing. Suppose
2943 there's a bug in that code and it doesn't delete the mock object properly - you
2944 could end up with a passing test when there's actually a bug.
2945
2946 Using a heap checker is a good idea and can alleviate the concern, but its
2947 implementation is not 100% reliable. So, sometimes you do want to *force* gMock
2948 to verify a mock object before it is (hopefully) destructed. You can do this
2949 with `Mock::VerifyAndClearExpectations(&mock_object)`:
2950
2951 ```cpp
2952 TEST(MyServerTest, ProcessesRequest) {
2953 using ::testing::Mock;
2954
2955 MockFoo* const foo = new MockFoo;
2956 EXPECT_CALL(*foo, ...)...;
2957 // ... other expectations ...
2958
2959 // server now owns foo.
2960 MyServer server(foo);
2961 server.ProcessRequest(...);
2962
2963 // In case that server's destructor will forget to delete foo,
2964 // this will verify the expectations anyway.
2965 Mock::VerifyAndClearExpectations(foo);
2966 } // server is destroyed when it goes out of scope here.
2967 ```
2968
2969 {: .callout .tip}
2970 **Tip:** The `Mock::VerifyAndClearExpectations()` function returns a `bool` to
2971 indicate whether the verification was successful (`true` for yes), so you can
2972 wrap that function call inside a `ASSERT_TRUE()` if there is no point going
2973 further when the verification has failed.
2974
2975 Do not set new expectations after verifying and clearing a mock after its use.
2976 Setting expectations after code that exercises the mock has undefined behavior.
2977 See [Using Mocks in Tests](gmock_for_dummies.md#using-mocks-in-tests) for more
2978 information.
2979
2980 ### Using Checkpoints {#UsingCheckPoints}
2981
2982 Sometimes you might want to test a mock object's behavior in phases whose sizes
2983 are each manageable, or you might want to set more detailed expectations about
2984 which API calls invoke which mock functions.
2985
2986 A technique you can use is to put the expectations in a sequence and insert
2987 calls to a dummy "checkpoint" function at specific places. Then you can verify
2988 that the mock function calls do happen at the right time. For example, if you
2989 are exercising the code:
2990
2991 ```cpp
2992 Foo(1);
2993 Foo(2);
2994 Foo(3);
2995 ```
2996
2997 and want to verify that `Foo(1)` and `Foo(3)` both invoke `mock.Bar("a")`, but
2998 `Foo(2)` doesn't invoke anything, you can write:
2999
3000 ```cpp
3001 using ::testing::MockFunction;
3002
3003 TEST(FooTest, InvokesBarCorrectly) {
3004 MyMock mock;
3005 // Class MockFunction<F> has exactly one mock method. It is named
3006 // Call() and has type F.
3007 MockFunction<void(string check_point_name)> check;
3008 {
3009 InSequence s;
3010
3011 EXPECT_CALL(mock, Bar("a"));
3012 EXPECT_CALL(check, Call("1"));
3013 EXPECT_CALL(check, Call("2"));
3014 EXPECT_CALL(mock, Bar("a"));
3015 }
3016 Foo(1);
3017 check.Call("1");
3018 Foo(2);
3019 check.Call("2");
3020 Foo(3);
3021 }
3022 ```
3023
3024 The expectation spec says that the first `Bar("a")` call must happen before
3025 checkpoint "1", the second `Bar("a")` call must happen after checkpoint "2", and
3026 nothing should happen between the two checkpoints. The explicit checkpoints make
3027 it clear which `Bar("a")` is called by which call to `Foo()`.
3028
3029 ### Mocking Destructors
3030
3031 Sometimes you want to make sure a mock object is destructed at the right time,
3032 e.g. after `bar->A()` is called but before `bar->B()` is called. We already know
3033 that you can specify constraints on the [order](#OrderedCalls) of mock function
3034 calls, so all we need to do is to mock the destructor of the mock function.
3035
3036 This sounds simple, except for one problem: a destructor is a special function
3037 with special syntax and special semantics, and the `MOCK_METHOD` macro doesn't
3038 work for it:
3039
3040 ```cpp
3041 MOCK_METHOD(void, ~MockFoo, ()); // Won't compile!
3042 ```
3043
3044 The good news is that you can use a simple pattern to achieve the same effect.
3045 First, add a mock function `Die()` to your mock class and call it in the
3046 destructor, like this:
3047
3048 ```cpp
3049 class MockFoo : public Foo {
3050 ...
3051 // Add the following two lines to the mock class.
3052 MOCK_METHOD(void, Die, ());
3053 ~MockFoo() override { Die(); }
3054 };
3055 ```
3056
3057 (If the name `Die()` clashes with an existing symbol, choose another name.) Now,
3058 we have translated the problem of testing when a `MockFoo` object dies to
3059 testing when its `Die()` method is called:
3060
3061 ```cpp
3062 MockFoo* foo = new MockFoo;
3063 MockBar* bar = new MockBar;
3064 ...
3065 {
3066 InSequence s;
3067
3068 // Expects *foo to die after bar->A() and before bar->B().
3069 EXPECT_CALL(*bar, A());
3070 EXPECT_CALL(*foo, Die());
3071 EXPECT_CALL(*bar, B());
3072 }
3073 ```
3074
3075 And that's that.
3076
3077 ### Using gMock and Threads {#UsingThreads}
3078
3079 In a **unit** test, it's best if you could isolate and test a piece of code in a
3080 single-threaded context. That avoids race conditions and dead locks, and makes
3081 debugging your test much easier.
3082
3083 Yet most programs are multi-threaded, and sometimes to test something we need to
3084 pound on it from more than one thread. gMock works for this purpose too.
3085
3086 Remember the steps for using a mock:
3087
3088 1. Create a mock object `foo`.
3089 2. Set its default actions and expectations using `ON_CALL()` and
3090 `EXPECT_CALL()`.
3091 3. The code under test calls methods of `foo`.
3092 4. Optionally, verify and reset the mock.
3093 5. Destroy the mock yourself, or let the code under test destroy it. The
3094 destructor will automatically verify it.
3095
3096 If you follow the following simple rules, your mocks and threads can live
3097 happily together:
3098
3099 * Execute your *test code* (as opposed to the code being tested) in *one*
3100 thread. This makes your test easy to follow.
3101 * Obviously, you can do step #1 without locking.
3102 * When doing step #2 and #5, make sure no other thread is accessing `foo`.
3103 Obvious too, huh?
3104 * #3 and #4 can be done either in one thread or in multiple threads - anyway
3105 you want. gMock takes care of the locking, so you don't have to do any -
3106 unless required by your test logic.
3107
3108 If you violate the rules (for example, if you set expectations on a mock while
3109 another thread is calling its methods), you get undefined behavior. That's not
3110 fun, so don't do it.
3111
3112 gMock guarantees that the action for a mock function is done in the same thread
3113 that called the mock function. For example, in
3114
3115 ```cpp
3116 EXPECT_CALL(mock, Foo(1))
3117 .WillOnce(action1);
3118 EXPECT_CALL(mock, Foo(2))
3119 .WillOnce(action2);
3120 ```
3121
3122 if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, gMock will
3123 execute `action1` in thread 1 and `action2` in thread 2.
3124
3125 gMock does *not* impose a sequence on actions performed in different threads
3126 (doing so may create deadlocks as the actions may need to cooperate). This means
3127 that the execution of `action1` and `action2` in the above example *may*
3128 interleave. If this is a problem, you should add proper synchronization logic to
3129 `action1` and `action2` to make the test thread-safe.
3130
3131 Also, remember that `DefaultValue<T>` is a global resource that potentially
3132 affects *all* living mock objects in your program. Naturally, you won't want to
3133 mess with it from multiple threads or when there still are mocks in action.
3134
3135 ### Controlling How Much Information gMock Prints
3136
3137 When gMock sees something that has the potential of being an error (e.g. a mock
3138 function with no expectation is called, a.k.a. an uninteresting call, which is
3139 allowed but perhaps you forgot to explicitly ban the call), it prints some
3140 warning messages, including the arguments of the function, the return value, and
3141 the stack trace. Hopefully this will remind you to take a look and see if there
3142 is indeed a problem.
3143
3144 Sometimes you are confident that your tests are correct and may not appreciate
3145 such friendly messages. Some other times, you are debugging your tests or
3146 learning about the behavior of the code you are testing, and wish you could
3147 observe every mock call that happens (including argument values, the return
3148 value, and the stack trace). Clearly, one size doesn't fit all.
3149
3150 You can control how much gMock tells you using the `--gmock_verbose=LEVEL`
3151 command-line flag, where `LEVEL` is a string with three possible values:
3152
3153 * `info`: gMock will print all informational messages, warnings, and errors
3154 (most verbose). At this setting, gMock will also log any calls to the
3155 `ON_CALL/EXPECT_CALL` macros. It will include a stack trace in
3156 "uninteresting call" warnings.
3157 * `warning`: gMock will print both warnings and errors (less verbose); it will
3158 omit the stack traces in "uninteresting call" warnings. This is the default.
3159 * `error`: gMock will print errors only (least verbose).
3160
3161 Alternatively, you can adjust the value of that flag from within your tests like
3162 so:
3163
3164 ```cpp
3165 ::testing::FLAGS_gmock_verbose = "error";
3166 ```
3167
3168 If you find gMock printing too many stack frames with its informational or
3169 warning messages, remember that you can control their amount with the
3170 `--gtest_stack_trace_depth=max_depth` flag.
3171
3172 Now, judiciously use the right flag to enable gMock serve you better!
3173
3174 ### Gaining Super Vision into Mock Calls
3175
3176 You have a test using gMock. It fails: gMock tells you some expectations aren't
3177 satisfied. However, you aren't sure why: Is there a typo somewhere in the
3178 matchers? Did you mess up the order of the `EXPECT_CALL`s? Or is the code under
3179 test doing something wrong? How can you find out the cause?
3180
3181 Won't it be nice if you have X-ray vision and can actually see the trace of all
3182 `EXPECT_CALL`s and mock method calls as they are made? For each call, would you
3183 like to see its actual argument values and which `EXPECT_CALL` gMock thinks it
3184 matches? If you still need some help to figure out who made these calls, how
3185 about being able to see the complete stack trace at each mock call?
3186
3187 You can unlock this power by running your test with the `--gmock_verbose=info`
3188 flag. For example, given the test program:
3189
3190 ```cpp
3191 #include "gmock/gmock.h"
3192
3193 using testing::_;
3194 using testing::HasSubstr;
3195 using testing::Return;
3196
3197 class MockFoo {
3198 public:
3199 MOCK_METHOD(void, F, (const string& x, const string& y));
3200 };
3201
3202 TEST(Foo, Bar) {
3203 MockFoo mock;
3204 EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return());
3205 EXPECT_CALL(mock, F("a", "b"));
3206 EXPECT_CALL(mock, F("c", HasSubstr("d")));
3207
3208 mock.F("a", "good");
3209 mock.F("a", "b");
3210 }
3211 ```
3212
3213 if you run it with `--gmock_verbose=info`, you will see this output:
3214
3215 ```shell
3216 [ RUN ] Foo.Bar
3217
3218 foo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked
3219 Stack trace: ...
3220
3221 foo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked
3222 Stack trace: ...
3223
3224 foo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked
3225 Stack trace: ...
3226
3227 foo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))...
3228 Function call: F(@0x7fff7c8dad40"a",@0x7fff7c8dad10"good")
3229 Stack trace: ...
3230
3231 foo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))...
3232 Function call: F(@0x7fff7c8dada0"a",@0x7fff7c8dad70"b")
3233 Stack trace: ...
3234
3235 foo_test.cc:16: Failure
3236 Actual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))...
3237 Expected: to be called once
3238 Actual: never called - unsatisfied and active
3239 [ FAILED ] Foo.Bar
3240 ```
3241
3242 Suppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo and
3243 should actually be `"a"`. With the above message, you should see that the actual
3244 `F("a", "good")` call is matched by the first `EXPECT_CALL`, not the third as
3245 you thought. From that it should be obvious that the third `EXPECT_CALL` is
3246 written wrong. Case solved.
3247
3248 If you are interested in the mock call trace but not the stack traces, you can
3249 combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test
3250 command line.
3251
3252 ### Running Tests in Emacs
3253
3254 If you build and run your tests in Emacs using the `M-x google-compile` command
3255 (as many googletest users do), the source file locations of gMock and googletest
3256 errors will be highlighted. Just press `<Enter>` on one of them and you'll be
3257 taken to the offending line. Or, you can just type `C-x`` to jump to the next
3258 error.
3259
3260 To make it even easier, you can add the following lines to your `~/.emacs` file:
3261
3262 ```text
3263 (global-set-key "\M-m" 'google-compile) ; m is for make
3264 (global-set-key [M-down] 'next-error)
3265 (global-set-key [M-up] '(lambda () (interactive) (next-error -1)))
3266 ```
3267
3268 Then you can type `M-m` to start a build (if you want to run the test as well,
3269 just make sure `foo_test.run` or `runtests` is in the build command you supply
3270 after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors.
3271
3272 ## Extending gMock
3273
3274 ### Writing New Matchers Quickly {#NewMatchers}
3275
3276 {: .callout .warning}
3277 WARNING: gMock does not guarantee when or how many times a matcher will be
3278 invoked. Therefore, all matchers must be functionally pure. See
3279 [this section](#PureMatchers) for more details.
3280
3281 The `MATCHER*` family of macros can be used to define custom matchers easily.
3282 The syntax:
3283
3284 ```cpp
3285 MATCHER(name, description_string_expression) { statements; }
3286 ```
3287
3288 will define a matcher with the given name that executes the statements, which
3289 must return a `bool` to indicate if the match succeeds. Inside the statements,
3290 you can refer to the value being matched by `arg`, and refer to its type by
3291 `arg_type`.
3292
3293 The *description string* is a `string`-typed expression that documents what the
3294 matcher does, and is used to generate the failure message when the match fails.
3295 It can (and should) reference the special `bool` variable `negation`, and should
3296 evaluate to the description of the matcher when `negation` is `false`, or that
3297 of the matcher's negation when `negation` is `true`.
3298
3299 For convenience, we allow the description string to be empty (`""`), in which
3300 case gMock will use the sequence of words in the matcher name as the
3301 description.
3302
3303 For example:
3304
3305 ```cpp
3306 MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; }
3307 ```
3308
3309 allows you to write
3310
3311 ```cpp
3312 // Expects mock_foo.Bar(n) to be called where n is divisible by 7.
3313 EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7()));
3314 ```
3315
3316 or,
3317
3318 ```cpp
3319 using ::testing::Not;
3320 ...
3321 // Verifies that a value is divisible by 7 and the other is not.
3322 EXPECT_THAT(some_expression, IsDivisibleBy7());
3323 EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7()));
3324 ```
3325
3326 If the above assertions fail, they will print something like:
3327
3328 ```shell
3329 Value of: some_expression
3330 Expected: is divisible by 7
3331 Actual: 27
3332 ...
3333 Value of: some_other_expression
3334 Expected: not (is divisible by 7)
3335 Actual: 21
3336 ```
3337
3338 where the descriptions `"is divisible by 7"` and `"not (is divisible by 7)"` are
3339 automatically calculated from the matcher name `IsDivisibleBy7`.
3340
3341 As you may have noticed, the auto-generated descriptions (especially those for
3342 the negation) may not be so great. You can always override them with a `string`
3343 expression of your own:
3344
3345 ```cpp
3346 MATCHER(IsDivisibleBy7,
3347 absl::StrCat(negation ? "isn't" : "is", " divisible by 7")) {
3348 return (arg % 7) == 0;
3349 }
3350 ```
3351
3352 Optionally, you can stream additional information to a hidden argument named
3353 `result_listener` to explain the match result. For example, a better definition
3354 of `IsDivisibleBy7` is:
3355
3356 ```cpp
3357 MATCHER(IsDivisibleBy7, "") {
3358 if ((arg % 7) == 0)
3359 return true;
3360
3361 *result_listener << "the remainder is " << (arg % 7);
3362 return false;
3363 }
3364 ```
3365
3366 With this definition, the above assertion will give a better message:
3367
3368 ```shell
3369 Value of: some_expression
3370 Expected: is divisible by 7
3371 Actual: 27 (the remainder is 6)
3372 ```
3373
3374 You should let `MatchAndExplain()` print *any additional information* that can
3375 help a user understand the match result. Note that it should explain why the
3376 match succeeds in case of a success (unless it's obvious) - this is useful when
3377 the matcher is used inside `Not()`. There is no need to print the argument value
3378 itself, as gMock already prints it for you.
3379
3380 {: .callout .note}
3381 NOTE: The type of the value being matched (`arg_type`) is determined by the
3382 context in which you use the matcher and is supplied to you by the compiler, so
3383 you don't need to worry about declaring it (nor can you). This allows the
3384 matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match
3385 any type where the value of `(arg % 7) == 0` can be implicitly converted to a
3386 `bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an
3387 `int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will
3388 be `unsigned long`; and so on.
3389
3390 ### Writing New Parameterized Matchers Quickly
3391
3392 Sometimes you'll want to define a matcher that has parameters. For that you can
3393 use the macro:
3394
3395 ```cpp
3396 MATCHER_P(name, param_name, description_string) { statements; }
3397 ```
3398
3399 where the description string can be either `""` or a `string` expression that
3400 references `negation` and `param_name`.
3401
3402 For example:
3403
3404 ```cpp
3405 MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
3406 ```
3407
3408 will allow you to write:
3409
3410 ```cpp
3411 EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
3412 ```
3413
3414 which may lead to this message (assuming `n` is 10):
3415
3416 ```shell
3417 Value of: Blah("a")
3418 Expected: has absolute value 10
3419 Actual: -9
3420 ```
3421
3422 Note that both the matcher description and its parameter are printed, making the
3423 message human-friendly.
3424
3425 In the matcher definition body, you can write `foo_type` to reference the type
3426 of a parameter named `foo`. For example, in the body of
3427 `MATCHER_P(HasAbsoluteValue, value)` above, you can write `value_type` to refer
3428 to the type of `value`.
3429
3430 gMock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to `MATCHER_P10` to
3431 support multi-parameter matchers:
3432
3433 ```cpp
3434 MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; }
3435 ```
3436
3437 Please note that the custom description string is for a particular *instance* of
3438 the matcher, where the parameters have been bound to actual values. Therefore
3439 usually you'll want the parameter values to be part of the description. gMock
3440 lets you do that by referencing the matcher parameters in the description string
3441 expression.
3442
3443 For example,
3444
3445 ```cpp
3446 using ::testing::PrintToString;
3447 MATCHER_P2(InClosedRange, low, hi,
3448 absl::StrFormat("%s in range [%s, %s]", negation ? "isn't" : "is",
3449 PrintToString(low), PrintToString(hi))) {
3450 return low <= arg && arg <= hi;
3451 }
3452 ...
3453 EXPECT_THAT(3, InClosedRange(4, 6));
3454 ```
3455
3456 would generate a failure that contains the message:
3457
3458 ```shell
3459 Expected: is in range [4, 6]
3460 ```
3461
3462 If you specify `""` as the description, the failure message will contain the
3463 sequence of words in the matcher name followed by the parameter values printed
3464 as a tuple. For example,
3465
3466 ```cpp
3467 MATCHER_P2(InClosedRange, low, hi, "") { ... }
3468 ...
3469 EXPECT_THAT(3, InClosedRange(4, 6));
3470 ```
3471
3472 would generate a failure that contains the text:
3473
3474 ```shell
3475 Expected: in closed range (4, 6)
3476 ```
3477
3478 For the purpose of typing, you can view
3479
3480 ```cpp
3481 MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
3482 ```
3483
3484 as shorthand for
3485
3486 ```cpp
3487 template <typename p1_type, ..., typename pk_type>
3488 FooMatcherPk<p1_type, ..., pk_type>
3489 Foo(p1_type p1, ..., pk_type pk) { ... }
3490 ```
3491
3492 When you write `Foo(v1, ..., vk)`, the compiler infers the types of the
3493 parameters `v1`, ..., and `vk` for you. If you are not happy with the result of
3494 the type inference, you can specify the types by explicitly instantiating the
3495 template, as in `Foo<long, bool>(5, false)`. As said earlier, you don't get to
3496 (or need to) specify `arg_type` as that's determined by the context in which the
3497 matcher is used.
3498
3499 You can assign the result of expression `Foo(p1, ..., pk)` to a variable of type
3500 `FooMatcherPk<p1_type, ..., pk_type>`. This can be useful when composing
3501 matchers. Matchers that don't have a parameter or have only one parameter have
3502 special types: you can assign `Foo()` to a `FooMatcher`-typed variable, and
3503 assign `Foo(p)` to a `FooMatcherP<p_type>`-typed variable.
3504
3505 While you can instantiate a matcher template with reference types, passing the
3506 parameters by pointer usually makes your code more readable. If, however, you
3507 still want to pass a parameter by reference, be aware that in the failure
3508 message generated by the matcher you will see the value of the referenced object
3509 but not its address.
3510
3511 You can overload matchers with different numbers of parameters:
3512
3513 ```cpp
3514 MATCHER_P(Blah, a, description_string_1) { ... }
3515 MATCHER_P2(Blah, a, b, description_string_2) { ... }
3516 ```
3517
3518 While it's tempting to always use the `MATCHER*` macros when defining a new
3519 matcher, you should also consider implementing the matcher interface directly
3520 instead (see the recipes that follow), especially if you need to use the matcher
3521 a lot. While these approaches require more work, they give you more control on
3522 the types of the value being matched and the matcher parameters, which in
3523 general leads to better compiler error messages that pay off in the long run.
3524 They also allow overloading matchers based on parameter types (as opposed to
3525 just based on the number of parameters).
3526
3527 ### Writing New Monomorphic Matchers
3528
3529 A matcher of argument type `T` implements the matcher interface for `T` and does
3530 two things: it tests whether a value of type `T` matches the matcher, and can
3531 describe what kind of values it matches. The latter ability is used for
3532 generating readable error messages when expectations are violated.
3533
3534 A matcher of `T` must declare a typedef like:
3535
3536 ```cpp
3537 using is_gtest_matcher = void;
3538 ```
3539
3540 and supports the following operations:
3541
3542 ```cpp
3543 // Match a value and optionally explain into an ostream.
3544 bool matched = matcher.MatchAndExplain(value, maybe_os);
3545 // where `value` is of type `T` and
3546 // `maybe_os` is of type `std::ostream*`, where it can be null if the caller
3547 // is not interested in there textual explanation.
3548
3549 matcher.DescribeTo(os);
3550 matcher.DescribeNegationTo(os);
3551 // where `os` is of type `std::ostream*`.
3552 ```
3553
3554 If you need a custom matcher but `Truly()` is not a good option (for example,
3555 you may not be happy with the way `Truly(predicate)` describes itself, or you
3556 may want your matcher to be polymorphic as `Eq(value)` is), you can define a
3557 matcher to do whatever you want in two steps: first implement the matcher
3558 interface, and then define a factory function to create a matcher instance. The
3559 second step is not strictly needed but it makes the syntax of using the matcher
3560 nicer.
3561
3562 For example, you can define a matcher to test whether an `int` is divisible by 7
3563 and then use it like this:
3564
3565 ```cpp
3566 using ::testing::Matcher;
3567
3568 class DivisibleBy7Matcher {
3569 public:
3570 using is_gtest_matcher = void;
3571
3572 bool MatchAndExplain(int n, std::ostream*) const {
3573 return (n % 7) == 0;
3574 }
3575
3576 void DescribeTo(std::ostream* os) const {
3577 *os << "is divisible by 7";
3578 }
3579
3580 void DescribeNegationTo(std::ostream* os) const {
3581 *os << "is not divisible by 7";
3582 }
3583 };
3584
3585 Matcher<int> DivisibleBy7() {
3586 return DivisibleBy7Matcher();
3587 }
3588
3589 ...
3590 EXPECT_CALL(foo, Bar(DivisibleBy7()));
3591 ```
3592
3593 You may improve the matcher message by streaming additional information to the
3594 `os` argument in `MatchAndExplain()`:
3595
3596 ```cpp
3597 class DivisibleBy7Matcher {
3598 public:
3599 bool MatchAndExplain(int n, std::ostream* os) const {
3600 const int remainder = n % 7;
3601 if (remainder != 0 && os != nullptr) {
3602 *os << "the remainder is " << remainder;
3603 }
3604 return remainder == 0;
3605 }
3606 ...
3607 };
3608 ```
3609
3610 Then, `EXPECT_THAT(x, DivisibleBy7());` may generate a message like this:
3611
3612 ```shell
3613 Value of: x
3614 Expected: is divisible by 7
3615 Actual: 23 (the remainder is 2)
3616 ```
3617
3618 {: .callout .tip}
3619 Tip: for convenience, `MatchAndExplain()` can take a `MatchResultListener*`
3620 instead of `std::ostream*`.
3621
3622 ### Writing New Polymorphic Matchers
3623
3624 Expanding what we learned above to *polymorphic* matchers is now just as simple
3625 as adding templates in the right place.
3626
3627 ```cpp
3628
3629 class NotNullMatcher {
3630 public:
3631 using is_gtest_matcher = void;
3632
3633 // To implement a polymorphic matcher, we just need to make MatchAndExplain a
3634 // template on its first argument.
3635
3636 // In this example, we want to use NotNull() with any pointer, so
3637 // MatchAndExplain() accepts a pointer of any type as its first argument.
3638 // In general, you can define MatchAndExplain() as an ordinary method or
3639 // a method template, or even overload it.
3640 template <typename T>
3641 bool MatchAndExplain(T* p, std::ostream*) const {
3642 return p != nullptr;
3643 }
3644
3645 // Describes the property of a value matching this matcher.
3646 void DescribeTo(std::ostream* os) const { *os << "is not NULL"; }
3647
3648 // Describes the property of a value NOT matching this matcher.
3649 void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; }
3650 };
3651
3652 NotNullMatcher NotNull() {
3653 return NotNullMatcher();
3654 }
3655
3656 ...
3657
3658 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
3659 ```
3660
3661 ### Legacy Matcher Implementation
3662
3663 Defining matchers used to be somewhat more complicated, in which it required
3664 several supporting classes and virtual functions. To implement a matcher for
3665 type `T` using the legacy API you have to derive from `MatcherInterface<T>` and
3666 call `MakeMatcher` to construct the object.
3667
3668 The interface looks like this:
3669
3670 ```cpp
3671 class MatchResultListener {
3672 public:
3673 ...
3674 // Streams x to the underlying ostream; does nothing if the ostream
3675 // is NULL.
3676 template <typename T>
3677 MatchResultListener& operator<<(const T& x);
3678
3679 // Returns the underlying ostream.
3680 std::ostream* stream();
3681 };
3682
3683 template <typename T>
3684 class MatcherInterface {
3685 public:
3686 virtual ~MatcherInterface();
3687
3688 // Returns true if and only if the matcher matches x; also explains the match
3689 // result to 'listener'.
3690 virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0;
3691
3692 // Describes this matcher to an ostream.
3693 virtual void DescribeTo(std::ostream* os) const = 0;
3694
3695 // Describes the negation of this matcher to an ostream.
3696 virtual void DescribeNegationTo(std::ostream* os) const;
3697 };
3698 ```
3699
3700 Fortunately, most of the time you can define a polymorphic matcher easily with
3701 the help of `MakePolymorphicMatcher()`. Here's how you can define `NotNull()` as
3702 an example:
3703
3704 ```cpp
3705 using ::testing::MakePolymorphicMatcher;
3706 using ::testing::MatchResultListener;
3707 using ::testing::PolymorphicMatcher;
3708
3709 class NotNullMatcher {
3710 public:
3711 // To implement a polymorphic matcher, first define a COPYABLE class
3712 // that has three members MatchAndExplain(), DescribeTo(), and
3713 // DescribeNegationTo(), like the following.
3714
3715 // In this example, we want to use NotNull() with any pointer, so
3716 // MatchAndExplain() accepts a pointer of any type as its first argument.
3717 // In general, you can define MatchAndExplain() as an ordinary method or
3718 // a method template, or even overload it.
3719 template <typename T>
3720 bool MatchAndExplain(T* p,
3721 MatchResultListener* /* listener */) const {
3722 return p != NULL;
3723 }
3724
3725 // Describes the property of a value matching this matcher.
3726 void DescribeTo(std::ostream* os) const { *os << "is not NULL"; }
3727
3728 // Describes the property of a value NOT matching this matcher.
3729 void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; }
3730 };
3731
3732 // To construct a polymorphic matcher, pass an instance of the class
3733 // to MakePolymorphicMatcher(). Note the return type.
3734 PolymorphicMatcher<NotNullMatcher> NotNull() {
3735 return MakePolymorphicMatcher(NotNullMatcher());
3736 }
3737
3738 ...
3739
3740 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
3741 ```
3742
3743 {: .callout .note}
3744 **Note:** Your polymorphic matcher class does **not** need to inherit from
3745 `MatcherInterface` or any other class, and its methods do **not** need to be
3746 virtual.
3747
3748 Like in a monomorphic matcher, you may explain the match result by streaming
3749 additional information to the `listener` argument in `MatchAndExplain()`.
3750
3751 ### Writing New Cardinalities
3752
3753 A cardinality is used in `Times()` to tell gMock how many times you expect a
3754 call to occur. It doesn't have to be exact. For example, you can say
3755 `AtLeast(5)` or `Between(2, 4)`.
3756
3757 If the [built-in set](gmock_cheat_sheet.md#CardinalityList) of cardinalities
3758 doesn't suit you, you are free to define your own by implementing the following
3759 interface (in namespace `testing`):
3760
3761 ```cpp
3762 class CardinalityInterface {
3763 public:
3764 virtual ~CardinalityInterface();
3765
3766 // Returns true if and only if call_count calls will satisfy this cardinality.
3767 virtual bool IsSatisfiedByCallCount(int call_count) const = 0;
3768
3769 // Returns true if and only if call_count calls will saturate this
3770 // cardinality.
3771 virtual bool IsSaturatedByCallCount(int call_count) const = 0;
3772
3773 // Describes self to an ostream.
3774 virtual void DescribeTo(std::ostream* os) const = 0;
3775 };
3776 ```
3777
3778 For example, to specify that a call must occur even number of times, you can
3779 write
3780
3781 ```cpp
3782 using ::testing::Cardinality;
3783 using ::testing::CardinalityInterface;
3784 using ::testing::MakeCardinality;
3785
3786 class EvenNumberCardinality : public CardinalityInterface {
3787 public:
3788 bool IsSatisfiedByCallCount(int call_count) const override {
3789 return (call_count % 2) == 0;
3790 }
3791
3792 bool IsSaturatedByCallCount(int call_count) const override {
3793 return false;
3794 }
3795
3796 void DescribeTo(std::ostream* os) const {
3797 *os << "called even number of times";
3798 }
3799 };
3800
3801 Cardinality EvenNumber() {
3802 return MakeCardinality(new EvenNumberCardinality);
3803 }
3804
3805 ...
3806 EXPECT_CALL(foo, Bar(3))
3807 .Times(EvenNumber());
3808 ```
3809
3810 ### Writing New Actions Quickly {#QuickNewActions}
3811
3812 If the built-in actions don't work for you, you can easily define your own one.
3813 Just define a functor class with a (possibly templated) call operator, matching
3814 the signature of your action.
3815
3816 ```cpp
3817 struct Increment {
3818 template <typename T>
3819 T operator()(T* arg) {
3820 return ++(*arg);
3821 }
3822 }
3823 ```
3824
3825 The same approach works with stateful functors (or any callable, really):
3826
3827 ```
3828 struct MultiplyBy {
3829 template <typename T>
3830 T operator()(T arg) { return arg * multiplier; }
3831
3832 int multiplier;
3833 }
3834
3835 // Then use:
3836 // EXPECT_CALL(...).WillOnce(MultiplyBy{7});
3837 ```
3838
3839 #### Legacy macro-based Actions
3840
3841 Before C++11, the functor-based actions were not supported; the old way of
3842 writing actions was through a set of `ACTION*` macros. We suggest to avoid them
3843 in new code; they hide a lot of logic behind the macro, potentially leading to
3844 harder-to-understand compiler errors. Nevertheless, we cover them here for
3845 completeness.
3846
3847 By writing
3848
3849 ```cpp
3850 ACTION(name) { statements; }
3851 ```
3852
3853 in a namespace scope (i.e. not inside a class or function), you will define an
3854 action with the given name that executes the statements. The value returned by
3855 `statements` will be used as the return value of the action. Inside the
3856 statements, you can refer to the K-th (0-based) argument of the mock function as
3857 `argK`. For example:
3858
3859 ```cpp
3860 ACTION(IncrementArg1) { return ++(*arg1); }
3861 ```
3862
3863 allows you to write
3864
3865 ```cpp
3866 ... WillOnce(IncrementArg1());
3867 ```
3868
3869 Note that you don't need to specify the types of the mock function arguments.
3870 Rest assured that your code is type-safe though: you'll get a compiler error if
3871 `*arg1` doesn't support the `++` operator, or if the type of `++(*arg1)` isn't
3872 compatible with the mock function's return type.
3873
3874 Another example:
3875
3876 ```cpp
3877 ACTION(Foo) {
3878 (*arg2)(5);
3879 Blah();
3880 *arg1 = 0;
3881 return arg0;
3882 }
3883 ```
3884
3885 defines an action `Foo()` that invokes argument #2 (a function pointer) with 5,
3886 calls function `Blah()`, sets the value pointed to by argument #1 to 0, and
3887 returns argument #0.
3888
3889 For more convenience and flexibility, you can also use the following pre-defined
3890 symbols in the body of `ACTION`:
3891
3892 `argK_type` | The type of the K-th (0-based) argument of the mock function
3893 :-------------- | :-----------------------------------------------------------
3894 `args` | All arguments of the mock function as a tuple
3895 `args_type` | The type of all arguments of the mock function as a tuple
3896 `return_type` | The return type of the mock function
3897 `function_type` | The type of the mock function
3898
3899 For example, when using an `ACTION` as a stub action for mock function:
3900
3901 ```cpp
3902 int DoSomething(bool flag, int* ptr);
3903 ```
3904
3905 we have:
3906
3907 Pre-defined Symbol | Is Bound To
3908 ------------------ | ---------------------------------
3909 `arg0` | the value of `flag`
3910 `arg0_type` | the type `bool`
3911 `arg1` | the value of `ptr`
3912 `arg1_type` | the type `int*`
3913 `args` | the tuple `(flag, ptr)`
3914 `args_type` | the type `std::tuple<bool, int*>`
3915 `return_type` | the type `int`
3916 `function_type` | the type `int(bool, int*)`
3917
3918 #### Legacy macro-based parameterized Actions
3919
3920 Sometimes you'll want to parameterize an action you define. For that we have
3921 another macro
3922
3923 ```cpp
3924 ACTION_P(name, param) { statements; }
3925 ```
3926
3927 For example,
3928
3929 ```cpp
3930 ACTION_P(Add, n) { return arg0 + n; }
3931 ```
3932
3933 will allow you to write
3934
3935 ```cpp
3936 // Returns argument #0 + 5.
3937 ... WillOnce(Add(5));
3938 ```
3939
3940 For convenience, we use the term *arguments* for the values used to invoke the
3941 mock function, and the term *parameters* for the values used to instantiate an
3942 action.
3943
3944 Note that you don't need to provide the type of the parameter either. Suppose
3945 the parameter is named `param`, you can also use the gMock-defined symbol
3946 `param_type` to refer to the type of the parameter as inferred by the compiler.
3947 For example, in the body of `ACTION_P(Add, n)` above, you can write `n_type` for
3948 the type of `n`.
3949
3950 gMock also provides `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter
3951 actions. For example,
3952
3953 ```cpp
3954 ACTION_P2(ReturnDistanceTo, x, y) {
3955 double dx = arg0 - x;
3956 double dy = arg1 - y;
3957 return sqrt(dx*dx + dy*dy);
3958 }
3959 ```
3960
3961 lets you write
3962
3963 ```cpp
3964 ... WillOnce(ReturnDistanceTo(5.0, 26.5));
3965 ```
3966
3967 You can view `ACTION` as a degenerated parameterized action where the number of
3968 parameters is 0.
3969
3970 You can also easily define actions overloaded on the number of parameters:
3971
3972 ```cpp
3973 ACTION_P(Plus, a) { ... }
3974 ACTION_P2(Plus, a, b) { ... }
3975 ```
3976
3977 ### Restricting the Type of an Argument or Parameter in an ACTION
3978
3979 For maximum brevity and reusability, the `ACTION*` macros don't ask you to
3980 provide the types of the mock function arguments and the action parameters.
3981 Instead, we let the compiler infer the types for us.
3982
3983 Sometimes, however, we may want to be more explicit about the types. There are
3984 several tricks to do that. For example:
3985
3986 ```cpp
3987 ACTION(Foo) {
3988 // Makes sure arg0 can be converted to int.
3989 int n = arg0;
3990 ... use n instead of arg0 here ...
3991 }
3992
3993 ACTION_P(Bar, param) {
3994 // Makes sure the type of arg1 is const char*.
3995 ::testing::StaticAssertTypeEq<const char*, arg1_type>();
3996
3997 // Makes sure param can be converted to bool.
3998 bool flag = param;
3999 }
4000 ```
4001
4002 where `StaticAssertTypeEq` is a compile-time assertion in googletest that
4003 verifies two types are the same.
4004
4005 ### Writing New Action Templates Quickly
4006
4007 Sometimes you want to give an action explicit template parameters that cannot be
4008 inferred from its value parameters. `ACTION_TEMPLATE()` supports that and can be
4009 viewed as an extension to `ACTION()` and `ACTION_P*()`.
4010
4011 The syntax:
4012
4013 ```cpp
4014 ACTION_TEMPLATE(ActionName,
4015 HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m),
4016 AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; }
4017 ```
4018
4019 defines an action template that takes *m* explicit template parameters and *n*
4020 value parameters, where *m* is in [1, 10] and *n* is in [0, 10]. `name_i` is the
4021 name of the *i*-th template parameter, and `kind_i` specifies whether it's a
4022 `typename`, an integral constant, or a template. `p_i` is the name of the *i*-th
4023 value parameter.
4024
4025 Example:
4026
4027 ```cpp
4028 // DuplicateArg<k, T>(output) converts the k-th argument of the mock
4029 // function to type T and copies it to *output.
4030 ACTION_TEMPLATE(DuplicateArg,
4031 // Note the comma between int and k:
4032 HAS_2_TEMPLATE_PARAMS(int, k, typename, T),
4033 AND_1_VALUE_PARAMS(output)) {
4034 *output = T(std::get<k>(args));
4035 }
4036 ```
4037
4038 To create an instance of an action template, write:
4039
4040 ```cpp
4041 ActionName<t1, ..., t_m>(v1, ..., v_n)
4042 ```
4043
4044 where the `t`s are the template arguments and the `v`s are the value arguments.
4045 The value argument types are inferred by the compiler. For example:
4046
4047 ```cpp
4048 using ::testing::_;
4049 ...
4050 int n;
4051 EXPECT_CALL(mock, Foo).WillOnce(DuplicateArg<1, unsigned char>(&n));
4052 ```
4053
4054 If you want to explicitly specify the value argument types, you can provide
4055 additional template arguments:
4056
4057 ```cpp
4058 ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n)
4059 ```
4060
4061 where `u_i` is the desired type of `v_i`.
4062
4063 `ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the number of
4064 value parameters, but not on the number of template parameters. Without the
4065 restriction, the meaning of the following is unclear:
4066
4067 ```cpp
4068 OverloadedAction<int, bool>(x);
4069 ```
4070
4071 Are we using a single-template-parameter action where `bool` refers to the type
4072 of `x`, or a two-template-parameter action where the compiler is asked to infer
4073 the type of `x`?
4074
4075 ### Using the ACTION Object's Type
4076
4077 If you are writing a function that returns an `ACTION` object, you'll need to
4078 know its type. The type depends on the macro used to define the action and the
4079 parameter types. The rule is relatively simple:
4080
4081
4082 | Given Definition | Expression | Has Type |
4083 | ----------------------------- | ------------------- | --------------------- |
4084 | `ACTION(Foo)` | `Foo()` | `FooAction` |
4085 | `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` |
4086 | `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` |
4087 | `ACTION_TEMPLATE(Bar, HAS_m_TEMPLATE_PARAMS(...), AND_1_VALUE_PARAMS(p1))` | `Bar<t1, ..., t_m>(int_value)` | `BarActionP<t1, ..., t_m, int>` |
4088 | `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` |
4089 | `ACTION_TEMPLATE(Baz, HAS_m_TEMPLATE_PARAMS(...), AND_2_VALUE_PARAMS(p1, p2))` | `Baz<t1, ..., t_m>(bool_value, int_value)` | `BazActionP2<t1, ..., t_m, bool, int>` |
4090 | ... | ... | ... |
4091
4092
4093 Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`,
4094 and etc) for actions with different numbers of value parameters, or the action
4095 definitions cannot be overloaded on the number of them.
4096
4097 ### Writing New Monomorphic Actions {#NewMonoActions}
4098
4099 While the `ACTION*` macros are very convenient, sometimes they are
4100 inappropriate. For example, despite the tricks shown in the previous recipes,
4101 they don't let you directly specify the types of the mock function arguments and
4102 the action parameters, which in general leads to unoptimized compiler error
4103 messages that can baffle unfamiliar users. They also don't allow overloading
4104 actions based on parameter types without jumping through some hoops.
4105
4106 An alternative to the `ACTION*` macros is to implement
4107 `::testing::ActionInterface<F>`, where `F` is the type of the mock function in
4108 which the action will be used. For example:
4109
4110 ```cpp
4111 template <typename F>
4112 class ActionInterface {
4113 public:
4114 virtual ~ActionInterface();
4115
4116 // Performs the action. Result is the return type of function type
4117 // F, and ArgumentTuple is the tuple of arguments of F.
4118 //
4119
4120 // For example, if F is int(bool, const string&), then Result would
4121 // be int, and ArgumentTuple would be std::tuple<bool, const string&>.
4122 virtual Result Perform(const ArgumentTuple& args) = 0;
4123 };
4124 ```
4125
4126 ```cpp
4127 using ::testing::_;
4128 using ::testing::Action;
4129 using ::testing::ActionInterface;
4130 using ::testing::MakeAction;
4131
4132 typedef int IncrementMethod(int*);
4133
4134 class IncrementArgumentAction : public ActionInterface<IncrementMethod> {
4135 public:
4136 int Perform(const std::tuple<int*>& args) override {
4137 int* p = std::get<0>(args); // Grabs the first argument.
4138 return *p++;
4139 }
4140 };
4141
4142 Action<IncrementMethod> IncrementArgument() {
4143 return MakeAction(new IncrementArgumentAction);
4144 }
4145
4146 ...
4147 EXPECT_CALL(foo, Baz(_))
4148 .WillOnce(IncrementArgument());
4149
4150 int n = 5;
4151 foo.Baz(&n); // Should return 5 and change n to 6.
4152 ```
4153
4154 ### Writing New Polymorphic Actions {#NewPolyActions}
4155
4156 The previous recipe showed you how to define your own action. This is all good,
4157 except that you need to know the type of the function in which the action will
4158 be used. Sometimes that can be a problem. For example, if you want to use the
4159 action in functions with *different* types (e.g. like `Return()` and
4160 `SetArgPointee()`).
4161
4162 If an action can be used in several types of mock functions, we say it's
4163 *polymorphic*. The `MakePolymorphicAction()` function template makes it easy to
4164 define such an action:
4165
4166 ```cpp
4167 namespace testing {
4168 template <typename Impl>
4169 PolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl);
4170 } // namespace testing
4171 ```
4172
4173 As an example, let's define an action that returns the second argument in the
4174 mock function's argument list. The first step is to define an implementation
4175 class:
4176
4177 ```cpp
4178 class ReturnSecondArgumentAction {
4179 public:
4180 template <typename Result, typename ArgumentTuple>
4181 Result Perform(const ArgumentTuple& args) const {
4182 // To get the i-th (0-based) argument, use std::get(args).
4183 return std::get<1>(args);
4184 }
4185 };
4186 ```
4187
4188 This implementation class does *not* need to inherit from any particular class.
4189 What matters is that it must have a `Perform()` method template. This method
4190 template takes the mock function's arguments as a tuple in a **single**
4191 argument, and returns the result of the action. It can be either `const` or not,
4192 but must be invocable with exactly one template argument, which is the result
4193 type. In other words, you must be able to call `Perform<R>(args)` where `R` is
4194 the mock function's return type and `args` is its arguments in a tuple.
4195
4196 Next, we use `MakePolymorphicAction()` to turn an instance of the implementation
4197 class into the polymorphic action we need. It will be convenient to have a
4198 wrapper for this:
4199
4200 ```cpp
4201 using ::testing::MakePolymorphicAction;
4202 using ::testing::PolymorphicAction;
4203
4204 PolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() {
4205 return MakePolymorphicAction(ReturnSecondArgumentAction());
4206 }
4207 ```
4208
4209 Now, you can use this polymorphic action the same way you use the built-in ones:
4210
4211 ```cpp
4212 using ::testing::_;
4213
4214 class MockFoo : public Foo {
4215 public:
4216 MOCK_METHOD(int, DoThis, (bool flag, int n), (override));
4217 MOCK_METHOD(string, DoThat, (int x, const char* str1, const char* str2),
4218 (override));
4219 };
4220
4221 ...
4222 MockFoo foo;
4223 EXPECT_CALL(foo, DoThis).WillOnce(ReturnSecondArgument());
4224 EXPECT_CALL(foo, DoThat).WillOnce(ReturnSecondArgument());
4225 ...
4226 foo.DoThis(true, 5); // Will return 5.
4227 foo.DoThat(1, "Hi", "Bye"); // Will return "Hi".
4228 ```
4229
4230 ### Teaching gMock How to Print Your Values
4231
4232 When an uninteresting or unexpected call occurs, gMock prints the argument
4233 values and the stack trace to help you debug. Assertion macros like
4234 `EXPECT_THAT` and `EXPECT_EQ` also print the values in question when the
4235 assertion fails. gMock and googletest do this using googletest's user-extensible
4236 value printer.
4237
4238 This printer knows how to print built-in C++ types, native arrays, STL
4239 containers, and any type that supports the `<<` operator. For other types, it
4240 prints the raw bytes in the value and hopes that you the user can figure it out.
4241 [The GoogleTest advanced guide](advanced.md#teaching-googletest-how-to-print-your-values)
4242 explains how to extend the printer to do a better job at printing your
4243 particular type than to dump the bytes.
4244
4245 ## Useful Mocks Created Using gMock
4246
4247 <!--#include file="includes/g3_testing_LOGs.md"-->
4248 <!--#include file="includes/g3_mock_callbacks.md"-->
4249
4250 ### Mock std::function {#MockFunction}
4251
4252 `std::function` is a general function type introduced in C++11. It is a
4253 preferred way of passing callbacks to new interfaces. Functions are copiable,
4254 and are not usually passed around by pointer, which makes them tricky to mock.
4255 But fear not - `MockFunction` can help you with that.
4256
4257 `MockFunction<R(T1, ..., Tn)>` has a mock method `Call()` with the signature:
4258
4259 ```cpp
4260 R Call(T1, ..., Tn);
4261 ```
4262
4263 It also has a `AsStdFunction()` method, which creates a `std::function` proxy
4264 forwarding to Call:
4265
4266 ```cpp
4267 std::function<R(T1, ..., Tn)> AsStdFunction();
4268 ```
4269
4270 To use `MockFunction`, first create `MockFunction` object and set up
4271 expectations on its `Call` method. Then pass proxy obtained from
4272 `AsStdFunction()` to the code you are testing. For example:
4273
4274 ```cpp
4275 TEST(FooTest, RunsCallbackWithBarArgument) {
4276 // 1. Create a mock object.
4277 MockFunction<int(string)> mock_function;
4278
4279 // 2. Set expectations on Call() method.
4280 EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1));
4281
4282 // 3. Exercise code that uses std::function.
4283 Foo(mock_function.AsStdFunction());
4284 // Foo's signature can be either of:
4285 // void Foo(const std::function<int(string)>& fun);
4286 // void Foo(std::function<int(string)> fun);
4287
4288 // 4. All expectations will be verified when mock_function
4289 // goes out of scope and is destroyed.
4290 }
4291 ```
4292
4293 Remember that function objects created with `AsStdFunction()` are just
4294 forwarders. If you create multiple of them, they will share the same set of
4295 expectations.
4296
4297 Although `std::function` supports unlimited number of arguments, `MockFunction`
4298 implementation is limited to ten. If you ever hit that limit... well, your
4299 callback has bigger problems than being mockable. :-)