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
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.
13 ## Creating Mock Classes
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:
21 MOCK_METHOD(ReturnType, MethodName, (Args...));
22 MOCK_METHOD(ReturnType, MethodName, (Args...), (Specs...));
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
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
34 * **`noexcept`** - Marks the method with `noexcept`. Required if overriding a
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(&&)`.
42 ### Dealing with unprotected commas
44 Unprotected commas, i.e. commas which are not surrounded by parentheses, prevent
45 `MOCK_METHOD` from parsing its arguments correctly:
51 MOCK_METHOD(std::pair<bool, int>, GetPair, ()); // Won't compile!
52 MOCK_METHOD(bool, CheckMap, (std::map<int, double>, bool)); // Won't compile!
56 Solution 1 - wrap with parentheses:
62 MOCK_METHOD((std::pair<bool, int>), GetPair, ());
63 MOCK_METHOD(bool, CheckMap, ((std::map<int, double>), bool));
67 Note that wrapping a return or argument type with parentheses is, in general,
68 invalid C++. `MOCK_METHOD` removes the parentheses.
70 Solution 2 - define an alias:
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));
83 ### Mocking Private or Protected Methods
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:
96 virtual bool Transform(Gadget* g) = 0;
99 virtual void Resume();
102 virtual int GetTimeOut();
105 class MockFoo : public Foo {
108 MOCK_METHOD(bool, Transform, (Gadget* g), (override));
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));
117 ### Mocking Overloaded Methods
119 You can mock overloaded functions as usual. No special attention is required:
125 // Must be virtual as we'll inherit from Foo.
128 // Overloaded on the types and/or numbers of arguments.
129 virtual int Add(Element x);
130 virtual int Add(int times, Element x);
132 // Overloaded on the const-ness of this object.
133 virtual Bar& GetBar();
134 virtual const Bar& GetBar() const;
137 class MockFoo : public Foo {
139 MOCK_METHOD(int, Add, (Element x), (override));
140 MOCK_METHOD(int, Add, (int times, Element x), (override));
142 MOCK_METHOD(Bar&, GetBar, (), (override));
143 MOCK_METHOD(const Bar&, GetBar, (), (const, override));
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:
153 class MockFoo : public Foo {
156 MOCK_METHOD(int, Add, (Element x), (override));
157 // We don't want to mock int Add(int times, Element x);
162 ### Mocking Class Templates
164 You can mock class templates just like any class.
167 template <typename Elem>
168 class StackInterface {
170 // Must be virtual as we'll inherit from StackInterface.
171 virtual ~StackInterface();
173 virtual int GetSize() const = 0;
174 virtual void Push(const Elem& x) = 0;
177 template <typename Elem>
178 class MockStack : public StackInterface<Elem> {
180 MOCK_METHOD(int, GetSize, (), (override));
181 MOCK_METHOD(void, Push, (const Elem& x), (override));
185 ### Mocking Non-virtual Methods {#MockingNonVirtualMethods}
187 gMock can mock non-virtual functions to be used in Hi-perf dependency injection.
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`):
195 // A simple packet stream class. None of its members is virtual.
196 class ConcretePacketStream {
198 void AppendPacket(Packet* new_packet);
199 const Packet* GetPacket(size_t packet_number) const;
200 size_t NumberOfPackets() const;
204 // A mock packet stream class. It inherits from no other, but defines
205 // GetPacket() and NumberOfPackets().
206 class MockPacketStream {
208 MOCK_METHOD(const Packet*, GetPacket, (size_t packet_number), (const));
209 MOCK_METHOD(size_t, NumberOfPackets, (), (const));
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.
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).
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:
229 template <class PacketStream>
230 void CreateConnection(PacketStream* stream) { ... }
232 template <class PacketStream>
235 void ReadPackets(PacketStream* stream, size_t packet_num);
239 Then you can use `CreateConnection<ConcretePacketStream>()` and
240 `PacketReader<ConcretePacketStream>` in production code, and use
241 `CreateConnection<MockPacketStream>()` and `PacketReader<MockPacketStream>` in
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 ...
252 ### Mocking Free Functions
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
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:
262 class FileInterface {
265 virtual bool Open(const char* path, const char* mode) = 0;
268 class File : public FileInterface {
271 bool Open(const char* path, const char* mode) override {
272 return OpenFile(path, mode);
277 Your code should talk to `FileInterface` to open a file. Now it's easy to mock
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.
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).
288 ### Old-Style `MOCK_METHODn` Macros
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
296 The macros in the `MOCK_METHODn` family differ from `MOCK_METHOD`:
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.
306 Old macros and their new equivalents:
309 <tr><th colspan=2>Simple</th></tr>
312 <td><code>MOCK_METHOD1(Foo, bool(int))</code></td>
316 <td><code>MOCK_METHOD(bool, Foo, (int))</code></td>
319 <tr><th colspan=2>Const Method</th></tr>
322 <td><code>MOCK_CONST_METHOD1(Foo, bool(int))</code></td>
326 <td><code>MOCK_METHOD(bool, Foo, (int), (const))</code></td>
329 <tr><th colspan=2>Method in a Class Template</th></tr>
332 <td><code>MOCK_METHOD1_T(Foo, bool(int))</code></td>
336 <td><code>MOCK_METHOD(bool, Foo, (int))</code></td>
339 <tr><th colspan=2>Const Method in a Class Template</th></tr>
342 <td><code>MOCK_CONST_METHOD1_T(Foo, bool(int))</code></td>
346 <td><code>MOCK_METHOD(bool, Foo, (int), (const))</code></td>
349 <tr><th colspan=2>Method with Call Type</th></tr>
352 <td><code>MOCK_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
356 <td><code>MOCK_METHOD(bool, Foo, (int), (Calltype(STDMETHODCALLTYPE)))</code></td>
359 <tr><th colspan=2>Const Method with Call Type</th></tr>
362 <td><code>MOCK_CONST_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
366 <td><code>MOCK_METHOD(bool, Foo, (int), (const, Calltype(STDMETHODCALLTYPE)))</code></td>
369 <tr><th colspan=2>Method with Call Type in a Class Template</th></tr>
372 <td><code>MOCK_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
376 <td><code>MOCK_METHOD(bool, Foo, (int), (Calltype(STDMETHODCALLTYPE)))</code></td>
379 <tr><th colspan=2>Const Method with Call Type in a Class Template</th></tr>
382 <td><code>MOCK_CONST_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td>
386 <td><code>MOCK_METHOD(bool, Foo, (int), (const, Calltype(STDMETHODCALLTYPE)))</code></td>
390 ### The Nice, the Strict, and the Naggy {#NiceStrictNaggy}
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.
397 However, sometimes you may want to ignore these uninteresting calls, and
398 sometimes you may want to treat them as errors. gMock lets you make the decision
399 on a per-mock-object basis.
401 Suppose your test uses a mock class `MockFoo`:
406 EXPECT_CALL(mock_foo, DoThis());
407 ... code that uses mock_foo ...
411 If a method of `mock_foo` other than `DoThis()` is called, you will get a
412 warning. However, if you rewrite your test to use `NiceMock<MockFoo>` instead,
413 you can suppress the warning:
416 using ::testing::NiceMock;
419 NiceMock<MockFoo> mock_foo;
420 EXPECT_CALL(mock_foo, DoThis());
421 ... code that uses mock_foo ...
425 `NiceMock<MockFoo>` is a subclass of `MockFoo`, so it can be used wherever
426 `MockFoo` is accepted.
428 It also works if `MockFoo`'s constructor takes some arguments, as
429 `NiceMock<MockFoo>` "inherits" `MockFoo`'s constructors:
432 using ::testing::NiceMock;
435 NiceMock<MockFoo> mock_foo(5, "hi"); // Calls MockFoo(5, "hi").
436 EXPECT_CALL(mock_foo, DoThis());
437 ... code that uses mock_foo ...
441 The usage of `StrictMock` is similar, except that it makes all uninteresting
445 using ::testing::StrictMock;
448 StrictMock<MockFoo> mock_foo;
449 EXPECT_CALL(mock_foo, DoThis());
450 ... code that uses mock_foo ...
452 // The test will fail if a method of mock_foo other than DoThis()
458 NOTE: `NiceMock` and `StrictMock` only affects *uninteresting* calls (calls of
459 *methods* with no expectations); they do not affect *unexpected* calls (calls of
460 methods with expectations, but they don't match). See
461 [Understanding Uninteresting vs Unexpected Calls](#uninteresting-vs-unexpected).
463 There are some caveats though (sadly they are side effects of C++'s
466 1. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` only work for mock methods
467 defined using the `MOCK_METHOD` macro **directly** in the `MockFoo` class.
468 If a mock method is defined in a **base class** of `MockFoo`, the "nice" or
469 "strict" modifier may not affect it, depending on the compiler. In
470 particular, nesting `NiceMock` and `StrictMock` (e.g.
471 `NiceMock<StrictMock<MockFoo> >`) is **not** supported.
472 2. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` may not work correctly if the
473 destructor of `MockFoo` is not virtual. We would like to fix this, but it
474 requires cleaning up existing tests.
476 Finally, you should be **very cautious** about when to use naggy or strict
477 mocks, as they tend to make tests more brittle and harder to maintain. When you
478 refactor your code without changing its externally visible behavior, ideally you
479 shouldn't need to update any tests. If your code interacts with a naggy mock,
480 however, you may start to get spammed with warnings as the result of your
481 change. Worse, if your code interacts with a strict mock, your tests may start
482 to fail and you'll be forced to fix them. Our general recommendation is to use
483 nice mocks (not yet the default) most of the time, use naggy mocks (the current
484 default) when developing or debugging tests, and use strict mocks only as the
487 ### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces}
489 Sometimes a method has a long list of arguments that is mostly uninteresting.
496 virtual void send(LogSeverity severity, const char* full_filename,
497 const char* base_filename, int line,
498 const struct tm* tm_time,
499 const char* message, size_t message_len) = 0;
503 This method's argument list is lengthy and hard to work with (the `message`
504 argument is not even 0-terminated). If we mock it as is, using the mock will be
505 awkward. If, however, we try to simplify this interface, we'll need to fix all
506 clients depending on it, which is often infeasible.
508 The trick is to redispatch the method in the mock class:
511 class ScopedMockLog : public LogSink {
514 void send(LogSeverity severity, const char* full_filename,
515 const char* base_filename, int line, const tm* tm_time,
516 const char* message, size_t message_len) override {
517 // We are only interested in the log severity, full file name, and
519 Log(severity, full_filename, std::string(message, message_len));
522 // Implements the mock method:
524 // void Log(LogSeverity severity,
525 // const string& file_path,
526 // const string& message);
527 MOCK_METHOD(void, Log,
528 (LogSeverity severity, const string& file_path,
529 const string& message));
533 By defining a new mock method with a trimmed argument list, we make the mock
534 class more user-friendly.
536 This technique may also be applied to make overloaded methods more amenable to
537 mocking. For example, when overloads have been used to implement default
541 class MockTurtleFactory : public TurtleFactory {
543 Turtle* MakeTurtle(int length, int weight) override { ... }
544 Turtle* MakeTurtle(int length, int weight, int speed) override { ... }
546 // the above methods delegate to this one:
547 MOCK_METHOD(Turtle*, DoMakeTurtle, ());
551 This allows tests that don't care which overload was invoked to avoid specifying
555 ON_CALL(factory, DoMakeTurtle)
556 .WillByDefault(Return(MakeMockTurtle()));
559 ### Alternative to Mocking Concrete Classes
561 Often you may find yourself using classes that don't implement interfaces. In
562 order to test your code that uses such a class (let's call it `Concrete`), you
563 may be tempted to make the methods of `Concrete` virtual and then mock it.
567 Making a non-virtual function virtual is a big decision. It creates an extension
568 point where subclasses can tweak your class' behavior. This weakens your control
569 on the class because now it's harder to maintain the class invariants. You
570 should make a function virtual only when there is a valid reason for a subclass
573 Mocking concrete classes directly is problematic as it creates a tight coupling
574 between the class and the tests - any small change in the class may invalidate
575 your tests and make test maintenance a pain.
577 To avoid such problems, many programmers have been practicing "coding to
578 interfaces": instead of talking to the `Concrete` class, your code would define
579 an interface and talk to it. Then you implement that interface as an adaptor on
580 top of `Concrete`. In tests, you can easily mock that interface to observe how
583 This technique incurs some overhead:
585 * You pay the cost of virtual function calls (usually not a problem).
586 * There is more abstraction for the programmers to learn.
588 However, it can also bring significant benefits in addition to better
591 * `Concrete`'s API may not fit your problem domain very well, as you may not
592 be the only client it tries to serve. By designing your own interface, you
593 have a chance to tailor it to your need - you may add higher-level
594 functionalities, rename stuff, etc instead of just trimming the class. This
595 allows you to write your code (user of the interface) in a more natural way,
596 which means it will be more readable, more maintainable, and you'll be more
598 * If `Concrete`'s implementation ever has to change, you don't have to rewrite
599 everywhere it is used. Instead, you can absorb the change in your
600 implementation of the interface, and your other code and tests will be
601 insulated from this change.
603 Some people worry that if everyone is practicing this technique, they will end
604 up writing lots of redundant code. This concern is totally understandable.
605 However, there are two reasons why it may not be the case:
607 * Different projects may need to use `Concrete` in different ways, so the best
608 interfaces for them will be different. Therefore, each of them will have its
609 own domain-specific interface on top of `Concrete`, and they will not be the
611 * If enough projects want to use the same interface, they can always share it,
612 just like they have been sharing `Concrete`. You can check in the interface
613 and the adaptor somewhere near `Concrete` (perhaps in a `contrib`
614 sub-directory) and let many projects use it.
616 You need to weigh the pros and cons carefully for your particular problem, but
617 I'd like to assure you that the Java community has been practicing this for a
618 long time and it's a proven effective technique applicable in a wide variety of
621 ### Delegating Calls to a Fake {#DelegatingToFake}
623 Some times you have a non-trivial fake implementation of an interface. For
630 virtual char DoThis(int n) = 0;
631 virtual void DoThat(const char* s, int* p) = 0;
634 class FakeFoo : public Foo {
636 char DoThis(int n) override {
637 return (n > 0) ? '+' :
641 void DoThat(const char* s, int* p) override {
647 Now you want to mock this interface such that you can set expectations on it.
648 However, you also want to use `FakeFoo` for the default behavior, as duplicating
649 it in the mock object is, well, a lot of work.
651 When you define the mock class using gMock, you can have it delegate its default
652 action to a fake class you already have, using this pattern:
655 class MockFoo : public Foo {
657 // Normal mock method definitions using gMock.
658 MOCK_METHOD(char, DoThis, (int n), (override));
659 MOCK_METHOD(void, DoThat, (const char* s, int* p), (override));
661 // Delegates the default actions of the methods to a FakeFoo object.
662 // This must be called *before* the custom ON_CALL() statements.
663 void DelegateToFake() {
664 ON_CALL(*this, DoThis).WillByDefault([this](int n) {
665 return fake_.DoThis(n);
667 ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) {
673 FakeFoo fake_; // Keeps an instance of the fake in the mock.
677 With that, you can use `MockFoo` in your tests as usual. Just remember that if
678 you don't explicitly set an action in an `ON_CALL()` or `EXPECT_CALL()`, the
679 fake will be called upon to do it.:
687 foo.DelegateToFake(); // Enables the fake for delegation.
689 // Put your ON_CALL(foo, ...)s here, if any.
691 // No action specified, meaning to use the default action.
692 EXPECT_CALL(foo, DoThis(5));
693 EXPECT_CALL(foo, DoThat(_, _));
696 EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked.
697 foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked.
704 * If you want, you can still override the default action by providing your own
705 `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`.
706 * In `DelegateToFake()`, you only need to delegate the methods whose fake
707 implementation you intend to use.
709 * The general technique discussed here works for overloaded methods, but
710 you'll need to tell the compiler which version you mean. To disambiguate a
711 mock function (the one you specify inside the parentheses of `ON_CALL()`),
712 use [this technique](#SelectOverload); to disambiguate a fake function (the
713 one you place inside `Invoke()`), use a `static_cast` to specify the
714 function's type. For instance, if class `Foo` has methods `char DoThis(int
715 n)` and `bool DoThis(double x) const`, and you want to invoke the latter,
716 you need to write `Invoke(&fake_, static_cast<bool (FakeFoo::*)(double)
717 const>(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)`
718 (The strange-looking thing inside the angled brackets of `static_cast` is
719 the type of a function pointer to the second `DoThis()` method.).
721 * Having to mix a mock and a fake is often a sign of something gone wrong.
722 Perhaps you haven't got used to the interaction-based way of testing yet. Or
723 perhaps your interface is taking on too many roles and should be split up.
724 Therefore, **don't abuse this**. We would only recommend to do it as an
725 intermediate step when you are refactoring your code.
727 Regarding the tip on mixing a mock and a fake, here's an example on why it may
728 be a bad sign: Suppose you have a class `System` for low-level system
729 operations. In particular, it does file and I/O operations. And suppose you want
730 to test how your code uses `System` to do I/O, and you just want the file
731 operations to work normally. If you mock out the entire `System` class, you'll
732 have to provide a fake implementation for the file operation part, which
733 suggests that `System` is taking on too many roles.
735 Instead, you can define a `FileOps` interface and an `IOOps` interface and split
736 `System`'s functionalities into the two. Then you can mock `IOOps` without
739 ### Delegating Calls to a Real Object
741 When using testing doubles (mocks, fakes, stubs, and etc), sometimes their
742 behaviors will differ from those of the real objects. This difference could be
743 either intentional (as in simulating an error such that you can test the error
744 handling code) or unintentional. If your mocks have different behaviors than the
745 real objects by mistake, you could end up with code that passes the tests but
748 You can use the *delegating-to-real* technique to ensure that your mock has the
749 same behavior as the real object while retaining the ability to validate calls.
750 This technique is very similar to the [delegating-to-fake](#DelegatingToFake)
751 technique, the difference being that we use a real object instead of a fake.
755 using ::testing::AtLeast;
757 class MockFoo : public Foo {
760 // By default, all calls are delegated to the real object.
761 ON_CALL(*this, DoThis).WillByDefault([this](int n) {
762 return real_.DoThis(n);
764 ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) {
769 MOCK_METHOD(char, DoThis, ...);
770 MOCK_METHOD(void, DoThat, ...);
778 EXPECT_CALL(mock, DoThis())
780 EXPECT_CALL(mock, DoThat("Hi"))
782 ... use mock in test ...
785 With this, gMock will verify that your code made the right calls (with the right
786 arguments, in the right order, called the right number of times, etc), and a
787 real object will answer the calls (so the behavior will be the same as in
788 production). This gives you the best of both worlds.
790 ### Delegating Calls to a Parent Class
792 Ideally, you should code to interfaces, whose methods are all pure virtual. In
793 reality, sometimes you do need to mock a virtual method that is not pure (i.e,
794 it already has an implementation). For example:
801 virtual void Pure(int n) = 0;
802 virtual int Concrete(const char* str) { ... }
805 class MockFoo : public Foo {
807 // Mocking a pure method.
808 MOCK_METHOD(void, Pure, (int n), (override));
809 // Mocking a concrete method. Foo::Concrete() is shadowed.
810 MOCK_METHOD(int, Concrete, (const char* str), (override));
814 Sometimes you may want to call `Foo::Concrete()` instead of
815 `MockFoo::Concrete()`. Perhaps you want to do it as part of a stub action, or
816 perhaps your test doesn't need to mock `Concrete()` at all (but it would be
817 oh-so painful to have to define a new mock class whenever you don't need to mock
820 You can call `Foo::Concrete()` inside an action by:
824 EXPECT_CALL(foo, Concrete).WillOnce([&foo](const char* str) {
825 return foo.Foo::Concrete(str);
829 or tell the mock object that you don't want to mock `Concrete()`:
833 ON_CALL(foo, Concrete).WillByDefault([&foo](const char* str) {
834 return foo.Foo::Concrete(str);
838 (Why don't we just write `{ return foo.Concrete(str); }`? If you do that,
839 `MockFoo::Concrete()` will be called (and cause an infinite recursion) since
840 `Foo::Concrete()` is virtual. That's just how C++ works.)
844 ### Matching Argument Values Exactly
846 You can specify exactly which arguments a mock method is expecting:
849 using ::testing::Return;
851 EXPECT_CALL(foo, DoThis(5))
852 .WillOnce(Return('a'));
853 EXPECT_CALL(foo, DoThat("Hello", bar));
856 ### Using Simple Matchers
858 You can use matchers to match arguments that have a certain property:
861 using ::testing::NotNull;
862 using ::testing::Return;
864 EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5.
865 .WillOnce(Return('a'));
866 EXPECT_CALL(foo, DoThat("Hello", NotNull()));
867 // The second argument must not be NULL.
870 A frequently used matcher is `_`, which matches anything:
873 EXPECT_CALL(foo, DoThat(_, NotNull()));
876 ### Combining Matchers {#CombiningMatchers}
878 You can build complex matchers from existing ones using `AllOf()`,
879 `AllOfArray()`, `AnyOf()`, `AnyOfArray()` and `Not()`:
882 using ::testing::AllOf;
884 using ::testing::HasSubstr;
886 using ::testing::Not;
888 // The argument must be > 5 and != 10.
889 EXPECT_CALL(foo, DoThis(AllOf(Gt(5),
892 // The first argument must not contain sub-string "blah".
893 EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")),
897 Matchers are function objects, and parametrized matchers can be composed just
898 like any other function. However because their types can be long and rarely
899 provide meaningful information, it can be easier to express them with C++14
900 generic lambdas to avoid specifying types. For example,
903 using ::testing::Contains;
904 using ::testing::Property;
906 inline constexpr auto HasFoo = [](const auto& f) {
907 return Property(&MyClass::foo, Contains(f));
910 EXPECT_THAT(x, HasFoo("blah"));
913 ### Casting Matchers {#SafeMatcherCast}
915 gMock matchers are statically typed, meaning that the compiler can catch your
916 mistake if you use a matcher of the wrong type (for example, if you use `Eq(5)`
917 to match a `string` argument). Good for you!
919 Sometimes, however, you know what you're doing and want the compiler to give you
920 some slack. One example is that you have a matcher for `long` and the argument
921 you want to match is `int`. While the two types aren't exactly the same, there
922 is nothing really wrong with using a `Matcher<long>` to match an `int` - after
923 all, we can first convert the `int` argument to a `long` losslessly before
924 giving it to the matcher.
926 To support this need, gMock gives you the `SafeMatcherCast<T>(m)` function. It
927 casts a matcher `m` to type `Matcher<T>`. To ensure safety, gMock checks that
928 (let `U` be the type `m` accepts :
930 1. Type `T` can be *implicitly* cast to type `U`;
931 2. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and
932 floating-point numbers), the conversion from `T` to `U` is not lossy (in
933 other words, any value representable by `T` can also be represented by `U`);
935 3. When `U` is a reference, `T` must also be a reference (as the underlying
936 matcher may be interested in the address of the `U` value).
938 The code won't compile if any of these conditions isn't met.
943 using ::testing::SafeMatcherCast;
945 // A base class and a child class.
947 class Derived : public Base { ... };
949 class MockFoo : public Foo {
951 MOCK_METHOD(void, DoThis, (Derived* derived), (override));
956 // m is a Matcher<Base*> we got from somewhere.
957 EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m)));
960 If you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar function
961 `MatcherCast<T>(m)`. The difference is that `MatcherCast` works as long as you
962 can `static_cast` type `T` to type `U`.
964 `MatcherCast` essentially lets you bypass C++'s type system (`static_cast` isn't
965 always safe as it could throw away information, for example), so be careful not
968 ### Selecting Between Overloaded Functions {#SelectOverload}
970 If you expect an overloaded function to be called, the compiler may need some
971 help on which overloaded version it is.
973 To disambiguate functions overloaded on the const-ness of this object, use the
974 `Const()` argument wrapper.
977 using ::testing::ReturnRef;
979 class MockFoo : public Foo {
981 MOCK_METHOD(Bar&, GetBar, (), (override));
982 MOCK_METHOD(const Bar&, GetBar, (), (const, override));
988 EXPECT_CALL(foo, GetBar()) // The non-const GetBar().
989 .WillOnce(ReturnRef(bar1));
990 EXPECT_CALL(Const(foo), GetBar()) // The const GetBar().
991 .WillOnce(ReturnRef(bar2));
994 (`Const()` is defined by gMock and returns a `const` reference to its argument.)
996 To disambiguate overloaded functions with the same number of arguments but
997 different argument types, you may need to specify the exact type of a matcher,
998 either by wrapping your matcher in `Matcher<type>()`, or using a matcher whose
999 type is fixed (`TypedEq<type>`, `An<type>()`, etc):
1002 using ::testing::An;
1003 using ::testing::Matcher;
1004 using ::testing::TypedEq;
1006 class MockPrinter : public Printer {
1008 MOCK_METHOD(void, Print, (int n), (override));
1009 MOCK_METHOD(void, Print, (char c), (override));
1012 TEST(PrinterTest, Print) {
1013 MockPrinter printer;
1015 EXPECT_CALL(printer, Print(An<int>())); // void Print(int);
1016 EXPECT_CALL(printer, Print(Matcher<int>(Lt(5)))); // void Print(int);
1017 EXPECT_CALL(printer, Print(TypedEq<char>('a'))); // void Print(char);
1025 ### Performing Different Actions Based on the Arguments
1027 When a mock method is called, the *last* matching expectation that's still
1028 active will be selected (think "newer overrides older"). So, you can make a
1029 method do different things depending on its argument values like this:
1033 using ::testing::Lt;
1034 using ::testing::Return;
1036 // The default case.
1037 EXPECT_CALL(foo, DoThis(_))
1038 .WillRepeatedly(Return('b'));
1039 // The more specific case.
1040 EXPECT_CALL(foo, DoThis(Lt(5)))
1041 .WillRepeatedly(Return('a'));
1044 Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will be
1045 returned; otherwise `'b'` will be returned.
1047 ### Matching Multiple Arguments as a Whole
1049 Sometimes it's not enough to match the arguments individually. For example, we
1050 may want to say that the first argument must be less than the second argument.
1051 The `With()` clause allows us to match all arguments of a mock function as a
1056 using ::testing::Ne;
1057 using ::testing::Lt;
1059 EXPECT_CALL(foo, InRange(Ne(0), _))
1063 says that the first argument of `InRange()` must not be 0, and must be less than
1064 the second argument.
1066 The expression inside `With()` must be a matcher of type `Matcher<std::tuple<A1,
1067 ..., An>>`, where `A1`, ..., `An` are the types of the function arguments.
1069 You can also write `AllArgs(m)` instead of `m` inside `.With()`. The two forms
1070 are equivalent, but `.With(AllArgs(Lt()))` is more readable than `.With(Lt())`.
1072 You can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments (as a
1073 tuple) against `m`. For example,
1077 using ::testing::AllOf;
1078 using ::testing::Args;
1079 using ::testing::Lt;
1081 EXPECT_CALL(foo, Blah)
1082 .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt())));
1085 says that `Blah` will be called with arguments `x`, `y`, and `z` where `x < y <
1086 z`. Note that in this example, it wasn't necessary to specify the positional
1089 As a convenience and example, gMock provides some matchers for 2-tuples,
1090 including the `Lt()` matcher above. See
1091 [Multi-argument Matchers](reference/matchers.md#MultiArgMatchers) for the
1094 Note that if you want to pass the arguments to a predicate of your own (e.g.
1095 `.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be written to
1096 take a `std::tuple` as its argument; gMock will pass the `n` selected arguments
1097 as *one* single tuple to the predicate.
1099 ### Using Matchers as Predicates
1101 Have you noticed that a matcher is just a fancy predicate that also knows how to
1102 describe itself? Many existing algorithms take predicates as arguments (e.g.
1103 those defined in STL's `<algorithm>` header), and it would be a shame if gMock
1104 matchers were not allowed to participate.
1106 Luckily, you can use a matcher where a unary predicate functor is expected by
1107 wrapping it inside the `Matches()` function. For example,
1110 #include <algorithm>
1113 using ::testing::Matches;
1114 using ::testing::Ge;
1118 // How many elements in v are >= 10?
1119 const int count = count_if(v.begin(), v.end(), Matches(Ge(10)));
1122 Since you can build complex matchers from simpler ones easily using gMock, this
1123 gives you a way to conveniently construct composite predicates (doing the same
1124 using STL's `<functional>` header is just painful). For example, here's a
1125 predicate that's satisfied by any number that is >= 0, <= 100, and != 50:
1128 using testing::AllOf;
1131 using testing::Matches;
1134 Matches(AllOf(Ge(0), Le(100), Ne(50)))
1137 ### Using Matchers in googletest Assertions
1139 See [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) in the Assertions
1142 ### Using Predicates as Matchers
1144 gMock provides a set of built-in matchers for matching arguments with expected
1145 values—see the [Matchers Reference](reference/matchers.md) for more information.
1146 In case you find the built-in set lacking, you can use an arbitrary unary
1147 predicate function or functor as a matcher - as long as the predicate accepts a
1148 value of the type you want. You do this by wrapping the predicate inside the
1149 `Truly()` function, for example:
1152 using ::testing::Truly;
1154 int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; }
1156 // Bar() must be called with an even number.
1157 EXPECT_CALL(foo, Bar(Truly(IsEven)));
1160 Note that the predicate function / functor doesn't have to return `bool`. It
1161 works as long as the return value can be used as the condition in in statement
1162 `if (condition) ...`.
1164 ### Matching Arguments that Are Not Copyable
1166 When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of
1167 `bar`. When `Foo()` is called later, gMock compares the argument to `Foo()` with
1168 the saved copy of `bar`. This way, you don't need to worry about `bar` being
1169 modified or destroyed after the `EXPECT_CALL()` is executed. The same is true
1170 when you use matchers like `Eq(bar)`, `Le(bar)`, and so on.
1172 But what if `bar` cannot be copied (i.e. has no copy constructor)? You could
1173 define your own matcher function or callback and use it with `Truly()`, as the
1174 previous couple of recipes have shown. Or, you may be able to get away from it
1175 if you can guarantee that `bar` won't be changed after the `EXPECT_CALL()` is
1176 executed. Just tell gMock that it should save a reference to `bar`, instead of a
1177 copy of it. Here's how:
1180 using ::testing::Eq;
1181 using ::testing::Lt;
1183 // Expects that Foo()'s argument == bar.
1184 EXPECT_CALL(mock_obj, Foo(Eq(std::ref(bar))));
1186 // Expects that Foo()'s argument < bar.
1187 EXPECT_CALL(mock_obj, Foo(Lt(std::ref(bar))));
1190 Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the
1191 result is undefined.
1193 ### Validating a Member of an Object
1195 Often a mock function takes a reference to object as an argument. When matching
1196 the argument, you may not want to compare the entire object against a fixed
1197 object, as that may be over-specification. Instead, you may need to validate a
1198 certain member variable or the result of a certain getter method of the object.
1199 You can do this with `Field()` and `Property()`. More specifically,
1205 is a matcher that matches a `Foo` object whose `bar` member variable satisfies
1209 Property(&Foo::baz, m)
1212 is a matcher that matches a `Foo` object whose `baz()` method returns a value
1213 that satisfies matcher `m`.
1217 | Expression | Description |
1218 | :--------------------------- | :--------------------------------------- |
1219 | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. |
1220 | `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. |
1222 Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument
1223 and be declared as `const`. Don't use `Property()` against member functions that
1224 you do not own, because taking addresses of functions is fragile and generally
1225 not part of the contract of the function.
1227 `Field()` and `Property()` can also match plain pointers to objects. For
1231 using ::testing::Field;
1232 using ::testing::Ge;
1234 Field(&Foo::number, Ge(3))
1237 matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, the match
1238 will always fail regardless of the inner matcher.
1240 What if you want to validate more than one members at the same time? Remember
1241 that there are [`AllOf()` and `AllOfArray()`](#CombiningMatchers).
1243 Finally `Field()` and `Property()` provide overloads that take the field or
1244 property names as the first argument to include it in the error message. This
1245 can be useful when creating combined matchers.
1248 using ::testing::AllOf;
1249 using ::testing::Field;
1250 using ::testing::Matcher;
1251 using ::testing::SafeMatcherCast;
1253 Matcher<Foo> IsFoo(const Foo& foo) {
1254 return AllOf(Field("some_field", &Foo::some_field, foo.some_field),
1255 Field("other_field", &Foo::other_field, foo.other_field),
1256 Field("last_field", &Foo::last_field, foo.last_field));
1260 ### Validating the Value Pointed to by a Pointer Argument
1262 C++ functions often take pointers as arguments. You can use matchers like
1263 `IsNull()`, `NotNull()`, and other comparison matchers to match a pointer, but
1264 what if you want to make sure the value *pointed to* by the pointer, instead of
1265 the pointer itself, has a certain property? Well, you can use the `Pointee(m)`
1268 `Pointee(m)` matches a pointer if and only if `m` matches the value the pointer
1269 points to. For example:
1272 using ::testing::Ge;
1273 using ::testing::Pointee;
1275 EXPECT_CALL(foo, Bar(Pointee(Ge(3))));
1278 expects `foo.Bar()` to be called with a pointer that points to a value greater
1281 One nice thing about `Pointee()` is that it treats a `NULL` pointer as a match
1282 failure, so you can write `Pointee(m)` instead of
1285 using ::testing::AllOf;
1286 using ::testing::NotNull;
1287 using ::testing::Pointee;
1289 AllOf(NotNull(), Pointee(m))
1292 without worrying that a `NULL` pointer will crash your test.
1294 Also, did we tell you that `Pointee()` works with both raw pointers **and**
1295 smart pointers (`std::unique_ptr`, `std::shared_ptr`, etc)?
1297 What if you have a pointer to pointer? You guessed it - you can use nested
1298 `Pointee()` to probe deeper inside the value. For example,
1299 `Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer that points
1300 to a number less than 3 (what a mouthful...).
1302 ### Defining a Custom Matcher Class {#CustomMatcherClass}
1304 Most matchers can be simply defined using [the MATCHER* macros](#NewMatchers),
1305 which are terse and flexible, and produce good error messages. However, these
1306 macros are not very explicit about the interfaces they create and are not always
1307 suitable, especially for matchers that will be widely reused.
1309 For more advanced cases, you may need to define your own matcher class. A custom
1310 matcher allows you to test a specific invariant property of that object. Let's
1311 take a look at how to do so.
1313 Imagine you have a mock function that takes an object of type `Foo`, which has
1314 an `int bar()` method and an `int baz()` method. You want to constrain that the
1315 argument's `bar()` value plus its `baz()` value is a given number. (This is an
1316 invariant.) Here's how we can write and use a matcher class to do so:
1319 class BarPlusBazEqMatcher {
1321 using is_gtest_matcher = void;
1323 explicit BarPlusBazEqMatcher(int expected_sum)
1324 : expected_sum_(expected_sum) {}
1326 bool MatchAndExplain(const Foo& foo,
1327 std::ostream* /* listener */) const {
1328 return (foo.bar() + foo.baz()) == expected_sum_;
1331 void DescribeTo(std::ostream* os) const {
1332 *os << "bar() + baz() equals " << expected_sum_;
1335 void DescribeNegationTo(std::ostream* os) const {
1336 *os << "bar() + baz() does not equal " << expected_sum_;
1339 const int expected_sum_;
1342 ::testing::Matcher<const Foo&> BarPlusBazEq(int expected_sum) {
1343 return BarPlusBazEqMatcher(expected_sum);
1348 EXPECT_CALL(foo, BarPlusBazEq(5))...;
1351 ### Matching Containers
1353 Sometimes an STL container (e.g. list, vector, map, ...) is passed to a mock
1354 function and you may want to validate it. Since most STL containers support the
1355 `==` operator, you can write `Eq(expected_container)` or simply
1356 `expected_container` to match a container exactly.
1358 Sometimes, though, you may want to be more flexible (for example, the first
1359 element must be an exact match, but the second element can be any positive
1360 number, and so on). Also, containers used in tests often have a small number of
1361 elements, and having to define the expected container out-of-line is a bit of a
1364 You can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in such
1369 using ::testing::ElementsAre;
1370 using ::testing::Gt;
1372 MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override));
1374 EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5)));
1377 The above matcher says that the container must have 4 elements, which must be 1,
1378 greater than 0, anything, and 5 respectively.
1380 If you instead write:
1384 using ::testing::Gt;
1385 using ::testing::UnorderedElementsAre;
1387 MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override));
1389 EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5)));
1392 It means that the container must have 4 elements, which (under some permutation)
1393 must be 1, greater than 0, anything, and 5 respectively.
1395 As an alternative you can place the arguments in a C-style array and use
1396 `ElementsAreArray()` or `UnorderedElementsAreArray()` instead:
1399 using ::testing::ElementsAreArray;
1401 // ElementsAreArray accepts an array of element values.
1402 const int expected_vector1[] = {1, 5, 2, 4, ...};
1403 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1)));
1405 // Or, an array of element matchers.
1406 Matcher<int> expected_vector2[] = {1, Gt(2), _, 3, ...};
1407 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2)));
1410 In case the array needs to be dynamically created (and therefore the array size
1411 cannot be inferred by the compiler), you can give `ElementsAreArray()` an
1412 additional argument to specify the array size:
1415 using ::testing::ElementsAreArray;
1417 int* const expected_vector3 = new int[count];
1418 ... fill expected_vector3 with values ...
1419 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count)));
1422 Use `Pair` when comparing maps or other associative containers.
1427 using testing::ElementsAre;
1428 using testing::Pair;
1430 std::map<string, int> m = {{"a", 1}, {"b", 2}, {"c", 3}};
1431 EXPECT_THAT(m, ElementsAre(Pair("a", 1), Pair("b", 2), Pair("c", 3)));
1438 * `ElementsAre*()` can be used to match *any* container that implements the
1439 STL iterator pattern (i.e. it has a `const_iterator` type and supports
1440 `begin()/end()`), not just the ones defined in STL. It will even work with
1441 container types yet to be written - as long as they follows the above
1443 * You can use nested `ElementsAre*()` to match nested (multi-dimensional)
1445 * If the container is passed by pointer instead of by reference, just write
1446 `Pointee(ElementsAre*(...))`.
1447 * The order of elements *matters* for `ElementsAre*()`. If you are using it
1448 with containers whose element order are undefined (e.g. `hash_map`) you
1449 should use `WhenSorted` around `ElementsAre`.
1451 ### Sharing Matchers
1453 Under the hood, a gMock matcher object consists of a pointer to a ref-counted
1454 implementation object. Copying matchers is allowed and very efficient, as only
1455 the pointer is copied. When the last matcher that references the implementation
1456 object dies, the implementation object will be deleted.
1458 Therefore, if you have some complex matcher that you want to use again and
1459 again, there is no need to build it every time. Just assign it to a matcher
1460 variable and use that variable repeatedly! For example,
1463 using ::testing::AllOf;
1464 using ::testing::Gt;
1465 using ::testing::Le;
1466 using ::testing::Matcher;
1468 Matcher<int> in_range = AllOf(Gt(5), Le(10));
1469 ... use in_range as a matcher in multiple EXPECT_CALLs ...
1472 ### Matchers must have no side-effects {#PureMatchers}
1474 {: .callout .warning}
1475 WARNING: gMock does not guarantee when or how many times a matcher will be
1476 invoked. Therefore, all matchers must be *purely functional*: they cannot have
1477 any side effects, and the match result must not depend on anything other than
1478 the matcher's parameters and the value being matched.
1480 This requirement must be satisfied no matter how a matcher is defined (e.g., if
1481 it is one of the standard matchers, or a custom matcher). In particular, a
1482 matcher can never call a mock function, as that will affect the state of the
1483 mock object and gMock.
1485 ## Setting Expectations
1487 ### Knowing When to Expect {#UseOnCall}
1489 **`ON_CALL`** is likely the *single most under-utilized construct* in gMock.
1491 There are basically two constructs for defining the behavior of a mock object:
1492 `ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when
1493 a mock method is called, but <em>doesn't imply any expectation on the method
1494 being called</em>. `EXPECT_CALL` not only defines the behavior, but also sets an
1495 expectation that <em>the method will be called with the given arguments, for the
1496 given number of times</em> (and *in the given order* when you specify the order
1499 Since `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every
1500 `EXPECT_CALL` adds a constraint on the behavior of the code under test. Having
1501 more constraints than necessary is *baaad* - even worse than not having enough
1504 This may be counter-intuitive. How could tests that verify more be worse than
1505 tests that verify less? Isn't verification the whole point of tests?
1507 The answer lies in *what* a test should verify. **A good test verifies the
1508 contract of the code.** If a test over-specifies, it doesn't leave enough
1509 freedom to the implementation. As a result, changing the implementation without
1510 breaking the contract (e.g. refactoring and optimization), which should be
1511 perfectly fine to do, can break such tests. Then you have to spend time fixing
1512 them, only to see them broken again the next time the implementation is changed.
1514 Keep in mind that one doesn't have to verify more than one property in one test.
1515 In fact, **it's a good style to verify only one thing in one test.** If you do
1516 that, a bug will likely break only one or two tests instead of dozens (which
1517 case would you rather debug?). If you are also in the habit of giving tests
1518 descriptive names that tell what they verify, you can often easily guess what's
1519 wrong just from the test log itself.
1521 So use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend
1522 to verify that the call is made. For example, you may have a bunch of `ON_CALL`s
1523 in your test fixture to set the common mock behavior shared by all tests in the
1524 same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s
1525 to verify different aspects of the code's behavior. Compared with the style
1526 where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more
1527 resilient to implementational changes (and thus less likely to require
1528 maintenance) and makes the intent of the tests more obvious (so they are easier
1529 to maintain when you do need to maintain them).
1531 If you are bothered by the "Uninteresting mock function call" message printed
1532 when a mock method without an `EXPECT_CALL` is called, you may use a `NiceMock`
1533 instead to suppress all such messages for the mock object, or suppress the
1534 message for specific methods by adding `EXPECT_CALL(...).Times(AnyNumber())`. DO
1535 NOT suppress it by blindly adding an `EXPECT_CALL(...)`, or you'll have a test
1536 that's a pain to maintain.
1538 ### Ignoring Uninteresting Calls
1540 If you are not interested in how a mock method is called, just don't say
1541 anything about it. In this case, if the method is ever called, gMock will
1542 perform its default action to allow the test program to continue. If you are not
1543 happy with the default action taken by gMock, you can override it using
1544 `DefaultValue<T>::Set()` (described [here](#DefaultValue)) or `ON_CALL()`.
1546 Please note that once you expressed interest in a particular mock method (via
1547 `EXPECT_CALL()`), all invocations to it must match some expectation. If this
1548 function is called but the arguments don't match any `EXPECT_CALL()` statement,
1549 it will be an error.
1551 ### Disallowing Unexpected Calls
1553 If a mock method shouldn't be called at all, explicitly say so:
1558 EXPECT_CALL(foo, Bar(_))
1562 If some calls to the method are allowed, but the rest are not, just list all the
1566 using ::testing::AnyNumber;
1567 using ::testing::Gt;
1569 EXPECT_CALL(foo, Bar(5));
1570 EXPECT_CALL(foo, Bar(Gt(10)))
1571 .Times(AnyNumber());
1574 A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` statements
1577 ### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected}
1579 *Uninteresting* calls and *unexpected* calls are different concepts in gMock.
1582 A call `x.Y(...)` is **uninteresting** if there's *not even a single*
1583 `EXPECT_CALL(x, Y(...))` set. In other words, the test isn't interested in the
1584 `x.Y()` method at all, as evident in that the test doesn't care to say anything
1587 A call `x.Y(...)` is **unexpected** if there are *some* `EXPECT_CALL(x,
1588 Y(...))`s set, but none of them matches the call. Put another way, the test is
1589 interested in the `x.Y()` method (therefore it explicitly sets some
1590 `EXPECT_CALL` to verify how it's called); however, the verification fails as the
1591 test doesn't expect this particular call to happen.
1593 **An unexpected call is always an error,** as the code under test doesn't behave
1594 the way the test expects it to behave.
1596 **By default, an uninteresting call is not an error,** as it violates no
1597 constraint specified by the test. (gMock's philosophy is that saying nothing
1598 means there is no constraint.) However, it leads to a warning, as it *might*
1599 indicate a problem (e.g. the test author might have forgotten to specify a
1602 In gMock, `NiceMock` and `StrictMock` can be used to make a mock class "nice" or
1603 "strict". How does this affect uninteresting calls and unexpected calls?
1605 A **nice mock** suppresses uninteresting call *warnings*. It is less chatty than
1606 the default mock, but otherwise is the same. If a test fails with a default
1607 mock, it will also fail using a nice mock instead. And vice versa. Don't expect
1608 making a mock nice to change the test's result.
1610 A **strict mock** turns uninteresting call warnings into errors. So making a
1611 mock strict may change the test's result.
1613 Let's look at an example:
1617 NiceMock<MockDomainRegistry> mock_registry;
1618 EXPECT_CALL(mock_registry, GetDomainOwner("google.com"))
1619 .WillRepeatedly(Return("Larry Page"));
1621 // Use mock_registry in code under test.
1622 ... &mock_registry ...
1626 The sole `EXPECT_CALL` here says that all calls to `GetDomainOwner()` must have
1627 `"google.com"` as the argument. If `GetDomainOwner("yahoo.com")` is called, it
1628 will be an unexpected call, and thus an error. *Having a nice mock doesn't
1629 change the severity of an unexpected call.*
1631 So how do we tell gMock that `GetDomainOwner()` can be called with some other
1632 arguments as well? The standard technique is to add a "catch all" `EXPECT_CALL`:
1635 EXPECT_CALL(mock_registry, GetDomainOwner(_))
1636 .Times(AnyNumber()); // catches all other calls to this method.
1637 EXPECT_CALL(mock_registry, GetDomainOwner("google.com"))
1638 .WillRepeatedly(Return("Larry Page"));
1641 Remember that `_` is the wildcard matcher that matches anything. With this, if
1642 `GetDomainOwner("google.com")` is called, it will do what the second
1643 `EXPECT_CALL` says; if it is called with a different argument, it will do what
1644 the first `EXPECT_CALL` says.
1646 Note that the order of the two `EXPECT_CALL`s is important, as a newer
1647 `EXPECT_CALL` takes precedence over an older one.
1649 For more on uninteresting calls, nice mocks, and strict mocks, read
1650 ["The Nice, the Strict, and the Naggy"](#NiceStrictNaggy).
1652 ### Ignoring Uninteresting Arguments {#ParameterlessExpectations}
1654 If your test doesn't care about the parameters (it only cares about the number
1655 or order of calls), you can often simply omit the parameter list:
1658 // Expect foo.Bar( ... ) twice with any arguments.
1659 EXPECT_CALL(foo, Bar).Times(2);
1661 // Delegate to the given method whenever the factory is invoked.
1662 ON_CALL(foo_factory, MakeFoo)
1663 .WillByDefault(&BuildFooForTest);
1666 This functionality is only available when a method is not overloaded; to prevent
1667 unexpected behavior it is a compilation error to try to set an expectation on a
1668 method where the specific overload is ambiguous. You can work around this by
1669 supplying a [simpler mock interface](#SimplerInterfaces) than the mocked class
1672 This pattern is also useful when the arguments are interesting, but match logic
1673 is substantially complex. You can leave the argument list unspecified and use
1674 SaveArg actions to [save the values for later verification](#SaveArgVerify). If
1675 you do that, you can easily differentiate calling the method the wrong number of
1676 times from calling it with the wrong arguments.
1678 ### Expecting Ordered Calls {#OrderedCalls}
1680 Although an `EXPECT_CALL()` statement defined later takes precedence when gMock
1681 tries to match a function call with an expectation, by default calls don't have
1682 to happen in the order `EXPECT_CALL()` statements are written. For example, if
1683 the arguments match the matchers in the second `EXPECT_CALL()`, but not those in
1684 the first and third, then the second expectation will be used.
1686 If you would rather have all calls occur in the order of the expectations, put
1687 the `EXPECT_CALL()` statements in a block where you define a variable of type
1692 using ::testing::InSequence;
1697 EXPECT_CALL(foo, DoThis(5));
1698 EXPECT_CALL(bar, DoThat(_))
1700 EXPECT_CALL(foo, DoThis(6));
1704 In this example, we expect a call to `foo.DoThis(5)`, followed by two calls to
1705 `bar.DoThat()` where the argument can be anything, which are in turn followed by
1706 a call to `foo.DoThis(6)`. If a call occurred out-of-order, gMock will report an
1709 ### Expecting Partially Ordered Calls {#PartialOrder}
1711 Sometimes requiring everything to occur in a predetermined order can lead to
1712 brittle tests. For example, we may care about `A` occurring before both `B` and
1713 `C`, but aren't interested in the relative order of `B` and `C`. In this case,
1714 the test should reflect our real intent, instead of being overly constraining.
1716 gMock allows you to impose an arbitrary DAG (directed acyclic graph) on the
1717 calls. One way to express the DAG is to use the
1718 [`After` clause](reference/mocking.md#EXPECT_CALL.After) of `EXPECT_CALL`.
1720 Another way is via the `InSequence()` clause (not the same as the `InSequence`
1721 class), which we borrowed from jMock 2. It's less flexible than `After()`, but
1722 more convenient when you have long chains of sequential calls, as it doesn't
1723 require you to come up with different names for the expectations in the chains.
1724 Here's how it works:
1726 If we view `EXPECT_CALL()` statements as nodes in a graph, and add an edge from
1727 node A to node B wherever A must occur before B, we can get a DAG. We use the
1728 term "sequence" to mean a directed path in this DAG. Now, if we decompose the
1729 DAG into sequences, we just need to know which sequences each `EXPECT_CALL()`
1730 belongs to in order to be able to reconstruct the original DAG.
1732 So, to specify the partial order on the expectations we need to do two things:
1733 first to define some `Sequence` objects, and then for each `EXPECT_CALL()` say
1734 which `Sequence` objects it is part of.
1736 Expectations in the same sequence must occur in the order they are written. For
1740 using ::testing::Sequence;
1744 EXPECT_CALL(foo, A())
1745 .InSequence(s1, s2);
1746 EXPECT_CALL(bar, B())
1748 EXPECT_CALL(bar, C())
1750 EXPECT_CALL(foo, D())
1754 specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> C -> D`):
1764 This means that A must occur before B and C, and C must occur before D. There's
1765 no restriction about the order other than these.
1767 ### Controlling When an Expectation Retires
1769 When a mock method is called, gMock only considers expectations that are still
1770 active. An expectation is active when created, and becomes inactive (aka
1771 *retires*) when a call that has to occur later has occurred. For example, in
1775 using ::testing::Sequence;
1779 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1
1781 .InSequence(s1, s2);
1782 EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2
1784 EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3
1788 as soon as either #2 or #3 is matched, #1 will retire. If a warning `"File too
1789 large."` is logged after this, it will be an error.
1791 Note that an expectation doesn't retire automatically when it's saturated. For
1797 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1798 EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2
1801 says that there will be exactly one warning with the message `"File too
1802 large."`. If the second warning contains this message too, #2 will match again
1803 and result in an upper-bound-violated error.
1805 If this is not what you want, you can ask an expectation to retire as soon as it
1811 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1812 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2
1813 .RetiresOnSaturation();
1816 Here #2 can be used only once, so if you have two warnings with the message
1817 `"File too large."`, the first will match #2 and the second will match #1 -
1818 there will be no error.
1822 ### Returning References from Mock Methods
1824 If a mock function's return type is a reference, you need to use `ReturnRef()`
1825 instead of `Return()` to return a result:
1828 using ::testing::ReturnRef;
1830 class MockFoo : public Foo {
1832 MOCK_METHOD(Bar&, GetBar, (), (override));
1837 EXPECT_CALL(foo, GetBar())
1838 .WillOnce(ReturnRef(bar));
1842 ### Returning Live Values from Mock Methods
1844 The `Return(x)` action saves a copy of `x` when the action is created, and
1845 always returns the same value whenever it's executed. Sometimes you may want to
1846 instead return the *live* value of `x` (i.e. its value at the time when the
1847 action is *executed*.). Use either `ReturnRef()` or `ReturnPointee()` for this
1850 If the mock function's return type is a reference, you can do it using
1851 `ReturnRef(x)`, as shown in the previous recipe ("Returning References from Mock
1852 Methods"). However, gMock doesn't let you use `ReturnRef()` in a mock function
1853 whose return type is not a reference, as doing that usually indicates a user
1854 error. So, what shall you do?
1856 Though you may be tempted, DO NOT use `std::ref()`:
1859 using testing::Return;
1861 class MockFoo : public Foo {
1863 MOCK_METHOD(int, GetValue, (), (override));
1868 EXPECT_CALL(foo, GetValue())
1869 .WillRepeatedly(Return(std::ref(x))); // Wrong!
1871 EXPECT_EQ(42, foo.GetValue());
1874 Unfortunately, it doesn't work here. The above code will fail with error:
1877 Value of: foo.GetValue()
1882 The reason is that `Return(*value*)` converts `value` to the actual return type
1883 of the mock function at the time when the action is *created*, not when it is
1884 *executed*. (This behavior was chosen for the action to be safe when `value` is
1885 a proxy object that references some temporary objects.) As a result,
1886 `std::ref(x)` is converted to an `int` value (instead of a `const int&`) when
1887 the expectation is set, and `Return(std::ref(x))` will always return 0.
1889 `ReturnPointee(pointer)` was provided to solve this problem specifically. It
1890 returns the value pointed to by `pointer` at the time the action is *executed*:
1893 using testing::ReturnPointee;
1897 EXPECT_CALL(foo, GetValue())
1898 .WillRepeatedly(ReturnPointee(&x)); // Note the & here.
1900 EXPECT_EQ(42, foo.GetValue()); // This will succeed now.
1903 ### Combining Actions
1905 Want to do more than one thing when a function is called? That's fine. `DoAll()`
1906 allow you to do sequence of actions every time. Only the return value of the
1907 last action in the sequence will be used.
1911 using ::testing::DoAll;
1913 class MockFoo : public Foo {
1915 MOCK_METHOD(bool, Bar, (int n), (override));
1918 EXPECT_CALL(foo, Bar(_))
1919 .WillOnce(DoAll(action_1,
1925 ### Verifying Complex Arguments {#SaveArgVerify}
1927 If you want to verify that a method is called with a particular argument but the
1928 match criteria is complex, it can be difficult to distinguish between
1929 cardinality failures (calling the method the wrong number of times) and argument
1930 match failures. Similarly, if you are matching multiple parameters, it may not
1931 be easy to distinguishing which argument failed to match. For example:
1934 // Not ideal: this could fail because of a problem with arg1 or arg2, or maybe
1935 // just the method wasn't called.
1936 EXPECT_CALL(foo, SendValues(_, ElementsAre(1, 4, 4, 7), EqualsProto( ... )));
1939 You can instead save the arguments and test them individually:
1942 EXPECT_CALL(foo, SendValues)
1943 .WillOnce(DoAll(SaveArg<1>(&actual_array), SaveArg<2>(&actual_proto)));
1945 EXPECT_THAT(actual_array, ElementsAre(1, 4, 4, 7));
1946 EXPECT_THAT(actual_proto, EqualsProto( ... ));
1949 ### Mocking Side Effects {#MockingSideEffects}
1951 Sometimes a method exhibits its effect not via returning a value but via side
1952 effects. For example, it may change some global state or modify an output
1953 argument. To mock side effects, in general you can define your own action by
1954 implementing `::testing::ActionInterface`.
1956 If all you need to do is to change an output argument, the built-in
1957 `SetArgPointee()` action is convenient:
1961 using ::testing::SetArgPointee;
1963 class MockMutator : public Mutator {
1965 MOCK_METHOD(void, Mutate, (bool mutate, int* value), (override));
1969 MockMutator mutator;
1970 EXPECT_CALL(mutator, Mutate(true, _))
1971 .WillOnce(SetArgPointee<1>(5));
1974 In this example, when `mutator.Mutate()` is called, we will assign 5 to the
1975 `int` variable pointed to by argument #1 (0-based).
1977 `SetArgPointee()` conveniently makes an internal copy of the value you pass to
1978 it, removing the need to keep the value in scope and alive. The implication
1979 however is that the value must have a copy constructor and assignment operator.
1981 If the mock method also needs to return a value as well, you can chain
1982 `SetArgPointee()` with `Return()` using `DoAll()`, remembering to put the
1983 `Return()` statement last:
1987 using ::testing::DoAll;
1988 using ::testing::Return;
1989 using ::testing::SetArgPointee;
1991 class MockMutator : public Mutator {
1994 MOCK_METHOD(bool, MutateInt, (int* value), (override));
1997 MockMutator mutator;
1998 EXPECT_CALL(mutator, MutateInt(_))
1999 .WillOnce(DoAll(SetArgPointee<0>(5),
2003 Note, however, that if you use the `ReturnOKWith()` method, it will override the
2004 values provided by `SetArgPointee()` in the response parameters of your function
2007 If the output argument is an array, use the `SetArrayArgument<N>(first, last)`
2008 action instead. It copies the elements in source range `[first, last)` to the
2009 array pointed to by the `N`-th (0-based) argument:
2012 using ::testing::NotNull;
2013 using ::testing::SetArrayArgument;
2015 class MockArrayMutator : public ArrayMutator {
2017 MOCK_METHOD(void, Mutate, (int* values, int num_values), (override));
2021 MockArrayMutator mutator;
2022 int values[5] = {1, 2, 3, 4, 5};
2023 EXPECT_CALL(mutator, Mutate(NotNull(), 5))
2024 .WillOnce(SetArrayArgument<0>(values, values + 5));
2027 This also works when the argument is an output iterator:
2031 using ::testing::SetArrayArgument;
2033 class MockRolodex : public Rolodex {
2035 MOCK_METHOD(void, GetNames, (std::back_insert_iterator<vector<string>>),
2040 MockRolodex rolodex;
2041 vector<string> names = {"George", "John", "Thomas"};
2042 EXPECT_CALL(rolodex, GetNames(_))
2043 .WillOnce(SetArrayArgument<0>(names.begin(), names.end()));
2046 ### Changing a Mock Object's Behavior Based on the State
2048 If you expect a call to change the behavior of a mock object, you can use
2049 `::testing::InSequence` to specify different behaviors before and after the
2053 using ::testing::InSequence;
2054 using ::testing::Return;
2059 EXPECT_CALL(my_mock, IsDirty())
2060 .WillRepeatedly(Return(true));
2061 EXPECT_CALL(my_mock, Flush());
2062 EXPECT_CALL(my_mock, IsDirty())
2063 .WillRepeatedly(Return(false));
2065 my_mock.FlushIfDirty();
2068 This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called
2069 and return `false` afterwards.
2071 If the behavior change is more complex, you can store the effects in a variable
2072 and make a mock method get its return value from that variable:
2076 using ::testing::SaveArg;
2077 using ::testing::Return;
2079 ACTION_P(ReturnPointee, p) { return *p; }
2081 int previous_value = 0;
2082 EXPECT_CALL(my_mock, GetPrevValue)
2083 .WillRepeatedly(ReturnPointee(&previous_value));
2084 EXPECT_CALL(my_mock, UpdateValue)
2085 .WillRepeatedly(SaveArg<0>(&previous_value));
2086 my_mock.DoSomethingToUpdateValue();
2089 Here `my_mock.GetPrevValue()` will always return the argument of the last
2090 `UpdateValue()` call.
2092 ### Setting the Default Value for a Return Type {#DefaultValue}
2094 If a mock method's return type is a built-in C++ type or pointer, by default it
2095 will return 0 when invoked. Also, in C++ 11 and above, a mock method whose
2096 return type has a default constructor will return a default-constructed value by
2097 default. You only need to specify an action if this default value doesn't work
2100 Sometimes, you may want to change this default value, or you may want to specify
2101 a default value for types gMock doesn't know about. You can do this using the
2102 `::testing::DefaultValue` class template:
2105 using ::testing::DefaultValue;
2107 class MockFoo : public Foo {
2109 MOCK_METHOD(Bar, CalculateBar, (), (override));
2115 // Sets the default return value for type Bar.
2116 DefaultValue<Bar>::Set(default_bar);
2120 // We don't need to specify an action here, as the default
2121 // return value works for us.
2122 EXPECT_CALL(foo, CalculateBar());
2124 foo.CalculateBar(); // This should return default_bar.
2126 // Unsets the default return value.
2127 DefaultValue<Bar>::Clear();
2130 Please note that changing the default value for a type can make your tests hard
2131 to understand. We recommend you to use this feature judiciously. For example,
2132 you may want to make sure the `Set()` and `Clear()` calls are right next to the
2133 code that uses your mock.
2135 ### Setting the Default Actions for a Mock Method
2137 You've learned how to change the default value of a given type. However, this
2138 may be too coarse for your purpose: perhaps you have two mock methods with the
2139 same return type and you want them to have different behaviors. The `ON_CALL()`
2140 macro allows you to customize your mock's behavior at the method level:
2144 using ::testing::AnyNumber;
2145 using ::testing::Gt;
2146 using ::testing::Return;
2148 ON_CALL(foo, Sign(_))
2149 .WillByDefault(Return(-1));
2150 ON_CALL(foo, Sign(0))
2151 .WillByDefault(Return(0));
2152 ON_CALL(foo, Sign(Gt(0)))
2153 .WillByDefault(Return(1));
2155 EXPECT_CALL(foo, Sign(_))
2156 .Times(AnyNumber());
2158 foo.Sign(5); // This should return 1.
2159 foo.Sign(-9); // This should return -1.
2160 foo.Sign(0); // This should return 0.
2163 As you may have guessed, when there are more than one `ON_CALL()` statements,
2164 the newer ones in the order take precedence over the older ones. In other words,
2165 the **last** one that matches the function arguments will be used. This matching
2166 order allows you to set up the common behavior in a mock object's constructor or
2167 the test fixture's set-up phase and specialize the mock's behavior later.
2169 Note that both `ON_CALL` and `EXPECT_CALL` have the same "later statements take
2170 precedence" rule, but they don't interact. That is, `EXPECT_CALL`s have their
2171 own precedence order distinct from the `ON_CALL` precedence order.
2173 ### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions}
2175 If the built-in actions don't suit you, you can use an existing callable
2176 (function, `std::function`, method, functor, lambda) as an action.
2179 using ::testing::_; using ::testing::Invoke;
2181 class MockFoo : public Foo {
2183 MOCK_METHOD(int, Sum, (int x, int y), (override));
2184 MOCK_METHOD(bool, ComplexJob, (int x), (override));
2187 int CalculateSum(int x, int y) { return x + y; }
2188 int Sum3(int x, int y, int z) { return x + y + z; }
2192 bool ComplexJob(int x);
2198 EXPECT_CALL(foo, Sum(_, _))
2199 .WillOnce(&CalculateSum)
2200 .WillRepeatedly(Invoke(NewPermanentCallback(Sum3, 1)));
2201 EXPECT_CALL(foo, ComplexJob(_))
2202 .WillOnce(Invoke(&helper, &Helper::ComplexJob))
2203 .WillOnce([] { return true; })
2204 .WillRepeatedly([](int x) { return x > 0; });
2206 foo.Sum(5, 6); // Invokes CalculateSum(5, 6).
2207 foo.Sum(2, 3); // Invokes Sum3(1, 2, 3).
2208 foo.ComplexJob(10); // Invokes helper.ComplexJob(10).
2209 foo.ComplexJob(-1); // Invokes the inline lambda.
2212 The only requirement is that the type of the function, etc must be *compatible*
2213 with the signature of the mock function, meaning that the latter's arguments (if
2214 it takes any) can be implicitly converted to the corresponding arguments of the
2215 former, and the former's return type can be implicitly converted to that of the
2216 latter. So, you can invoke something whose type is *not* exactly the same as the
2217 mock function, as long as it's safe to do so - nice, huh?
2221 * The action takes ownership of the callback and will delete it when the
2222 action itself is destructed.
2223 * If the type of a callback is derived from a base callback type `C`, you need
2224 to implicitly cast it to `C` to resolve the overloading, e.g.
2227 using ::testing::Invoke;
2229 ResultCallback<bool>* is_ok = ...;
2230 ... Invoke(is_ok) ...; // This works.
2232 BlockingClosure* done = new BlockingClosure;
2233 ... Invoke(implicit_cast<Closure*>(done)) ...; // The cast is necessary.
2236 ### Using Functions with Extra Info as Actions
2238 The function or functor you call using `Invoke()` must have the same number of
2239 arguments as the mock function you use it for. Sometimes you may have a function
2240 that takes more arguments, and you are willing to pass in the extra arguments
2241 yourself to fill the gap. You can do this in gMock using callbacks with
2242 pre-bound arguments. Here's an example:
2245 using ::testing::Invoke;
2247 class MockFoo : public Foo {
2249 MOCK_METHOD(char, DoThis, (int n), (override));
2252 char SignOfSum(int x, int y) {
2253 const int sum = x + y;
2254 return (sum > 0) ? '+' : (sum < 0) ? '-' : '0';
2257 TEST_F(FooTest, Test) {
2260 EXPECT_CALL(foo, DoThis(2))
2261 .WillOnce(Invoke(NewPermanentCallback(SignOfSum, 5)));
2262 EXPECT_EQ('+', foo.DoThis(2)); // Invokes SignOfSum(5, 2).
2266 ### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments
2268 `Invoke()` passes the mock function's arguments to the function, etc being
2269 invoked such that the callee has the full context of the call to work with. If
2270 the invoked function is not interested in some or all of the arguments, it can
2273 Yet, a common pattern is that a test author wants to invoke a function without
2274 the arguments of the mock function. She could do that using a wrapper function
2275 that throws away the arguments before invoking an underlining nullary function.
2276 Needless to say, this can be tedious and obscures the intent of the test.
2278 There are two solutions to this problem. First, you can pass any callable of
2279 zero args as an action. Alternatively, use `InvokeWithoutArgs()`, which is like
2280 `Invoke()` except that it doesn't pass the mock function's arguments to the
2281 callee. Here's an example of each:
2285 using ::testing::InvokeWithoutArgs;
2287 class MockFoo : public Foo {
2289 MOCK_METHOD(bool, ComplexJob, (int n), (override));
2293 bool Job2(int n, char c) { ... }
2297 EXPECT_CALL(foo, ComplexJob(_))
2298 .WillOnce([] { Job1(); });
2299 .WillOnce(InvokeWithoutArgs(NewPermanentCallback(Job2, 5, 'a')));
2301 foo.ComplexJob(10); // Invokes Job1().
2302 foo.ComplexJob(20); // Invokes Job2(5, 'a').
2307 * The action takes ownership of the callback and will delete it when the
2308 action itself is destructed.
2309 * If the type of a callback is derived from a base callback type `C`, you need
2310 to implicitly cast it to `C` to resolve the overloading, e.g.
2313 using ::testing::InvokeWithoutArgs;
2315 ResultCallback<bool>* is_ok = ...;
2316 ... InvokeWithoutArgs(is_ok) ...; // This works.
2318 BlockingClosure* done = ...;
2319 ... InvokeWithoutArgs(implicit_cast<Closure*>(done)) ...;
2320 // The cast is necessary.
2323 ### Invoking an Argument of the Mock Function
2325 Sometimes a mock function will receive a function pointer, a functor (in other
2326 words, a "callable") as an argument, e.g.
2329 class MockFoo : public Foo {
2331 MOCK_METHOD(bool, DoThis, (int n, (ResultCallback1<bool, int>* callback)),
2336 and you may want to invoke this callable argument:
2342 EXPECT_CALL(foo, DoThis(_, _))
2344 // Will execute callback->Run(5), where callback is the
2345 // second argument DoThis() receives.
2349 NOTE: The section below is legacy documentation from before C++ had lambdas:
2351 Arghh, you need to refer to a mock function argument but C++ has no lambda
2352 (yet), so you have to define your own action. :-( Or do you really?
2354 Well, gMock has an action to solve *exactly* this problem:
2357 InvokeArgument<N>(arg_1, arg_2, ..., arg_m)
2360 will invoke the `N`-th (0-based) argument the mock function receives, with
2361 `arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is a function
2362 pointer, a functor, or a callback. gMock handles them all.
2364 With that, you could write:
2368 using ::testing::InvokeArgument;
2370 EXPECT_CALL(foo, DoThis(_, _))
2371 .WillOnce(InvokeArgument<1>(5));
2372 // Will execute callback->Run(5), where callback is the
2373 // second argument DoThis() receives.
2376 What if the callable takes an argument by reference? No problem - just wrap it
2377 inside `std::ref()`:
2381 MOCK_METHOD(bool, Bar,
2382 ((ResultCallback2<bool, int, const Helper&>* callback)),
2386 using ::testing::InvokeArgument;
2391 EXPECT_CALL(foo, Bar(_))
2392 .WillOnce(InvokeArgument<0>(5, std::ref(helper)));
2393 // std::ref(helper) guarantees that a reference to helper, not a copy of
2394 // it, will be passed to the callback.
2397 What if the callable takes an argument by reference and we do **not** wrap the
2398 argument in `std::ref()`? Then `InvokeArgument()` will *make a copy* of the
2399 argument, and pass a *reference to the copy*, instead of a reference to the
2400 original value, to the callable. This is especially handy when the argument is a
2405 MOCK_METHOD(bool, DoThat, (bool (*f)(const double& x, const string& s)),
2409 using ::testing::InvokeArgument;
2413 EXPECT_CALL(foo, DoThat(_))
2414 .WillOnce(InvokeArgument<0>(5.0, string("Hi")));
2415 // Will execute (*f)(5.0, string("Hi")), where f is the function pointer
2416 // DoThat() receives. Note that the values 5.0 and string("Hi") are
2417 // temporary and dead once the EXPECT_CALL() statement finishes. Yet
2418 // it's fine to perform this action later, since a copy of the values
2419 // are kept inside the InvokeArgument action.
2422 ### Ignoring an Action's Result
2424 Sometimes you have an action that returns *something*, but you need an action
2425 that returns `void` (perhaps you want to use it in a mock function that returns
2426 `void`, or perhaps it needs to be used in `DoAll()` and it's not the last in the
2427 list). `IgnoreResult()` lets you do that. For example:
2431 using ::testing::DoAll;
2432 using ::testing::IgnoreResult;
2433 using ::testing::Return;
2435 int Process(const MyData& data);
2436 string DoSomething();
2438 class MockFoo : public Foo {
2440 MOCK_METHOD(void, Abc, (const MyData& data), (override));
2441 MOCK_METHOD(bool, Xyz, (), (override));
2446 EXPECT_CALL(foo, Abc(_))
2447 // .WillOnce(Invoke(Process));
2448 // The above line won't compile as Process() returns int but Abc() needs
2450 .WillOnce(IgnoreResult(Process));
2451 EXPECT_CALL(foo, Xyz())
2452 .WillOnce(DoAll(IgnoreResult(DoSomething),
2453 // Ignores the string DoSomething() returns.
2457 Note that you **cannot** use `IgnoreResult()` on an action that already returns
2458 `void`. Doing so will lead to ugly compiler errors.
2460 ### Selecting an Action's Arguments {#SelectingArgs}
2462 Say you have a mock function `Foo()` that takes seven arguments, and you have a
2463 custom action that you want to invoke when `Foo()` is called. Trouble is, the
2464 custom action only wants three arguments:
2468 using ::testing::Invoke;
2470 MOCK_METHOD(bool, Foo,
2471 (bool visible, const string& name, int x, int y,
2472 (const map<pair<int, int>>), double& weight, double min_weight,
2475 bool IsVisibleInQuadrant1(bool visible, int x, int y) {
2476 return visible && x >= 0 && y >= 0;
2479 EXPECT_CALL(mock, Foo)
2480 .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-(
2483 To please the compiler God, you need to define an "adaptor" that has the same
2484 signature as `Foo()` and calls the custom action with the right arguments:
2488 using ::testing::Invoke;
2490 bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y,
2491 const map<pair<int, int>, double>& weight,
2492 double min_weight, double max_wight) {
2493 return IsVisibleInQuadrant1(visible, x, y);
2496 EXPECT_CALL(mock, Foo)
2497 .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works.
2500 But isn't this awkward?
2502 gMock provides a generic *action adaptor*, so you can spend your time minding
2503 more important business than writing your own adaptors. Here's the syntax:
2506 WithArgs<N1, N2, ..., Nk>(action)
2509 creates an action that passes the arguments of the mock function at the given
2510 indices (0-based) to the inner `action` and performs it. Using `WithArgs`, our
2511 original example can be written as:
2515 using ::testing::Invoke;
2516 using ::testing::WithArgs;
2518 EXPECT_CALL(mock, Foo)
2519 .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); // No need to define your own adaptor.
2522 For better readability, gMock also gives you:
2524 * `WithoutArgs(action)` when the inner `action` takes *no* argument, and
2525 * `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes
2528 As you may have realized, `InvokeWithoutArgs(...)` is just syntactic sugar for
2529 `WithoutArgs(Invoke(...))`.
2533 * The inner action used in `WithArgs` and friends does not have to be
2534 `Invoke()` -- it can be anything.
2535 * You can repeat an argument in the argument list if necessary, e.g.
2536 `WithArgs<2, 3, 3, 5>(...)`.
2537 * You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`.
2538 * The types of the selected arguments do *not* have to match the signature of
2539 the inner action exactly. It works as long as they can be implicitly
2540 converted to the corresponding arguments of the inner action. For example,
2541 if the 4-th argument of the mock function is an `int` and `my_action` takes
2542 a `double`, `WithArg<4>(my_action)` will work.
2544 ### Ignoring Arguments in Action Functions
2546 The [selecting-an-action's-arguments](#SelectingArgs) recipe showed us one way
2547 to make a mock function and an action with incompatible argument lists fit
2548 together. The downside is that wrapping the action in `WithArgs<...>()` can get
2549 tedious for people writing the tests.
2551 If you are defining a function (or method, functor, lambda, callback) to be used
2552 with `Invoke*()`, and you are not interested in some of its arguments, an
2553 alternative to `WithArgs` is to declare the uninteresting arguments as `Unused`.
2554 This makes the definition less cluttered and less fragile in case the types of
2555 the uninteresting arguments change. It could also increase the chance the action
2556 function can be reused. For example, given
2560 MOCK_METHOD(double, Foo, double(const string& label, double x, double y),
2562 MOCK_METHOD(double, Bar, (int index, double x, double y), (override));
2569 using ::testing::Invoke;
2571 double DistanceToOriginWithLabel(const string& label, double x, double y) {
2572 return sqrt(x*x + y*y);
2574 double DistanceToOriginWithIndex(int index, double x, double y) {
2575 return sqrt(x*x + y*y);
2578 EXPECT_CALL(mock, Foo("abc", _, _))
2579 .WillOnce(Invoke(DistanceToOriginWithLabel));
2580 EXPECT_CALL(mock, Bar(5, _, _))
2581 .WillOnce(Invoke(DistanceToOriginWithIndex));
2588 using ::testing::Invoke;
2589 using ::testing::Unused;
2591 double DistanceToOrigin(Unused, double x, double y) {
2592 return sqrt(x*x + y*y);
2595 EXPECT_CALL(mock, Foo("abc", _, _))
2596 .WillOnce(Invoke(DistanceToOrigin));
2597 EXPECT_CALL(mock, Bar(5, _, _))
2598 .WillOnce(Invoke(DistanceToOrigin));
2603 Just like matchers, a gMock action object consists of a pointer to a ref-counted
2604 implementation object. Therefore copying actions is also allowed and very
2605 efficient. When the last action that references the implementation object dies,
2606 the implementation object will be deleted.
2608 If you have some complex action that you want to use again and again, you may
2609 not have to build it from scratch every time. If the action doesn't have an
2610 internal state (i.e. if it always does the same thing no matter how many times
2611 it has been called), you can assign it to an action variable and use that
2612 variable repeatedly. For example:
2615 using ::testing::Action;
2616 using ::testing::DoAll;
2617 using ::testing::Return;
2618 using ::testing::SetArgPointee;
2620 Action<bool(int*)> set_flag = DoAll(SetArgPointee<0>(5),
2622 ... use set_flag in .WillOnce() and .WillRepeatedly() ...
2625 However, if the action has its own state, you may be surprised if you share the
2626 action object. Suppose you have an action factory `IncrementCounter(init)` which
2627 creates an action that increments and returns a counter whose initial value is
2628 `init`, using two actions created from the same expression and using a shared
2629 action will exhibit different behaviors. Example:
2632 EXPECT_CALL(foo, DoThis())
2633 .WillRepeatedly(IncrementCounter(0));
2634 EXPECT_CALL(foo, DoThat())
2635 .WillRepeatedly(IncrementCounter(0));
2636 foo.DoThis(); // Returns 1.
2637 foo.DoThis(); // Returns 2.
2638 foo.DoThat(); // Returns 1 - Blah() uses a different
2639 // counter than Bar()'s.
2645 using ::testing::Action;
2647 Action<int()> increment = IncrementCounter(0);
2648 EXPECT_CALL(foo, DoThis())
2649 .WillRepeatedly(increment);
2650 EXPECT_CALL(foo, DoThat())
2651 .WillRepeatedly(increment);
2652 foo.DoThis(); // Returns 1.
2653 foo.DoThis(); // Returns 2.
2654 foo.DoThat(); // Returns 3 - the counter is shared.
2657 ### Testing Asynchronous Behavior
2659 One oft-encountered problem with gMock is that it can be hard to test
2660 asynchronous behavior. Suppose you had a `EventQueue` class that you wanted to
2661 test, and you created a separate `EventDispatcher` interface so that you could
2662 easily mock it out. However, the implementation of the class fired all the
2663 events on a background thread, which made test timings difficult. You could just
2664 insert `sleep()` statements and hope for the best, but that makes your test
2665 behavior nondeterministic. A better way is to use gMock actions and
2666 `Notification` objects to force your asynchronous test to behave synchronously.
2669 class MockEventDispatcher : public EventDispatcher {
2670 MOCK_METHOD(bool, DispatchEvent, (int32), (override));
2673 TEST(EventQueueTest, EnqueueEventTest) {
2674 MockEventDispatcher mock_event_dispatcher;
2675 EventQueue event_queue(&mock_event_dispatcher);
2677 const int32 kEventId = 321;
2678 absl::Notification done;
2679 EXPECT_CALL(mock_event_dispatcher, DispatchEvent(kEventId))
2680 .WillOnce([&done] { done.Notify(); });
2682 event_queue.EnqueueEvent(kEventId);
2683 done.WaitForNotification();
2687 In the example above, we set our normal gMock expectations, but then add an
2688 additional action to notify the `Notification` object. Now we can just call
2689 `Notification::WaitForNotification()` in the main thread to wait for the
2690 asynchronous call to finish. After that, our test suite is complete and we can
2694 Note: this example has a downside: namely, if the expectation is not satisfied,
2695 our test will run forever. It will eventually time-out and fail, but it will
2696 take longer and be slightly harder to debug. To alleviate this problem, you can
2697 use `WaitForNotificationWithTimeout(ms)` instead of `WaitForNotification()`.
2699 ## Misc Recipes on Using gMock
2701 ### Mocking Methods That Use Move-Only Types
2703 C++11 introduced *move-only types*. A move-only-typed value can be moved from
2704 one object to another, but cannot be copied. `std::unique_ptr<T>` is probably
2705 the most commonly used move-only type.
2707 Mocking a method that takes and/or returns move-only types presents some
2708 challenges, but nothing insurmountable. This recipe shows you how you can do it.
2709 Note that the support for move-only method arguments was only introduced to
2710 gMock in April 2017; in older code, you may find more complex
2711 [workarounds](#LegacyMoveOnly) for lack of this feature.
2713 Let’s say we are working on a fictional project that lets one post and share
2714 snippets called “buzzes”. Your code uses these types:
2717 enum class AccessLevel { kInternal, kPublic };
2721 explicit Buzz(AccessLevel access) { ... }
2727 virtual ~Buzzer() {}
2728 virtual std::unique_ptr<Buzz> MakeBuzz(StringPiece text) = 0;
2729 virtual bool ShareBuzz(std::unique_ptr<Buzz> buzz, int64_t timestamp) = 0;
2734 A `Buzz` object represents a snippet being posted. A class that implements the
2735 `Buzzer` interface is capable of creating and sharing `Buzz`es. Methods in
2736 `Buzzer` may return a `unique_ptr<Buzz>` or take a `unique_ptr<Buzz>`. Now we
2737 need to mock `Buzzer` in our tests.
2739 To mock a method that accepts or returns move-only types, you just use the
2740 familiar `MOCK_METHOD` syntax as usual:
2743 class MockBuzzer : public Buzzer {
2745 MOCK_METHOD(std::unique_ptr<Buzz>, MakeBuzz, (StringPiece text), (override));
2746 MOCK_METHOD(bool, ShareBuzz, (std::unique_ptr<Buzz> buzz, int64_t timestamp),
2751 Now that we have the mock class defined, we can use it in tests. In the
2752 following code examples, we assume that we have defined a `MockBuzzer` object
2753 named `mock_buzzer_`:
2756 MockBuzzer mock_buzzer_;
2759 First let’s see how we can set expectations on the `MakeBuzz()` method, which
2760 returns a `unique_ptr<Buzz>`.
2762 As usual, if you set an expectation without an action (i.e. the `.WillOnce()` or
2763 `.WillRepeatedly()` clause), when that expectation fires, the default action for
2764 that method will be taken. Since `unique_ptr<>` has a default constructor that
2765 returns a null `unique_ptr`, that’s what you’ll get if you don’t specify an
2769 // Use the default action.
2770 EXPECT_CALL(mock_buzzer_, MakeBuzz("hello"));
2772 // Triggers the previous EXPECT_CALL.
2773 EXPECT_EQ(nullptr, mock_buzzer_.MakeBuzz("hello"));
2776 If you are not happy with the default action, you can tweak it as usual; see
2777 [Setting Default Actions](#OnCall).
2779 If you just need to return a pre-defined move-only value, you can use the
2780 `Return(ByMove(...))` action:
2783 // When this fires, the unique_ptr<> specified by ByMove(...) will
2785 EXPECT_CALL(mock_buzzer_, MakeBuzz("world"))
2786 .WillOnce(Return(ByMove(MakeUnique<Buzz>(AccessLevel::kInternal))));
2788 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("world"));
2791 Note that `ByMove()` is essential here - if you drop it, the code won’t compile.
2793 Quiz time! What do you think will happen if a `Return(ByMove(...))` action is
2794 performed more than once (e.g. you write `...
2795 .WillRepeatedly(Return(ByMove(...)));`)? Come think of it, after the first time
2796 the action runs, the source value will be consumed (since it’s a move-only
2797 value), so the next time around, there’s no value to move from -- you’ll get a
2798 run-time error that `Return(ByMove(...))` can only be run once.
2800 If you need your mock method to do more than just moving a pre-defined value,
2801 remember that you can always use a lambda or a callable object, which can do
2802 pretty much anything you want:
2805 EXPECT_CALL(mock_buzzer_, MakeBuzz("x"))
2806 .WillRepeatedly([](StringPiece text) {
2807 return MakeUnique<Buzz>(AccessLevel::kInternal);
2810 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x"));
2811 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x"));
2814 Every time this `EXPECT_CALL` fires, a new `unique_ptr<Buzz>` will be created
2815 and returned. You cannot do this with `Return(ByMove(...))`.
2817 That covers returning move-only values; but how do we work with methods
2818 accepting move-only arguments? The answer is that they work normally, although
2819 some actions will not compile when any of method's arguments are move-only. You
2820 can always use `Return`, or a [lambda or functor](#FunctionsAsActions):
2823 using ::testing::Unused;
2825 EXPECT_CALL(mock_buzzer_, ShareBuzz(NotNull(), _)).WillOnce(Return(true));
2826 EXPECT_TRUE(mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal)),
2829 EXPECT_CALL(mock_buzzer_, ShareBuzz(_, _)).WillOnce(
2830 [](std::unique_ptr<Buzz> buzz, Unused) { return buzz != nullptr; });
2831 EXPECT_FALSE(mock_buzzer_.ShareBuzz(nullptr, 0));
2834 Many built-in actions (`WithArgs`, `WithoutArgs`,`DeleteArg`, `SaveArg`, ...)
2835 could in principle support move-only arguments, but the support for this is not
2836 implemented yet. If this is blocking you, please file a bug.
2838 A few actions (e.g. `DoAll`) copy their arguments internally, so they can never
2839 work with non-copyable objects; you'll have to use functors instead.
2841 #### Legacy workarounds for move-only types {#LegacyMoveOnly}
2843 Support for move-only function arguments was only introduced to gMock in April
2844 of 2017. In older code, you may encounter the following workaround for the lack
2845 of this feature (it is no longer necessary - we're including it just for
2849 class MockBuzzer : public Buzzer {
2851 MOCK_METHOD(bool, DoShareBuzz, (Buzz* buzz, Time timestamp));
2852 bool ShareBuzz(std::unique_ptr<Buzz> buzz, Time timestamp) override {
2853 return DoShareBuzz(buzz.get(), timestamp);
2858 The trick is to delegate the `ShareBuzz()` method to a mock method (let’s call
2859 it `DoShareBuzz()`) that does not take move-only parameters. Then, instead of
2860 setting expectations on `ShareBuzz()`, you set them on the `DoShareBuzz()` mock
2864 MockBuzzer mock_buzzer_;
2865 EXPECT_CALL(mock_buzzer_, DoShareBuzz(NotNull(), _));
2867 // When one calls ShareBuzz() on the MockBuzzer like this, the call is
2868 // forwarded to DoShareBuzz(), which is mocked. Therefore this statement
2869 // will trigger the above EXPECT_CALL.
2870 mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal), 0);
2873 ### Making the Compilation Faster
2875 Believe it or not, the *vast majority* of the time spent on compiling a mock
2876 class is in generating its constructor and destructor, as they perform
2877 non-trivial tasks (e.g. verification of the expectations). What's more, mock
2878 methods with different signatures have different types and thus their
2879 constructors/destructors need to be generated by the compiler separately. As a
2880 result, if you mock many different types of methods, compiling your mock class
2881 can get really slow.
2883 If you are experiencing slow compilation, you can move the definition of your
2884 mock class' constructor and destructor out of the class body and into a `.cc`
2885 file. This way, even if you `#include` your mock class in N files, the compiler
2886 only needs to generate its constructor and destructor once, resulting in a much
2889 Let's illustrate the idea using an example. Here's the definition of a mock
2890 class before applying this recipe:
2895 class MockFoo : public Foo {
2897 // Since we don't declare the constructor or the destructor,
2898 // the compiler will generate them in every translation unit
2899 // where this mock class is used.
2901 MOCK_METHOD(int, DoThis, (), (override));
2902 MOCK_METHOD(bool, DoThat, (const char* str), (override));
2903 ... more mock methods ...
2907 After the change, it would look like:
2912 class MockFoo : public Foo {
2914 // The constructor and destructor are declared, but not defined, here.
2918 MOCK_METHOD(int, DoThis, (), (override));
2919 MOCK_METHOD(bool, DoThat, (const char* str), (override));
2920 ... more mock methods ...
2927 // File mock_foo.cc.
2928 #include "path/to/mock_foo.h"
2930 // The definitions may appear trivial, but the functions actually do a
2931 // lot of things through the constructors/destructors of the member
2932 // variables used to implement the mock methods.
2933 MockFoo::MockFoo() {}
2934 MockFoo::~MockFoo() {}
2937 ### Forcing a Verification
2939 When it's being destroyed, your friendly mock object will automatically verify
2940 that all expectations on it have been satisfied, and will generate googletest
2941 failures if not. This is convenient as it leaves you with one less thing to
2942 worry about. That is, unless you are not sure if your mock object will be
2945 How could it be that your mock object won't eventually be destroyed? Well, it
2946 might be created on the heap and owned by the code you are testing. Suppose
2947 there's a bug in that code and it doesn't delete the mock object properly - you
2948 could end up with a passing test when there's actually a bug.
2950 Using a heap checker is a good idea and can alleviate the concern, but its
2951 implementation is not 100% reliable. So, sometimes you do want to *force* gMock
2952 to verify a mock object before it is (hopefully) destructed. You can do this
2953 with `Mock::VerifyAndClearExpectations(&mock_object)`:
2956 TEST(MyServerTest, ProcessesRequest) {
2957 using ::testing::Mock;
2959 MockFoo* const foo = new MockFoo;
2960 EXPECT_CALL(*foo, ...)...;
2961 // ... other expectations ...
2963 // server now owns foo.
2964 MyServer server(foo);
2965 server.ProcessRequest(...);
2967 // In case that server's destructor will forget to delete foo,
2968 // this will verify the expectations anyway.
2969 Mock::VerifyAndClearExpectations(foo);
2970 } // server is destroyed when it goes out of scope here.
2974 **Tip:** The `Mock::VerifyAndClearExpectations()` function returns a `bool` to
2975 indicate whether the verification was successful (`true` for yes), so you can
2976 wrap that function call inside a `ASSERT_TRUE()` if there is no point going
2977 further when the verification has failed.
2979 Do not set new expectations after verifying and clearing a mock after its use.
2980 Setting expectations after code that exercises the mock has undefined behavior.
2981 See [Using Mocks in Tests](gmock_for_dummies.md#using-mocks-in-tests) for more
2984 ### Using Checkpoints {#UsingCheckPoints}
2986 Sometimes you might want to test a mock object's behavior in phases whose sizes
2987 are each manageable, or you might want to set more detailed expectations about
2988 which API calls invoke which mock functions.
2990 A technique you can use is to put the expectations in a sequence and insert
2991 calls to a dummy "checkpoint" function at specific places. Then you can verify
2992 that the mock function calls do happen at the right time. For example, if you
2993 are exercising the code:
3001 and want to verify that `Foo(1)` and `Foo(3)` both invoke `mock.Bar("a")`, but
3002 `Foo(2)` doesn't invoke anything, you can write:
3005 using ::testing::MockFunction;
3007 TEST(FooTest, InvokesBarCorrectly) {
3009 // Class MockFunction<F> has exactly one mock method. It is named
3010 // Call() and has type F.
3011 MockFunction<void(string check_point_name)> check;
3015 EXPECT_CALL(mock, Bar("a"));
3016 EXPECT_CALL(check, Call("1"));
3017 EXPECT_CALL(check, Call("2"));
3018 EXPECT_CALL(mock, Bar("a"));
3028 The expectation spec says that the first `Bar("a")` call must happen before
3029 checkpoint "1", the second `Bar("a")` call must happen after checkpoint "2", and
3030 nothing should happen between the two checkpoints. The explicit checkpoints make
3031 it clear which `Bar("a")` is called by which call to `Foo()`.
3033 ### Mocking Destructors
3035 Sometimes you want to make sure a mock object is destructed at the right time,
3036 e.g. after `bar->A()` is called but before `bar->B()` is called. We already know
3037 that you can specify constraints on the [order](#OrderedCalls) of mock function
3038 calls, so all we need to do is to mock the destructor of the mock function.
3040 This sounds simple, except for one problem: a destructor is a special function
3041 with special syntax and special semantics, and the `MOCK_METHOD` macro doesn't
3045 MOCK_METHOD(void, ~MockFoo, ()); // Won't compile!
3048 The good news is that you can use a simple pattern to achieve the same effect.
3049 First, add a mock function `Die()` to your mock class and call it in the
3050 destructor, like this:
3053 class MockFoo : public Foo {
3055 // Add the following two lines to the mock class.
3056 MOCK_METHOD(void, Die, ());
3057 ~MockFoo() override { Die(); }
3061 (If the name `Die()` clashes with an existing symbol, choose another name.) Now,
3062 we have translated the problem of testing when a `MockFoo` object dies to
3063 testing when its `Die()` method is called:
3066 MockFoo* foo = new MockFoo;
3067 MockBar* bar = new MockBar;
3072 // Expects *foo to die after bar->A() and before bar->B().
3073 EXPECT_CALL(*bar, A());
3074 EXPECT_CALL(*foo, Die());
3075 EXPECT_CALL(*bar, B());
3081 ### Using gMock and Threads {#UsingThreads}
3083 In a **unit** test, it's best if you could isolate and test a piece of code in a
3084 single-threaded context. That avoids race conditions and dead locks, and makes
3085 debugging your test much easier.
3087 Yet most programs are multi-threaded, and sometimes to test something we need to
3088 pound on it from more than one thread. gMock works for this purpose too.
3090 Remember the steps for using a mock:
3092 1. Create a mock object `foo`.
3093 2. Set its default actions and expectations using `ON_CALL()` and
3095 3. The code under test calls methods of `foo`.
3096 4. Optionally, verify and reset the mock.
3097 5. Destroy the mock yourself, or let the code under test destroy it. The
3098 destructor will automatically verify it.
3100 If you follow the following simple rules, your mocks and threads can live
3103 * Execute your *test code* (as opposed to the code being tested) in *one*
3104 thread. This makes your test easy to follow.
3105 * Obviously, you can do step #1 without locking.
3106 * When doing step #2 and #5, make sure no other thread is accessing `foo`.
3108 * #3 and #4 can be done either in one thread or in multiple threads - anyway
3109 you want. gMock takes care of the locking, so you don't have to do any -
3110 unless required by your test logic.
3112 If you violate the rules (for example, if you set expectations on a mock while
3113 another thread is calling its methods), you get undefined behavior. That's not
3114 fun, so don't do it.
3116 gMock guarantees that the action for a mock function is done in the same thread
3117 that called the mock function. For example, in
3120 EXPECT_CALL(mock, Foo(1))
3122 EXPECT_CALL(mock, Foo(2))
3126 if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, gMock will
3127 execute `action1` in thread 1 and `action2` in thread 2.
3129 gMock does *not* impose a sequence on actions performed in different threads
3130 (doing so may create deadlocks as the actions may need to cooperate). This means
3131 that the execution of `action1` and `action2` in the above example *may*
3132 interleave. If this is a problem, you should add proper synchronization logic to
3133 `action1` and `action2` to make the test thread-safe.
3135 Also, remember that `DefaultValue<T>` is a global resource that potentially
3136 affects *all* living mock objects in your program. Naturally, you won't want to
3137 mess with it from multiple threads or when there still are mocks in action.
3139 ### Controlling How Much Information gMock Prints
3141 When gMock sees something that has the potential of being an error (e.g. a mock
3142 function with no expectation is called, a.k.a. an uninteresting call, which is
3143 allowed but perhaps you forgot to explicitly ban the call), it prints some
3144 warning messages, including the arguments of the function, the return value, and
3145 the stack trace. Hopefully this will remind you to take a look and see if there
3146 is indeed a problem.
3148 Sometimes you are confident that your tests are correct and may not appreciate
3149 such friendly messages. Some other times, you are debugging your tests or
3150 learning about the behavior of the code you are testing, and wish you could
3151 observe every mock call that happens (including argument values, the return
3152 value, and the stack trace). Clearly, one size doesn't fit all.
3154 You can control how much gMock tells you using the `--gmock_verbose=LEVEL`
3155 command-line flag, where `LEVEL` is a string with three possible values:
3157 * `info`: gMock will print all informational messages, warnings, and errors
3158 (most verbose). At this setting, gMock will also log any calls to the
3159 `ON_CALL/EXPECT_CALL` macros. It will include a stack trace in
3160 "uninteresting call" warnings.
3161 * `warning`: gMock will print both warnings and errors (less verbose); it will
3162 omit the stack traces in "uninteresting call" warnings. This is the default.
3163 * `error`: gMock will print errors only (least verbose).
3165 Alternatively, you can adjust the value of that flag from within your tests like
3169 ::testing::FLAGS_gmock_verbose = "error";
3172 If you find gMock printing too many stack frames with its informational or
3173 warning messages, remember that you can control their amount with the
3174 `--gtest_stack_trace_depth=max_depth` flag.
3176 Now, judiciously use the right flag to enable gMock serve you better!
3178 ### Gaining Super Vision into Mock Calls
3180 You have a test using gMock. It fails: gMock tells you some expectations aren't
3181 satisfied. However, you aren't sure why: Is there a typo somewhere in the
3182 matchers? Did you mess up the order of the `EXPECT_CALL`s? Or is the code under
3183 test doing something wrong? How can you find out the cause?
3185 Won't it be nice if you have X-ray vision and can actually see the trace of all
3186 `EXPECT_CALL`s and mock method calls as they are made? For each call, would you
3187 like to see its actual argument values and which `EXPECT_CALL` gMock thinks it
3188 matches? If you still need some help to figure out who made these calls, how
3189 about being able to see the complete stack trace at each mock call?
3191 You can unlock this power by running your test with the `--gmock_verbose=info`
3192 flag. For example, given the test program:
3195 #include "gmock/gmock.h"
3198 using testing::HasSubstr;
3199 using testing::Return;
3203 MOCK_METHOD(void, F, (const string& x, const string& y));
3208 EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return());
3209 EXPECT_CALL(mock, F("a", "b"));
3210 EXPECT_CALL(mock, F("c", HasSubstr("d")));
3212 mock.F("a", "good");
3217 if you run it with `--gmock_verbose=info`, you will see this output:
3222 foo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked
3225 foo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked
3228 foo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked
3231 foo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))...
3232 Function call: F(@0x7fff7c8dad40"a",@0x7fff7c8dad10"good")
3235 foo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))...
3236 Function call: F(@0x7fff7c8dada0"a",@0x7fff7c8dad70"b")
3239 foo_test.cc:16: Failure
3240 Actual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))...
3241 Expected: to be called once
3242 Actual: never called - unsatisfied and active
3246 Suppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo and
3247 should actually be `"a"`. With the above message, you should see that the actual
3248 `F("a", "good")` call is matched by the first `EXPECT_CALL`, not the third as
3249 you thought. From that it should be obvious that the third `EXPECT_CALL` is
3250 written wrong. Case solved.
3252 If you are interested in the mock call trace but not the stack traces, you can
3253 combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test
3256 ### Running Tests in Emacs
3258 If you build and run your tests in Emacs using the `M-x google-compile` command
3259 (as many googletest users do), the source file locations of gMock and googletest
3260 errors will be highlighted. Just press `<Enter>` on one of them and you'll be
3261 taken to the offending line. Or, you can just type `C-x`` to jump to the next
3264 To make it even easier, you can add the following lines to your `~/.emacs` file:
3267 (global-set-key "\M-m" 'google-compile) ; m is for make
3268 (global-set-key [M-down] 'next-error)
3269 (global-set-key [M-up] '(lambda () (interactive) (next-error -1)))
3272 Then you can type `M-m` to start a build (if you want to run the test as well,
3273 just make sure `foo_test.run` or `runtests` is in the build command you supply
3274 after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors.
3278 ### Writing New Matchers Quickly {#NewMatchers}
3280 {: .callout .warning}
3281 WARNING: gMock does not guarantee when or how many times a matcher will be
3282 invoked. Therefore, all matchers must be functionally pure. See
3283 [this section](#PureMatchers) for more details.
3285 The `MATCHER*` family of macros can be used to define custom matchers easily.
3289 MATCHER(name, description_string_expression) { statements; }
3292 will define a matcher with the given name that executes the statements, which
3293 must return a `bool` to indicate if the match succeeds. Inside the statements,
3294 you can refer to the value being matched by `arg`, and refer to its type by
3297 The *description string* is a `string`-typed expression that documents what the
3298 matcher does, and is used to generate the failure message when the match fails.
3299 It can (and should) reference the special `bool` variable `negation`, and should
3300 evaluate to the description of the matcher when `negation` is `false`, or that
3301 of the matcher's negation when `negation` is `true`.
3303 For convenience, we allow the description string to be empty (`""`), in which
3304 case gMock will use the sequence of words in the matcher name as the
3310 MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; }
3316 // Expects mock_foo.Bar(n) to be called where n is divisible by 7.
3317 EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7()));
3323 using ::testing::Not;
3325 // Verifies that a value is divisible by 7 and the other is not.
3326 EXPECT_THAT(some_expression, IsDivisibleBy7());
3327 EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7()));
3330 If the above assertions fail, they will print something like:
3333 Value of: some_expression
3334 Expected: is divisible by 7
3337 Value of: some_other_expression
3338 Expected: not (is divisible by 7)
3342 where the descriptions `"is divisible by 7"` and `"not (is divisible by 7)"` are
3343 automatically calculated from the matcher name `IsDivisibleBy7`.
3345 As you may have noticed, the auto-generated descriptions (especially those for
3346 the negation) may not be so great. You can always override them with a `string`
3347 expression of your own:
3350 MATCHER(IsDivisibleBy7,
3351 absl::StrCat(negation ? "isn't" : "is", " divisible by 7")) {
3352 return (arg % 7) == 0;
3356 Optionally, you can stream additional information to a hidden argument named
3357 `result_listener` to explain the match result. For example, a better definition
3358 of `IsDivisibleBy7` is:
3361 MATCHER(IsDivisibleBy7, "") {
3365 *result_listener << "the remainder is " << (arg % 7);
3370 With this definition, the above assertion will give a better message:
3373 Value of: some_expression
3374 Expected: is divisible by 7
3375 Actual: 27 (the remainder is 6)
3378 You should let `MatchAndExplain()` print *any additional information* that can
3379 help a user understand the match result. Note that it should explain why the
3380 match succeeds in case of a success (unless it's obvious) - this is useful when
3381 the matcher is used inside `Not()`. There is no need to print the argument value
3382 itself, as gMock already prints it for you.
3385 NOTE: The type of the value being matched (`arg_type`) is determined by the
3386 context in which you use the matcher and is supplied to you by the compiler, so
3387 you don't need to worry about declaring it (nor can you). This allows the
3388 matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match
3389 any type where the value of `(arg % 7) == 0` can be implicitly converted to a
3390 `bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an
3391 `int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will
3392 be `unsigned long`; and so on.
3394 ### Writing New Parameterized Matchers Quickly
3396 Sometimes you'll want to define a matcher that has parameters. For that you can
3400 MATCHER_P(name, param_name, description_string) { statements; }
3403 where the description string can be either `""` or a `string` expression that
3404 references `negation` and `param_name`.
3409 MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
3412 will allow you to write:
3415 EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
3418 which may lead to this message (assuming `n` is 10):
3422 Expected: has absolute value 10
3426 Note that both the matcher description and its parameter are printed, making the
3427 message human-friendly.
3429 In the matcher definition body, you can write `foo_type` to reference the type
3430 of a parameter named `foo`. For example, in the body of
3431 `MATCHER_P(HasAbsoluteValue, value)` above, you can write `value_type` to refer
3432 to the type of `value`.
3434 gMock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to `MATCHER_P10` to
3435 support multi-parameter matchers:
3438 MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; }
3441 Please note that the custom description string is for a particular *instance* of
3442 the matcher, where the parameters have been bound to actual values. Therefore
3443 usually you'll want the parameter values to be part of the description. gMock
3444 lets you do that by referencing the matcher parameters in the description string
3450 using ::testing::PrintToString;
3451 MATCHER_P2(InClosedRange, low, hi,
3452 absl::StrFormat("%s in range [%s, %s]", negation ? "isn't" : "is",
3453 PrintToString(low), PrintToString(hi))) {
3454 return low <= arg && arg <= hi;
3457 EXPECT_THAT(3, InClosedRange(4, 6));
3460 would generate a failure that contains the message:
3463 Expected: is in range [4, 6]
3466 If you specify `""` as the description, the failure message will contain the
3467 sequence of words in the matcher name followed by the parameter values printed
3468 as a tuple. For example,
3471 MATCHER_P2(InClosedRange, low, hi, "") { ... }
3473 EXPECT_THAT(3, InClosedRange(4, 6));
3476 would generate a failure that contains the text:
3479 Expected: in closed range (4, 6)
3482 For the purpose of typing, you can view
3485 MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
3491 template <typename p1_type, ..., typename pk_type>
3492 FooMatcherPk<p1_type, ..., pk_type>
3493 Foo(p1_type p1, ..., pk_type pk) { ... }
3496 When you write `Foo(v1, ..., vk)`, the compiler infers the types of the
3497 parameters `v1`, ..., and `vk` for you. If you are not happy with the result of
3498 the type inference, you can specify the types by explicitly instantiating the
3499 template, as in `Foo<long, bool>(5, false)`. As said earlier, you don't get to
3500 (or need to) specify `arg_type` as that's determined by the context in which the
3503 You can assign the result of expression `Foo(p1, ..., pk)` to a variable of type
3504 `FooMatcherPk<p1_type, ..., pk_type>`. This can be useful when composing
3505 matchers. Matchers that don't have a parameter or have only one parameter have
3506 special types: you can assign `Foo()` to a `FooMatcher`-typed variable, and
3507 assign `Foo(p)` to a `FooMatcherP<p_type>`-typed variable.
3509 While you can instantiate a matcher template with reference types, passing the
3510 parameters by pointer usually makes your code more readable. If, however, you
3511 still want to pass a parameter by reference, be aware that in the failure
3512 message generated by the matcher you will see the value of the referenced object
3513 but not its address.
3515 You can overload matchers with different numbers of parameters:
3518 MATCHER_P(Blah, a, description_string_1) { ... }
3519 MATCHER_P2(Blah, a, b, description_string_2) { ... }
3522 While it's tempting to always use the `MATCHER*` macros when defining a new
3523 matcher, you should also consider implementing the matcher interface directly
3524 instead (see the recipes that follow), especially if you need to use the matcher
3525 a lot. While these approaches require more work, they give you more control on
3526 the types of the value being matched and the matcher parameters, which in
3527 general leads to better compiler error messages that pay off in the long run.
3528 They also allow overloading matchers based on parameter types (as opposed to
3529 just based on the number of parameters).
3531 ### Writing New Monomorphic Matchers
3533 A matcher of argument type `T` implements the matcher interface for `T` and does
3534 two things: it tests whether a value of type `T` matches the matcher, and can
3535 describe what kind of values it matches. The latter ability is used for
3536 generating readable error messages when expectations are violated.
3538 A matcher of `T` must declare a typedef like:
3541 using is_gtest_matcher = void;
3544 and supports the following operations:
3547 // Match a value and optionally explain into an ostream.
3548 bool matched = matcher.MatchAndExplain(value, maybe_os);
3549 // where `value` is of type `T` and
3550 // `maybe_os` is of type `std::ostream*`, where it can be null if the caller
3551 // is not interested in there textual explanation.
3553 matcher.DescribeTo(os);
3554 matcher.DescribeNegationTo(os);
3555 // where `os` is of type `std::ostream*`.
3558 If you need a custom matcher but `Truly()` is not a good option (for example,
3559 you may not be happy with the way `Truly(predicate)` describes itself, or you
3560 may want your matcher to be polymorphic as `Eq(value)` is), you can define a
3561 matcher to do whatever you want in two steps: first implement the matcher
3562 interface, and then define a factory function to create a matcher instance. The
3563 second step is not strictly needed but it makes the syntax of using the matcher
3566 For example, you can define a matcher to test whether an `int` is divisible by 7
3567 and then use it like this:
3570 using ::testing::Matcher;
3572 class DivisibleBy7Matcher {
3574 using is_gtest_matcher = void;
3576 bool MatchAndExplain(int n, std::ostream*) const {
3577 return (n % 7) == 0;
3580 void DescribeTo(std::ostream* os) const {
3581 *os << "is divisible by 7";
3584 void DescribeNegationTo(std::ostream* os) const {
3585 *os << "is not divisible by 7";
3589 Matcher<int> DivisibleBy7() {
3590 return DivisibleBy7Matcher();
3594 EXPECT_CALL(foo, Bar(DivisibleBy7()));
3597 You may improve the matcher message by streaming additional information to the
3598 `os` argument in `MatchAndExplain()`:
3601 class DivisibleBy7Matcher {
3603 bool MatchAndExplain(int n, std::ostream* os) const {
3604 const int remainder = n % 7;
3605 if (remainder != 0 && os != nullptr) {
3606 *os << "the remainder is " << remainder;
3608 return remainder == 0;
3614 Then, `EXPECT_THAT(x, DivisibleBy7());` may generate a message like this:
3618 Expected: is divisible by 7
3619 Actual: 23 (the remainder is 2)
3623 Tip: for convenience, `MatchAndExplain()` can take a `MatchResultListener*`
3624 instead of `std::ostream*`.
3626 ### Writing New Polymorphic Matchers
3628 Expanding what we learned above to *polymorphic* matchers is now just as simple
3629 as adding templates in the right place.
3633 class NotNullMatcher {
3635 using is_gtest_matcher = void;
3637 // To implement a polymorphic matcher, we just need to make MatchAndExplain a
3638 // template on its first argument.
3640 // In this example, we want to use NotNull() with any pointer, so
3641 // MatchAndExplain() accepts a pointer of any type as its first argument.
3642 // In general, you can define MatchAndExplain() as an ordinary method or
3643 // a method template, or even overload it.
3644 template <typename T>
3645 bool MatchAndExplain(T* p, std::ostream*) const {
3646 return p != nullptr;
3649 // Describes the property of a value matching this matcher.
3650 void DescribeTo(std::ostream* os) const { *os << "is not NULL"; }
3652 // Describes the property of a value NOT matching this matcher.
3653 void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; }
3656 NotNullMatcher NotNull() {
3657 return NotNullMatcher();
3662 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
3665 ### Legacy Matcher Implementation
3667 Defining matchers used to be somewhat more complicated, in which it required
3668 several supporting classes and virtual functions. To implement a matcher for
3669 type `T` using the legacy API you have to derive from `MatcherInterface<T>` and
3670 call `MakeMatcher` to construct the object.
3672 The interface looks like this:
3675 class MatchResultListener {
3678 // Streams x to the underlying ostream; does nothing if the ostream
3680 template <typename T>
3681 MatchResultListener& operator<<(const T& x);
3683 // Returns the underlying ostream.
3684 std::ostream* stream();
3687 template <typename T>
3688 class MatcherInterface {
3690 virtual ~MatcherInterface();
3692 // Returns true if and only if the matcher matches x; also explains the match
3693 // result to 'listener'.
3694 virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0;
3696 // Describes this matcher to an ostream.
3697 virtual void DescribeTo(std::ostream* os) const = 0;
3699 // Describes the negation of this matcher to an ostream.
3700 virtual void DescribeNegationTo(std::ostream* os) const;
3704 Fortunately, most of the time you can define a polymorphic matcher easily with
3705 the help of `MakePolymorphicMatcher()`. Here's how you can define `NotNull()` as
3709 using ::testing::MakePolymorphicMatcher;
3710 using ::testing::MatchResultListener;
3711 using ::testing::PolymorphicMatcher;
3713 class NotNullMatcher {
3715 // To implement a polymorphic matcher, first define a COPYABLE class
3716 // that has three members MatchAndExplain(), DescribeTo(), and
3717 // DescribeNegationTo(), like the following.
3719 // In this example, we want to use NotNull() with any pointer, so
3720 // MatchAndExplain() accepts a pointer of any type as its first argument.
3721 // In general, you can define MatchAndExplain() as an ordinary method or
3722 // a method template, or even overload it.
3723 template <typename T>
3724 bool MatchAndExplain(T* p,
3725 MatchResultListener* /* listener */) const {
3729 // Describes the property of a value matching this matcher.
3730 void DescribeTo(std::ostream* os) const { *os << "is not NULL"; }
3732 // Describes the property of a value NOT matching this matcher.
3733 void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; }
3736 // To construct a polymorphic matcher, pass an instance of the class
3737 // to MakePolymorphicMatcher(). Note the return type.
3738 PolymorphicMatcher<NotNullMatcher> NotNull() {
3739 return MakePolymorphicMatcher(NotNullMatcher());
3744 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
3748 **Note:** Your polymorphic matcher class does **not** need to inherit from
3749 `MatcherInterface` or any other class, and its methods do **not** need to be
3752 Like in a monomorphic matcher, you may explain the match result by streaming
3753 additional information to the `listener` argument in `MatchAndExplain()`.
3755 ### Writing New Cardinalities
3757 A cardinality is used in `Times()` to tell gMock how many times you expect a
3758 call to occur. It doesn't have to be exact. For example, you can say
3759 `AtLeast(5)` or `Between(2, 4)`.
3761 If the [built-in set](gmock_cheat_sheet.md#CardinalityList) of cardinalities
3762 doesn't suit you, you are free to define your own by implementing the following
3763 interface (in namespace `testing`):
3766 class CardinalityInterface {
3768 virtual ~CardinalityInterface();
3770 // Returns true if and only if call_count calls will satisfy this cardinality.
3771 virtual bool IsSatisfiedByCallCount(int call_count) const = 0;
3773 // Returns true if and only if call_count calls will saturate this
3775 virtual bool IsSaturatedByCallCount(int call_count) const = 0;
3777 // Describes self to an ostream.
3778 virtual void DescribeTo(std::ostream* os) const = 0;
3782 For example, to specify that a call must occur even number of times, you can
3786 using ::testing::Cardinality;
3787 using ::testing::CardinalityInterface;
3788 using ::testing::MakeCardinality;
3790 class EvenNumberCardinality : public CardinalityInterface {
3792 bool IsSatisfiedByCallCount(int call_count) const override {
3793 return (call_count % 2) == 0;
3796 bool IsSaturatedByCallCount(int call_count) const override {
3800 void DescribeTo(std::ostream* os) const {
3801 *os << "called even number of times";
3805 Cardinality EvenNumber() {
3806 return MakeCardinality(new EvenNumberCardinality);
3810 EXPECT_CALL(foo, Bar(3))
3811 .Times(EvenNumber());
3814 ### Writing New Actions {#QuickNewActions}
3816 If the built-in actions don't work for you, you can easily define your own one.
3817 All you need is a call operator with a signature compatible with the mocked
3818 function. So you can use a lambda:
3821 MockFunction<int(int)> mock;
3822 EXPECT_CALL(mock, Call).WillOnce([](const int input) { return input * 7; });
3823 EXPECT_EQ(14, mock.AsStdFunction()(2));
3826 Or a struct with a call operator (even a templated one):
3830 template <typename T>
3831 T operator()(T arg) { return arg * multiplier; }
3837 // EXPECT_CALL(...).WillOnce(MultiplyBy{7});
3840 It's also fine for the callable to take no arguments, ignoring the arguments
3841 supplied to the mock function:
3844 MockFunction<int(int)> mock;
3845 EXPECT_CALL(mock, Call).WillOnce([] { return 17; });
3846 EXPECT_EQ(17, mock.AsStdFunction()(0));
3849 When used with `WillOnce`, the callable can assume it will be called at most
3850 once and is allowed to be a move-only type:
3853 // An action that contains move-only types and has an &&-qualified operator,
3854 // demanding in the type system that it be called at most once. This can be
3855 // used with WillOnce, but the compiler will reject it if handed to
3857 struct MoveOnlyAction {
3858 std::unique_ptr<int> move_only_state;
3859 std::unique_ptr<int> operator()() && { return std::move(move_only_state); }
3862 MockFunction<std::unique_ptr<int>()> mock;
3863 EXPECT_CALL(mock, Call).WillOnce(MoveOnlyAction{std::make_unique<int>(17)});
3864 EXPECT_THAT(mock.AsStdFunction()(), Pointee(Eq(17)));
3867 More generally, to use with a mock function whose signature is `R(Args...)` the
3868 object can be anything convertible to `OnceAction<R(Args...)>` or
3869 `Action<R(Args...)`>. The difference between the two is that `OnceAction` has
3870 weaker requirements (`Action` requires a copy-constructible input that can be
3871 called repeatedly whereas `OnceAction` requires only move-constructible and
3872 supports `&&`-qualified call operators), but can be used only with `WillOnce`.
3873 `OnceAction` is typically relevant only when supporting move-only types or
3874 actions that want a type-system guarantee that they will be called at most once.
3876 Typically the `OnceAction` and `Action` templates need not be referenced
3877 directly in your actions: a struct or class with a call operator is sufficient,
3878 as in the examples above. But fancier polymorphic actions that need to know the
3879 specific return type of the mock function can define templated conversion
3880 operators to make that possible. See `gmock-actions.h` for examples.
3882 #### Legacy macro-based Actions
3884 Before C++11, the functor-based actions were not supported; the old way of
3885 writing actions was through a set of `ACTION*` macros. We suggest to avoid them
3886 in new code; they hide a lot of logic behind the macro, potentially leading to
3887 harder-to-understand compiler errors. Nevertheless, we cover them here for
3893 ACTION(name) { statements; }
3896 in a namespace scope (i.e. not inside a class or function), you will define an
3897 action with the given name that executes the statements. The value returned by
3898 `statements` will be used as the return value of the action. Inside the
3899 statements, you can refer to the K-th (0-based) argument of the mock function as
3900 `argK`. For example:
3903 ACTION(IncrementArg1) { return ++(*arg1); }
3909 ... WillOnce(IncrementArg1());
3912 Note that you don't need to specify the types of the mock function arguments.
3913 Rest assured that your code is type-safe though: you'll get a compiler error if
3914 `*arg1` doesn't support the `++` operator, or if the type of `++(*arg1)` isn't
3915 compatible with the mock function's return type.
3928 defines an action `Foo()` that invokes argument #2 (a function pointer) with 5,
3929 calls function `Blah()`, sets the value pointed to by argument #1 to 0, and
3930 returns argument #0.
3932 For more convenience and flexibility, you can also use the following pre-defined
3933 symbols in the body of `ACTION`:
3935 `argK_type` | The type of the K-th (0-based) argument of the mock function
3936 :-------------- | :-----------------------------------------------------------
3937 `args` | All arguments of the mock function as a tuple
3938 `args_type` | The type of all arguments of the mock function as a tuple
3939 `return_type` | The return type of the mock function
3940 `function_type` | The type of the mock function
3942 For example, when using an `ACTION` as a stub action for mock function:
3945 int DoSomething(bool flag, int* ptr);
3950 Pre-defined Symbol | Is Bound To
3951 ------------------ | ---------------------------------
3952 `arg0` | the value of `flag`
3953 `arg0_type` | the type `bool`
3954 `arg1` | the value of `ptr`
3955 `arg1_type` | the type `int*`
3956 `args` | the tuple `(flag, ptr)`
3957 `args_type` | the type `std::tuple<bool, int*>`
3958 `return_type` | the type `int`
3959 `function_type` | the type `int(bool, int*)`
3961 #### Legacy macro-based parameterized Actions
3963 Sometimes you'll want to parameterize an action you define. For that we have
3967 ACTION_P(name, param) { statements; }
3973 ACTION_P(Add, n) { return arg0 + n; }
3976 will allow you to write
3979 // Returns argument #0 + 5.
3980 ... WillOnce(Add(5));
3983 For convenience, we use the term *arguments* for the values used to invoke the
3984 mock function, and the term *parameters* for the values used to instantiate an
3987 Note that you don't need to provide the type of the parameter either. Suppose
3988 the parameter is named `param`, you can also use the gMock-defined symbol
3989 `param_type` to refer to the type of the parameter as inferred by the compiler.
3990 For example, in the body of `ACTION_P(Add, n)` above, you can write `n_type` for
3993 gMock also provides `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter
3994 actions. For example,
3997 ACTION_P2(ReturnDistanceTo, x, y) {
3998 double dx = arg0 - x;
3999 double dy = arg1 - y;
4000 return sqrt(dx*dx + dy*dy);
4007 ... WillOnce(ReturnDistanceTo(5.0, 26.5));
4010 You can view `ACTION` as a degenerated parameterized action where the number of
4013 You can also easily define actions overloaded on the number of parameters:
4016 ACTION_P(Plus, a) { ... }
4017 ACTION_P2(Plus, a, b) { ... }
4020 ### Restricting the Type of an Argument or Parameter in an ACTION
4022 For maximum brevity and reusability, the `ACTION*` macros don't ask you to
4023 provide the types of the mock function arguments and the action parameters.
4024 Instead, we let the compiler infer the types for us.
4026 Sometimes, however, we may want to be more explicit about the types. There are
4027 several tricks to do that. For example:
4031 // Makes sure arg0 can be converted to int.
4033 ... use n instead of arg0 here ...
4036 ACTION_P(Bar, param) {
4037 // Makes sure the type of arg1 is const char*.
4038 ::testing::StaticAssertTypeEq<const char*, arg1_type>();
4040 // Makes sure param can be converted to bool.
4045 where `StaticAssertTypeEq` is a compile-time assertion in googletest that
4046 verifies two types are the same.
4048 ### Writing New Action Templates Quickly
4050 Sometimes you want to give an action explicit template parameters that cannot be
4051 inferred from its value parameters. `ACTION_TEMPLATE()` supports that and can be
4052 viewed as an extension to `ACTION()` and `ACTION_P*()`.
4057 ACTION_TEMPLATE(ActionName,
4058 HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m),
4059 AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; }
4062 defines an action template that takes *m* explicit template parameters and *n*
4063 value parameters, where *m* is in [1, 10] and *n* is in [0, 10]. `name_i` is the
4064 name of the *i*-th template parameter, and `kind_i` specifies whether it's a
4065 `typename`, an integral constant, or a template. `p_i` is the name of the *i*-th
4071 // DuplicateArg<k, T>(output) converts the k-th argument of the mock
4072 // function to type T and copies it to *output.
4073 ACTION_TEMPLATE(DuplicateArg,
4074 // Note the comma between int and k:
4075 HAS_2_TEMPLATE_PARAMS(int, k, typename, T),
4076 AND_1_VALUE_PARAMS(output)) {
4077 *output = T(std::get<k>(args));
4081 To create an instance of an action template, write:
4084 ActionName<t1, ..., t_m>(v1, ..., v_n)
4087 where the `t`s are the template arguments and the `v`s are the value arguments.
4088 The value argument types are inferred by the compiler. For example:
4094 EXPECT_CALL(mock, Foo).WillOnce(DuplicateArg<1, unsigned char>(&n));
4097 If you want to explicitly specify the value argument types, you can provide
4098 additional template arguments:
4101 ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n)
4104 where `u_i` is the desired type of `v_i`.
4106 `ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the number of
4107 value parameters, but not on the number of template parameters. Without the
4108 restriction, the meaning of the following is unclear:
4111 OverloadedAction<int, bool>(x);
4114 Are we using a single-template-parameter action where `bool` refers to the type
4115 of `x`, or a two-template-parameter action where the compiler is asked to infer
4118 ### Using the ACTION Object's Type
4120 If you are writing a function that returns an `ACTION` object, you'll need to
4121 know its type. The type depends on the macro used to define the action and the
4122 parameter types. The rule is relatively simple:
4125 | Given Definition | Expression | Has Type |
4126 | ----------------------------- | ------------------- | --------------------- |
4127 | `ACTION(Foo)` | `Foo()` | `FooAction` |
4128 | `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` |
4129 | `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` |
4130 | `ACTION_TEMPLATE(Bar, HAS_m_TEMPLATE_PARAMS(...), AND_1_VALUE_PARAMS(p1))` | `Bar<t1, ..., t_m>(int_value)` | `BarActionP<t1, ..., t_m, int>` |
4131 | `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` |
4132 | `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>` |
4136 Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`,
4137 and etc) for actions with different numbers of value parameters, or the action
4138 definitions cannot be overloaded on the number of them.
4140 ### Writing New Monomorphic Actions {#NewMonoActions}
4142 While the `ACTION*` macros are very convenient, sometimes they are
4143 inappropriate. For example, despite the tricks shown in the previous recipes,
4144 they don't let you directly specify the types of the mock function arguments and
4145 the action parameters, which in general leads to unoptimized compiler error
4146 messages that can baffle unfamiliar users. They also don't allow overloading
4147 actions based on parameter types without jumping through some hoops.
4149 An alternative to the `ACTION*` macros is to implement
4150 `::testing::ActionInterface<F>`, where `F` is the type of the mock function in
4151 which the action will be used. For example:
4154 template <typename F>
4155 class ActionInterface {
4157 virtual ~ActionInterface();
4159 // Performs the action. Result is the return type of function type
4160 // F, and ArgumentTuple is the tuple of arguments of F.
4163 // For example, if F is int(bool, const string&), then Result would
4164 // be int, and ArgumentTuple would be std::tuple<bool, const string&>.
4165 virtual Result Perform(const ArgumentTuple& args) = 0;
4171 using ::testing::Action;
4172 using ::testing::ActionInterface;
4173 using ::testing::MakeAction;
4175 typedef int IncrementMethod(int*);
4177 class IncrementArgumentAction : public ActionInterface<IncrementMethod> {
4179 int Perform(const std::tuple<int*>& args) override {
4180 int* p = std::get<0>(args); // Grabs the first argument.
4185 Action<IncrementMethod> IncrementArgument() {
4186 return MakeAction(new IncrementArgumentAction);
4190 EXPECT_CALL(foo, Baz(_))
4191 .WillOnce(IncrementArgument());
4194 foo.Baz(&n); // Should return 5 and change n to 6.
4197 ### Writing New Polymorphic Actions {#NewPolyActions}
4199 The previous recipe showed you how to define your own action. This is all good,
4200 except that you need to know the type of the function in which the action will
4201 be used. Sometimes that can be a problem. For example, if you want to use the
4202 action in functions with *different* types (e.g. like `Return()` and
4205 If an action can be used in several types of mock functions, we say it's
4206 *polymorphic*. The `MakePolymorphicAction()` function template makes it easy to
4207 define such an action:
4211 template <typename Impl>
4212 PolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl);
4213 } // namespace testing
4216 As an example, let's define an action that returns the second argument in the
4217 mock function's argument list. The first step is to define an implementation
4221 class ReturnSecondArgumentAction {
4223 template <typename Result, typename ArgumentTuple>
4224 Result Perform(const ArgumentTuple& args) const {
4225 // To get the i-th (0-based) argument, use std::get(args).
4226 return std::get<1>(args);
4231 This implementation class does *not* need to inherit from any particular class.
4232 What matters is that it must have a `Perform()` method template. This method
4233 template takes the mock function's arguments as a tuple in a **single**
4234 argument, and returns the result of the action. It can be either `const` or not,
4235 but must be invocable with exactly one template argument, which is the result
4236 type. In other words, you must be able to call `Perform<R>(args)` where `R` is
4237 the mock function's return type and `args` is its arguments in a tuple.
4239 Next, we use `MakePolymorphicAction()` to turn an instance of the implementation
4240 class into the polymorphic action we need. It will be convenient to have a
4244 using ::testing::MakePolymorphicAction;
4245 using ::testing::PolymorphicAction;
4247 PolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() {
4248 return MakePolymorphicAction(ReturnSecondArgumentAction());
4252 Now, you can use this polymorphic action the same way you use the built-in ones:
4257 class MockFoo : public Foo {
4259 MOCK_METHOD(int, DoThis, (bool flag, int n), (override));
4260 MOCK_METHOD(string, DoThat, (int x, const char* str1, const char* str2),
4266 EXPECT_CALL(foo, DoThis).WillOnce(ReturnSecondArgument());
4267 EXPECT_CALL(foo, DoThat).WillOnce(ReturnSecondArgument());
4269 foo.DoThis(true, 5); // Will return 5.
4270 foo.DoThat(1, "Hi", "Bye"); // Will return "Hi".
4273 ### Teaching gMock How to Print Your Values
4275 When an uninteresting or unexpected call occurs, gMock prints the argument
4276 values and the stack trace to help you debug. Assertion macros like
4277 `EXPECT_THAT` and `EXPECT_EQ` also print the values in question when the
4278 assertion fails. gMock and googletest do this using googletest's user-extensible
4281 This printer knows how to print built-in C++ types, native arrays, STL
4282 containers, and any type that supports the `<<` operator. For other types, it
4283 prints the raw bytes in the value and hopes that you the user can figure it out.
4284 [The GoogleTest advanced guide](advanced.md#teaching-googletest-how-to-print-your-values)
4285 explains how to extend the printer to do a better job at printing your
4286 particular type than to dump the bytes.
4288 ## Useful Mocks Created Using gMock
4290 <!--#include file="includes/g3_testing_LOGs.md"-->
4291 <!--#include file="includes/g3_mock_callbacks.md"-->
4293 ### Mock std::function {#MockFunction}
4295 `std::function` is a general function type introduced in C++11. It is a
4296 preferred way of passing callbacks to new interfaces. Functions are copiable,
4297 and are not usually passed around by pointer, which makes them tricky to mock.
4298 But fear not - `MockFunction` can help you with that.
4300 `MockFunction<R(T1, ..., Tn)>` has a mock method `Call()` with the signature:
4303 R Call(T1, ..., Tn);
4306 It also has a `AsStdFunction()` method, which creates a `std::function` proxy
4310 std::function<R(T1, ..., Tn)> AsStdFunction();
4313 To use `MockFunction`, first create `MockFunction` object and set up
4314 expectations on its `Call` method. Then pass proxy obtained from
4315 `AsStdFunction()` to the code you are testing. For example:
4318 TEST(FooTest, RunsCallbackWithBarArgument) {
4319 // 1. Create a mock object.
4320 MockFunction<int(string)> mock_function;
4322 // 2. Set expectations on Call() method.
4323 EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1));
4325 // 3. Exercise code that uses std::function.
4326 Foo(mock_function.AsStdFunction());
4327 // Foo's signature can be either of:
4328 // void Foo(const std::function<int(string)>& fun);
4329 // void Foo(std::function<int(string)> fun);
4331 // 4. All expectations will be verified when mock_function
4332 // goes out of scope and is destroyed.
4336 Remember that function objects created with `AsStdFunction()` are just
4337 forwarders. If you create multiple of them, they will share the same set of
4340 Although `std::function` supports unlimited number of arguments, `MockFunction`
4341 implementation is limited to ten. If you ever hit that limit... well, your
4342 callback has bigger problems than being mockable. :-)