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. (In the future, we might remove
396 this warning by default.)
398 However, sometimes you may want to ignore these uninteresting calls, and
399 sometimes you may want to treat them as errors. gMock lets you make the decision
400 on a per-mock-object basis.
402 Suppose your test uses a mock class `MockFoo`:
407 EXPECT_CALL(mock_foo, DoThis());
408 ... code that uses mock_foo ...
412 If a method of `mock_foo` other than `DoThis()` is called, you will get a
413 warning. However, if you rewrite your test to use `NiceMock<MockFoo>` instead,
414 you can suppress the warning:
417 using ::testing::NiceMock;
420 NiceMock<MockFoo> mock_foo;
421 EXPECT_CALL(mock_foo, DoThis());
422 ... code that uses mock_foo ...
426 `NiceMock<MockFoo>` is a subclass of `MockFoo`, so it can be used wherever
427 `MockFoo` is accepted.
429 It also works if `MockFoo`'s constructor takes some arguments, as
430 `NiceMock<MockFoo>` "inherits" `MockFoo`'s constructors:
433 using ::testing::NiceMock;
436 NiceMock<MockFoo> mock_foo(5, "hi"); // Calls MockFoo(5, "hi").
437 EXPECT_CALL(mock_foo, DoThis());
438 ... code that uses mock_foo ...
442 The usage of `StrictMock` is similar, except that it makes all uninteresting
446 using ::testing::StrictMock;
449 StrictMock<MockFoo> mock_foo;
450 EXPECT_CALL(mock_foo, DoThis());
451 ... code that uses mock_foo ...
453 // The test will fail if a method of mock_foo other than DoThis()
459 NOTE: `NiceMock` and `StrictMock` only affects *uninteresting* calls (calls of
460 *methods* with no expectations); they do not affect *unexpected* calls (calls of
461 methods with expectations, but they don't match). See
462 [Understanding Uninteresting vs Unexpected Calls](#uninteresting-vs-unexpected).
464 There are some caveats though (sadly they are side effects of C++'s
467 1. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` only work for mock methods
468 defined using the `MOCK_METHOD` macro **directly** in the `MockFoo` class.
469 If a mock method is defined in a **base class** of `MockFoo`, the "nice" or
470 "strict" modifier may not affect it, depending on the compiler. In
471 particular, nesting `NiceMock` and `StrictMock` (e.g.
472 `NiceMock<StrictMock<MockFoo> >`) is **not** supported.
473 2. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` may not work correctly if the
474 destructor of `MockFoo` is not virtual. We would like to fix this, but it
475 requires cleaning up existing tests.
477 Finally, you should be **very cautious** about when to use naggy or strict
478 mocks, as they tend to make tests more brittle and harder to maintain. When you
479 refactor your code without changing its externally visible behavior, ideally you
480 shouldn't need to update any tests. If your code interacts with a naggy mock,
481 however, you may start to get spammed with warnings as the result of your
482 change. Worse, if your code interacts with a strict mock, your tests may start
483 to fail and you'll be forced to fix them. Our general recommendation is to use
484 nice mocks (not yet the default) most of the time, use naggy mocks (the current
485 default) when developing or debugging tests, and use strict mocks only as the
488 ### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces}
490 Sometimes a method has a long list of arguments that is mostly uninteresting.
497 virtual void send(LogSeverity severity, const char* full_filename,
498 const char* base_filename, int line,
499 const struct tm* tm_time,
500 const char* message, size_t message_len) = 0;
504 This method's argument list is lengthy and hard to work with (the `message`
505 argument is not even 0-terminated). If we mock it as is, using the mock will be
506 awkward. If, however, we try to simplify this interface, we'll need to fix all
507 clients depending on it, which is often infeasible.
509 The trick is to redispatch the method in the mock class:
512 class ScopedMockLog : public LogSink {
515 void send(LogSeverity severity, const char* full_filename,
516 const char* base_filename, int line, const tm* tm_time,
517 const char* message, size_t message_len) override {
518 // We are only interested in the log severity, full file name, and
520 Log(severity, full_filename, std::string(message, message_len));
523 // Implements the mock method:
525 // void Log(LogSeverity severity,
526 // const string& file_path,
527 // const string& message);
528 MOCK_METHOD(void, Log,
529 (LogSeverity severity, const string& file_path,
530 const string& message));
534 By defining a new mock method with a trimmed argument list, we make the mock
535 class more user-friendly.
537 This technique may also be applied to make overloaded methods more amenable to
538 mocking. For example, when overloads have been used to implement default
542 class MockTurtleFactory : public TurtleFactory {
544 Turtle* MakeTurtle(int length, int weight) override { ... }
545 Turtle* MakeTurtle(int length, int weight, int speed) override { ... }
547 // the above methods delegate to this one:
548 MOCK_METHOD(Turtle*, DoMakeTurtle, ());
552 This allows tests that don't care which overload was invoked to avoid specifying
556 ON_CALL(factory, DoMakeTurtle)
557 .WillByDefault(Return(MakeMockTurtle()));
560 ### Alternative to Mocking Concrete Classes
562 Often you may find yourself using classes that don't implement interfaces. In
563 order to test your code that uses such a class (let's call it `Concrete`), you
564 may be tempted to make the methods of `Concrete` virtual and then mock it.
568 Making a non-virtual function virtual is a big decision. It creates an extension
569 point where subclasses can tweak your class' behavior. This weakens your control
570 on the class because now it's harder to maintain the class invariants. You
571 should make a function virtual only when there is a valid reason for a subclass
574 Mocking concrete classes directly is problematic as it creates a tight coupling
575 between the class and the tests - any small change in the class may invalidate
576 your tests and make test maintenance a pain.
578 To avoid such problems, many programmers have been practicing "coding to
579 interfaces": instead of talking to the `Concrete` class, your code would define
580 an interface and talk to it. Then you implement that interface as an adaptor on
581 top of `Concrete`. In tests, you can easily mock that interface to observe how
584 This technique incurs some overhead:
586 * You pay the cost of virtual function calls (usually not a problem).
587 * There is more abstraction for the programmers to learn.
589 However, it can also bring significant benefits in addition to better
592 * `Concrete`'s API may not fit your problem domain very well, as you may not
593 be the only client it tries to serve. By designing your own interface, you
594 have a chance to tailor it to your need - you may add higher-level
595 functionalities, rename stuff, etc instead of just trimming the class. This
596 allows you to write your code (user of the interface) in a more natural way,
597 which means it will be more readable, more maintainable, and you'll be more
599 * If `Concrete`'s implementation ever has to change, you don't have to rewrite
600 everywhere it is used. Instead, you can absorb the change in your
601 implementation of the interface, and your other code and tests will be
602 insulated from this change.
604 Some people worry that if everyone is practicing this technique, they will end
605 up writing lots of redundant code. This concern is totally understandable.
606 However, there are two reasons why it may not be the case:
608 * Different projects may need to use `Concrete` in different ways, so the best
609 interfaces for them will be different. Therefore, each of them will have its
610 own domain-specific interface on top of `Concrete`, and they will not be the
612 * If enough projects want to use the same interface, they can always share it,
613 just like they have been sharing `Concrete`. You can check in the interface
614 and the adaptor somewhere near `Concrete` (perhaps in a `contrib`
615 sub-directory) and let many projects use it.
617 You need to weigh the pros and cons carefully for your particular problem, but
618 I'd like to assure you that the Java community has been practicing this for a
619 long time and it's a proven effective technique applicable in a wide variety of
622 ### Delegating Calls to a Fake {#DelegatingToFake}
624 Some times you have a non-trivial fake implementation of an interface. For
631 virtual char DoThis(int n) = 0;
632 virtual void DoThat(const char* s, int* p) = 0;
635 class FakeFoo : public Foo {
637 char DoThis(int n) override {
638 return (n > 0) ? '+' :
642 void DoThat(const char* s, int* p) override {
648 Now you want to mock this interface such that you can set expectations on it.
649 However, you also want to use `FakeFoo` for the default behavior, as duplicating
650 it in the mock object is, well, a lot of work.
652 When you define the mock class using gMock, you can have it delegate its default
653 action to a fake class you already have, using this pattern:
656 class MockFoo : public Foo {
658 // Normal mock method definitions using gMock.
659 MOCK_METHOD(char, DoThis, (int n), (override));
660 MOCK_METHOD(void, DoThat, (const char* s, int* p), (override));
662 // Delegates the default actions of the methods to a FakeFoo object.
663 // This must be called *before* the custom ON_CALL() statements.
664 void DelegateToFake() {
665 ON_CALL(*this, DoThis).WillByDefault([this](int n) {
666 return fake_.DoThis(n);
668 ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) {
674 FakeFoo fake_; // Keeps an instance of the fake in the mock.
678 With that, you can use `MockFoo` in your tests as usual. Just remember that if
679 you don't explicitly set an action in an `ON_CALL()` or `EXPECT_CALL()`, the
680 fake will be called upon to do it.:
688 foo.DelegateToFake(); // Enables the fake for delegation.
690 // Put your ON_CALL(foo, ...)s here, if any.
692 // No action specified, meaning to use the default action.
693 EXPECT_CALL(foo, DoThis(5));
694 EXPECT_CALL(foo, DoThat(_, _));
697 EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked.
698 foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked.
705 * If you want, you can still override the default action by providing your own
706 `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`.
707 * In `DelegateToFake()`, you only need to delegate the methods whose fake
708 implementation you intend to use.
710 * The general technique discussed here works for overloaded methods, but
711 you'll need to tell the compiler which version you mean. To disambiguate a
712 mock function (the one you specify inside the parentheses of `ON_CALL()`),
713 use [this technique](#SelectOverload); to disambiguate a fake function (the
714 one you place inside `Invoke()`), use a `static_cast` to specify the
715 function's type. For instance, if class `Foo` has methods `char DoThis(int
716 n)` and `bool DoThis(double x) const`, and you want to invoke the latter,
717 you need to write `Invoke(&fake_, static_cast<bool (FakeFoo::*)(double)
718 const>(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)`
719 (The strange-looking thing inside the angled brackets of `static_cast` is
720 the type of a function pointer to the second `DoThis()` method.).
722 * Having to mix a mock and a fake is often a sign of something gone wrong.
723 Perhaps you haven't got used to the interaction-based way of testing yet. Or
724 perhaps your interface is taking on too many roles and should be split up.
725 Therefore, **don't abuse this**. We would only recommend to do it as an
726 intermediate step when you are refactoring your code.
728 Regarding the tip on mixing a mock and a fake, here's an example on why it may
729 be a bad sign: Suppose you have a class `System` for low-level system
730 operations. In particular, it does file and I/O operations. And suppose you want
731 to test how your code uses `System` to do I/O, and you just want the file
732 operations to work normally. If you mock out the entire `System` class, you'll
733 have to provide a fake implementation for the file operation part, which
734 suggests that `System` is taking on too many roles.
736 Instead, you can define a `FileOps` interface and an `IOOps` interface and split
737 `System`'s functionalities into the two. Then you can mock `IOOps` without
740 ### Delegating Calls to a Real Object
742 When using testing doubles (mocks, fakes, stubs, and etc), sometimes their
743 behaviors will differ from those of the real objects. This difference could be
744 either intentional (as in simulating an error such that you can test the error
745 handling code) or unintentional. If your mocks have different behaviors than the
746 real objects by mistake, you could end up with code that passes the tests but
749 You can use the *delegating-to-real* technique to ensure that your mock has the
750 same behavior as the real object while retaining the ability to validate calls.
751 This technique is very similar to the [delegating-to-fake](#DelegatingToFake)
752 technique, the difference being that we use a real object instead of a fake.
756 using ::testing::AtLeast;
758 class MockFoo : public Foo {
761 // By default, all calls are delegated to the real object.
762 ON_CALL(*this, DoThis).WillByDefault([this](int n) {
763 return real_.DoThis(n);
765 ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) {
770 MOCK_METHOD(char, DoThis, ...);
771 MOCK_METHOD(void, DoThat, ...);
779 EXPECT_CALL(mock, DoThis())
781 EXPECT_CALL(mock, DoThat("Hi"))
783 ... use mock in test ...
786 With this, gMock will verify that your code made the right calls (with the right
787 arguments, in the right order, called the right number of times, etc), and a
788 real object will answer the calls (so the behavior will be the same as in
789 production). This gives you the best of both worlds.
791 ### Delegating Calls to a Parent Class
793 Ideally, you should code to interfaces, whose methods are all pure virtual. In
794 reality, sometimes you do need to mock a virtual method that is not pure (i.e,
795 it already has an implementation). For example:
802 virtual void Pure(int n) = 0;
803 virtual int Concrete(const char* str) { ... }
806 class MockFoo : public Foo {
808 // Mocking a pure method.
809 MOCK_METHOD(void, Pure, (int n), (override));
810 // Mocking a concrete method. Foo::Concrete() is shadowed.
811 MOCK_METHOD(int, Concrete, (const char* str), (override));
815 Sometimes you may want to call `Foo::Concrete()` instead of
816 `MockFoo::Concrete()`. Perhaps you want to do it as part of a stub action, or
817 perhaps your test doesn't need to mock `Concrete()` at all (but it would be
818 oh-so painful to have to define a new mock class whenever you don't need to mock
821 You can call `Foo::Concrete()` inside an action by:
825 EXPECT_CALL(foo, Concrete).WillOnce([&foo](const char* str) {
826 return foo.Foo::Concrete(str);
830 or tell the mock object that you don't want to mock `Concrete()`:
834 ON_CALL(foo, Concrete).WillByDefault([&foo](const char* str) {
835 return foo.Foo::Concrete(str);
839 (Why don't we just write `{ return foo.Concrete(str); }`? If you do that,
840 `MockFoo::Concrete()` will be called (and cause an infinite recursion) since
841 `Foo::Concrete()` is virtual. That's just how C++ works.)
845 ### Matching Argument Values Exactly
847 You can specify exactly which arguments a mock method is expecting:
850 using ::testing::Return;
852 EXPECT_CALL(foo, DoThis(5))
853 .WillOnce(Return('a'));
854 EXPECT_CALL(foo, DoThat("Hello", bar));
857 ### Using Simple Matchers
859 You can use matchers to match arguments that have a certain property:
862 using ::testing::NotNull;
863 using ::testing::Return;
865 EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5.
866 .WillOnce(Return('a'));
867 EXPECT_CALL(foo, DoThat("Hello", NotNull()));
868 // The second argument must not be NULL.
871 A frequently used matcher is `_`, which matches anything:
874 EXPECT_CALL(foo, DoThat(_, NotNull()));
877 ### Combining Matchers {#CombiningMatchers}
879 You can build complex matchers from existing ones using `AllOf()`,
880 `AllOfArray()`, `AnyOf()`, `AnyOfArray()` and `Not()`:
883 using ::testing::AllOf;
885 using ::testing::HasSubstr;
887 using ::testing::Not;
889 // The argument must be > 5 and != 10.
890 EXPECT_CALL(foo, DoThis(AllOf(Gt(5),
893 // The first argument must not contain sub-string "blah".
894 EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")),
898 Matchers are function objects, and parametrized matchers can be composed just
899 like any other function. However because their types can be long and rarely
900 provide meaningful information, it can be easier to express them with C++14
901 generic lambdas to avoid specifying types. For example,
904 using ::testing::Contains;
905 using ::testing::Property;
907 inline constexpr auto HasFoo = [](const auto& f) {
908 return Property(&MyClass::foo, Contains(f));
911 EXPECT_THAT(x, HasFoo("blah"));
914 ### Casting Matchers {#SafeMatcherCast}
916 gMock matchers are statically typed, meaning that the compiler can catch your
917 mistake if you use a matcher of the wrong type (for example, if you use `Eq(5)`
918 to match a `string` argument). Good for you!
920 Sometimes, however, you know what you're doing and want the compiler to give you
921 some slack. One example is that you have a matcher for `long` and the argument
922 you want to match is `int`. While the two types aren't exactly the same, there
923 is nothing really wrong with using a `Matcher<long>` to match an `int` - after
924 all, we can first convert the `int` argument to a `long` losslessly before
925 giving it to the matcher.
927 To support this need, gMock gives you the `SafeMatcherCast<T>(m)` function. It
928 casts a matcher `m` to type `Matcher<T>`. To ensure safety, gMock checks that
929 (let `U` be the type `m` accepts :
931 1. Type `T` can be *implicitly* cast to type `U`;
932 2. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and
933 floating-point numbers), the conversion from `T` to `U` is not lossy (in
934 other words, any value representable by `T` can also be represented by `U`);
936 3. When `U` is a reference, `T` must also be a reference (as the underlying
937 matcher may be interested in the address of the `U` value).
939 The code won't compile if any of these conditions isn't met.
944 using ::testing::SafeMatcherCast;
946 // A base class and a child class.
948 class Derived : public Base { ... };
950 class MockFoo : public Foo {
952 MOCK_METHOD(void, DoThis, (Derived* derived), (override));
957 // m is a Matcher<Base*> we got from somewhere.
958 EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m)));
961 If you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar function
962 `MatcherCast<T>(m)`. The difference is that `MatcherCast` works as long as you
963 can `static_cast` type `T` to type `U`.
965 `MatcherCast` essentially lets you bypass C++'s type system (`static_cast` isn't
966 always safe as it could throw away information, for example), so be careful not
969 ### Selecting Between Overloaded Functions {#SelectOverload}
971 If you expect an overloaded function to be called, the compiler may need some
972 help on which overloaded version it is.
974 To disambiguate functions overloaded on the const-ness of this object, use the
975 `Const()` argument wrapper.
978 using ::testing::ReturnRef;
980 class MockFoo : public Foo {
982 MOCK_METHOD(Bar&, GetBar, (), (override));
983 MOCK_METHOD(const Bar&, GetBar, (), (const, override));
989 EXPECT_CALL(foo, GetBar()) // The non-const GetBar().
990 .WillOnce(ReturnRef(bar1));
991 EXPECT_CALL(Const(foo), GetBar()) // The const GetBar().
992 .WillOnce(ReturnRef(bar2));
995 (`Const()` is defined by gMock and returns a `const` reference to its argument.)
997 To disambiguate overloaded functions with the same number of arguments but
998 different argument types, you may need to specify the exact type of a matcher,
999 either by wrapping your matcher in `Matcher<type>()`, or using a matcher whose
1000 type is fixed (`TypedEq<type>`, `An<type>()`, etc):
1003 using ::testing::An;
1004 using ::testing::Matcher;
1005 using ::testing::TypedEq;
1007 class MockPrinter : public Printer {
1009 MOCK_METHOD(void, Print, (int n), (override));
1010 MOCK_METHOD(void, Print, (char c), (override));
1013 TEST(PrinterTest, Print) {
1014 MockPrinter printer;
1016 EXPECT_CALL(printer, Print(An<int>())); // void Print(int);
1017 EXPECT_CALL(printer, Print(Matcher<int>(Lt(5)))); // void Print(int);
1018 EXPECT_CALL(printer, Print(TypedEq<char>('a'))); // void Print(char);
1026 ### Performing Different Actions Based on the Arguments
1028 When a mock method is called, the *last* matching expectation that's still
1029 active will be selected (think "newer overrides older"). So, you can make a
1030 method do different things depending on its argument values like this:
1034 using ::testing::Lt;
1035 using ::testing::Return;
1037 // The default case.
1038 EXPECT_CALL(foo, DoThis(_))
1039 .WillRepeatedly(Return('b'));
1040 // The more specific case.
1041 EXPECT_CALL(foo, DoThis(Lt(5)))
1042 .WillRepeatedly(Return('a'));
1045 Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will be
1046 returned; otherwise `'b'` will be returned.
1048 ### Matching Multiple Arguments as a Whole
1050 Sometimes it's not enough to match the arguments individually. For example, we
1051 may want to say that the first argument must be less than the second argument.
1052 The `With()` clause allows us to match all arguments of a mock function as a
1057 using ::testing::Ne;
1058 using ::testing::Lt;
1060 EXPECT_CALL(foo, InRange(Ne(0), _))
1064 says that the first argument of `InRange()` must not be 0, and must be less than
1065 the second argument.
1067 The expression inside `With()` must be a matcher of type `Matcher<std::tuple<A1,
1068 ..., An>>`, where `A1`, ..., `An` are the types of the function arguments.
1070 You can also write `AllArgs(m)` instead of `m` inside `.With()`. The two forms
1071 are equivalent, but `.With(AllArgs(Lt()))` is more readable than `.With(Lt())`.
1073 You can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments (as a
1074 tuple) against `m`. For example,
1078 using ::testing::AllOf;
1079 using ::testing::Args;
1080 using ::testing::Lt;
1082 EXPECT_CALL(foo, Blah)
1083 .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt())));
1086 says that `Blah` will be called with arguments `x`, `y`, and `z` where `x < y <
1087 z`. Note that in this example, it wasn't necessary specify the positional
1090 As a convenience and example, gMock provides some matchers for 2-tuples,
1091 including the `Lt()` matcher above. See
1092 [Multi-argument Matchers](reference/matchers.md#MultiArgMatchers) for the
1095 Note that if you want to pass the arguments to a predicate of your own (e.g.
1096 `.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be written to
1097 take a `std::tuple` as its argument; gMock will pass the `n` selected arguments
1098 as *one* single tuple to the predicate.
1100 ### Using Matchers as Predicates
1102 Have you noticed that a matcher is just a fancy predicate that also knows how to
1103 describe itself? Many existing algorithms take predicates as arguments (e.g.
1104 those defined in STL's `<algorithm>` header), and it would be a shame if gMock
1105 matchers were not allowed to participate.
1107 Luckily, you can use a matcher where a unary predicate functor is expected by
1108 wrapping it inside the `Matches()` function. For example,
1111 #include <algorithm>
1114 using ::testing::Matches;
1115 using ::testing::Ge;
1119 // How many elements in v are >= 10?
1120 const int count = count_if(v.begin(), v.end(), Matches(Ge(10)));
1123 Since you can build complex matchers from simpler ones easily using gMock, this
1124 gives you a way to conveniently construct composite predicates (doing the same
1125 using STL's `<functional>` header is just painful). For example, here's a
1126 predicate that's satisfied by any number that is >= 0, <= 100, and != 50:
1129 using testing::AllOf;
1132 using testing::Matches;
1135 Matches(AllOf(Ge(0), Le(100), Ne(50)))
1138 ### Using Matchers in googletest Assertions
1140 See [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) in the Assertions
1143 ### Using Predicates as Matchers
1145 gMock provides a set of built-in matchers for matching arguments with expected
1146 values—see the [Matchers Reference](reference/matchers.md) for more information.
1147 In case you find the built-in set lacking, you can use an arbitrary unary
1148 predicate function or functor as a matcher - as long as the predicate accepts a
1149 value of the type you want. You do this by wrapping the predicate inside the
1150 `Truly()` function, for example:
1153 using ::testing::Truly;
1155 int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; }
1157 // Bar() must be called with an even number.
1158 EXPECT_CALL(foo, Bar(Truly(IsEven)));
1161 Note that the predicate function / functor doesn't have to return `bool`. It
1162 works as long as the return value can be used as the condition in in statement
1163 `if (condition) ...`.
1165 ### Matching Arguments that Are Not Copyable
1167 When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of
1168 `bar`. When `Foo()` is called later, gMock compares the argument to `Foo()` with
1169 the saved copy of `bar`. This way, you don't need to worry about `bar` being
1170 modified or destroyed after the `EXPECT_CALL()` is executed. The same is true
1171 when you use matchers like `Eq(bar)`, `Le(bar)`, and so on.
1173 But what if `bar` cannot be copied (i.e. has no copy constructor)? You could
1174 define your own matcher function or callback and use it with `Truly()`, as the
1175 previous couple of recipes have shown. Or, you may be able to get away from it
1176 if you can guarantee that `bar` won't be changed after the `EXPECT_CALL()` is
1177 executed. Just tell gMock that it should save a reference to `bar`, instead of a
1178 copy of it. Here's how:
1181 using ::testing::Eq;
1182 using ::testing::Lt;
1184 // Expects that Foo()'s argument == bar.
1185 EXPECT_CALL(mock_obj, Foo(Eq(std::ref(bar))));
1187 // Expects that Foo()'s argument < bar.
1188 EXPECT_CALL(mock_obj, Foo(Lt(std::ref(bar))));
1191 Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the
1192 result is undefined.
1194 ### Validating a Member of an Object
1196 Often a mock function takes a reference to object as an argument. When matching
1197 the argument, you may not want to compare the entire object against a fixed
1198 object, as that may be over-specification. Instead, you may need to validate a
1199 certain member variable or the result of a certain getter method of the object.
1200 You can do this with `Field()` and `Property()`. More specifically,
1206 is a matcher that matches a `Foo` object whose `bar` member variable satisfies
1210 Property(&Foo::baz, m)
1213 is a matcher that matches a `Foo` object whose `baz()` method returns a value
1214 that satisfies matcher `m`.
1218 | Expression | Description |
1219 | :--------------------------- | :--------------------------------------- |
1220 | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. |
1221 | `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. |
1223 Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument
1224 and be declared as `const`. Don't use `Property()` against member functions that
1225 you do not own, because taking addresses of functions is fragile and generally
1226 not part of the contract of the function.
1228 `Field()` and `Property()` can also match plain pointers to objects. For
1232 using ::testing::Field;
1233 using ::testing::Ge;
1235 Field(&Foo::number, Ge(3))
1238 matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, the match
1239 will always fail regardless of the inner matcher.
1241 What if you want to validate more than one members at the same time? Remember
1242 that there are [`AllOf()` and `AllOfArray()`](#CombiningMatchers).
1244 Finally `Field()` and `Property()` provide overloads that take the field or
1245 property names as the first argument to include it in the error message. This
1246 can be useful when creating combined matchers.
1249 using ::testing::AllOf;
1250 using ::testing::Field;
1251 using ::testing::Matcher;
1252 using ::testing::SafeMatcherCast;
1254 Matcher<Foo> IsFoo(const Foo& foo) {
1255 return AllOf(Field("some_field", &Foo::some_field, foo.some_field),
1256 Field("other_field", &Foo::other_field, foo.other_field),
1257 Field("last_field", &Foo::last_field, foo.last_field));
1261 ### Validating the Value Pointed to by a Pointer Argument
1263 C++ functions often take pointers as arguments. You can use matchers like
1264 `IsNull()`, `NotNull()`, and other comparison matchers to match a pointer, but
1265 what if you want to make sure the value *pointed to* by the pointer, instead of
1266 the pointer itself, has a certain property? Well, you can use the `Pointee(m)`
1269 `Pointee(m)` matches a pointer if and only if `m` matches the value the pointer
1270 points to. For example:
1273 using ::testing::Ge;
1274 using ::testing::Pointee;
1276 EXPECT_CALL(foo, Bar(Pointee(Ge(3))));
1279 expects `foo.Bar()` to be called with a pointer that points to a value greater
1282 One nice thing about `Pointee()` is that it treats a `NULL` pointer as a match
1283 failure, so you can write `Pointee(m)` instead of
1286 using ::testing::AllOf;
1287 using ::testing::NotNull;
1288 using ::testing::Pointee;
1290 AllOf(NotNull(), Pointee(m))
1293 without worrying that a `NULL` pointer will crash your test.
1295 Also, did we tell you that `Pointee()` works with both raw pointers **and**
1296 smart pointers (`std::unique_ptr`, `std::shared_ptr`, etc)?
1298 What if you have a pointer to pointer? You guessed it - you can use nested
1299 `Pointee()` to probe deeper inside the value. For example,
1300 `Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer that points
1301 to a number less than 3 (what a mouthful...).
1303 ### Testing a Certain Property of an Object
1305 Sometimes you want to specify that an object argument has a certain property,
1306 but there is no existing matcher that does this. If you want good error
1307 messages, you should [define a matcher](#NewMatchers). If you want to do it
1308 quick and dirty, you could get away with writing an ordinary function.
1310 Let's say you have a mock function that takes an object of type `Foo`, which has
1311 an `int bar()` method and an `int baz()` method, and you want to constrain that
1312 the argument's `bar()` value plus its `baz()` value is a given number. Here's
1313 how you can define a matcher to do it:
1316 using ::testing::Matcher;
1318 class BarPlusBazEqMatcher {
1320 explicit BarPlusBazEqMatcher(int expected_sum)
1321 : expected_sum_(expected_sum) {}
1323 bool MatchAndExplain(const Foo& foo,
1324 std::ostream* /* listener */) const {
1325 return (foo.bar() + foo.baz()) == expected_sum_;
1328 void DescribeTo(std::ostream& os) const {
1329 os << "bar() + baz() equals " << expected_sum_;
1332 void DescribeNegationTo(std::ostream& os) const {
1333 os << "bar() + baz() does not equal " << expected_sum_;
1336 const int expected_sum_;
1339 Matcher<const Foo&> BarPlusBazEq(int expected_sum) {
1340 return BarPlusBazEqMatcher(expected_sum);
1344 EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...;
1347 ### Matching Containers
1349 Sometimes an STL container (e.g. list, vector, map, ...) is passed to a mock
1350 function and you may want to validate it. Since most STL containers support the
1351 `==` operator, you can write `Eq(expected_container)` or simply
1352 `expected_container` to match a container exactly.
1354 Sometimes, though, you may want to be more flexible (for example, the first
1355 element must be an exact match, but the second element can be any positive
1356 number, and so on). Also, containers used in tests often have a small number of
1357 elements, and having to define the expected container out-of-line is a bit of a
1360 You can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in such
1365 using ::testing::ElementsAre;
1366 using ::testing::Gt;
1368 MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override));
1370 EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5)));
1373 The above matcher says that the container must have 4 elements, which must be 1,
1374 greater than 0, anything, and 5 respectively.
1376 If you instead write:
1380 using ::testing::Gt;
1381 using ::testing::UnorderedElementsAre;
1383 MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override));
1385 EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5)));
1388 It means that the container must have 4 elements, which (under some permutation)
1389 must be 1, greater than 0, anything, and 5 respectively.
1391 As an alternative you can place the arguments in a C-style array and use
1392 `ElementsAreArray()` or `UnorderedElementsAreArray()` instead:
1395 using ::testing::ElementsAreArray;
1397 // ElementsAreArray accepts an array of element values.
1398 const int expected_vector1[] = {1, 5, 2, 4, ...};
1399 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1)));
1401 // Or, an array of element matchers.
1402 Matcher<int> expected_vector2[] = {1, Gt(2), _, 3, ...};
1403 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2)));
1406 In case the array needs to be dynamically created (and therefore the array size
1407 cannot be inferred by the compiler), you can give `ElementsAreArray()` an
1408 additional argument to specify the array size:
1411 using ::testing::ElementsAreArray;
1413 int* const expected_vector3 = new int[count];
1414 ... fill expected_vector3 with values ...
1415 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count)));
1418 Use `Pair` when comparing maps or other associative containers.
1423 using testing::ElementsAre;
1424 using testing::Pair;
1426 std::map<string, int> m = {{"a", 1}, {"b", 2}, {"c", 3}};
1427 EXPECT_THAT(m, ElementsAre(Pair("a", 1), Pair("b", 2), Pair("c", 3)));
1434 * `ElementsAre*()` can be used to match *any* container that implements the
1435 STL iterator pattern (i.e. it has a `const_iterator` type and supports
1436 `begin()/end()`), not just the ones defined in STL. It will even work with
1437 container types yet to be written - as long as they follows the above
1439 * You can use nested `ElementsAre*()` to match nested (multi-dimensional)
1441 * If the container is passed by pointer instead of by reference, just write
1442 `Pointee(ElementsAre*(...))`.
1443 * The order of elements *matters* for `ElementsAre*()`. If you are using it
1444 with containers whose element order are undefined (e.g. `hash_map`) you
1445 should use `WhenSorted` around `ElementsAre`.
1447 ### Sharing Matchers
1449 Under the hood, a gMock matcher object consists of a pointer to a ref-counted
1450 implementation object. Copying matchers is allowed and very efficient, as only
1451 the pointer is copied. When the last matcher that references the implementation
1452 object dies, the implementation object will be deleted.
1454 Therefore, if you have some complex matcher that you want to use again and
1455 again, there is no need to build it everytime. Just assign it to a matcher
1456 variable and use that variable repeatedly! For example,
1459 using ::testing::AllOf;
1460 using ::testing::Gt;
1461 using ::testing::Le;
1462 using ::testing::Matcher;
1464 Matcher<int> in_range = AllOf(Gt(5), Le(10));
1465 ... use in_range as a matcher in multiple EXPECT_CALLs ...
1468 ### Matchers must have no side-effects {#PureMatchers}
1470 {: .callout .warning}
1471 WARNING: gMock does not guarantee when or how many times a matcher will be
1472 invoked. Therefore, all matchers must be *purely functional*: they cannot have
1473 any side effects, and the match result must not depend on anything other than
1474 the matcher's parameters and the value being matched.
1476 This requirement must be satisfied no matter how a matcher is defined (e.g., if
1477 it is one of the standard matchers, or a custom matcher). In particular, a
1478 matcher can never call a mock function, as that will affect the state of the
1479 mock object and gMock.
1481 ## Setting Expectations
1483 ### Knowing When to Expect {#UseOnCall}
1485 **`ON_CALL`** is likely the *single most under-utilized construct* in gMock.
1487 There are basically two constructs for defining the behavior of a mock object:
1488 `ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when
1489 a mock method is called, but <em>doesn't imply any expectation on the method
1490 being called</em>. `EXPECT_CALL` not only defines the behavior, but also sets an
1491 expectation that <em>the method will be called with the given arguments, for the
1492 given number of times</em> (and *in the given order* when you specify the order
1495 Since `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every
1496 `EXPECT_CALL` adds a constraint on the behavior of the code under test. Having
1497 more constraints than necessary is *baaad* - even worse than not having enough
1500 This may be counter-intuitive. How could tests that verify more be worse than
1501 tests that verify less? Isn't verification the whole point of tests?
1503 The answer lies in *what* a test should verify. **A good test verifies the
1504 contract of the code.** If a test over-specifies, it doesn't leave enough
1505 freedom to the implementation. As a result, changing the implementation without
1506 breaking the contract (e.g. refactoring and optimization), which should be
1507 perfectly fine to do, can break such tests. Then you have to spend time fixing
1508 them, only to see them broken again the next time the implementation is changed.
1510 Keep in mind that one doesn't have to verify more than one property in one test.
1511 In fact, **it's a good style to verify only one thing in one test.** If you do
1512 that, a bug will likely break only one or two tests instead of dozens (which
1513 case would you rather debug?). If you are also in the habit of giving tests
1514 descriptive names that tell what they verify, you can often easily guess what's
1515 wrong just from the test log itself.
1517 So use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend
1518 to verify that the call is made. For example, you may have a bunch of `ON_CALL`s
1519 in your test fixture to set the common mock behavior shared by all tests in the
1520 same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s
1521 to verify different aspects of the code's behavior. Compared with the style
1522 where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more
1523 resilient to implementational changes (and thus less likely to require
1524 maintenance) and makes the intent of the tests more obvious (so they are easier
1525 to maintain when you do need to maintain them).
1527 If you are bothered by the "Uninteresting mock function call" message printed
1528 when a mock method without an `EXPECT_CALL` is called, you may use a `NiceMock`
1529 instead to suppress all such messages for the mock object, or suppress the
1530 message for specific methods by adding `EXPECT_CALL(...).Times(AnyNumber())`. DO
1531 NOT suppress it by blindly adding an `EXPECT_CALL(...)`, or you'll have a test
1532 that's a pain to maintain.
1534 ### Ignoring Uninteresting Calls
1536 If you are not interested in how a mock method is called, just don't say
1537 anything about it. In this case, if the method is ever called, gMock will
1538 perform its default action to allow the test program to continue. If you are not
1539 happy with the default action taken by gMock, you can override it using
1540 `DefaultValue<T>::Set()` (described [here](#DefaultValue)) or `ON_CALL()`.
1542 Please note that once you expressed interest in a particular mock method (via
1543 `EXPECT_CALL()`), all invocations to it must match some expectation. If this
1544 function is called but the arguments don't match any `EXPECT_CALL()` statement,
1545 it will be an error.
1547 ### Disallowing Unexpected Calls
1549 If a mock method shouldn't be called at all, explicitly say so:
1554 EXPECT_CALL(foo, Bar(_))
1558 If some calls to the method are allowed, but the rest are not, just list all the
1562 using ::testing::AnyNumber;
1563 using ::testing::Gt;
1565 EXPECT_CALL(foo, Bar(5));
1566 EXPECT_CALL(foo, Bar(Gt(10)))
1567 .Times(AnyNumber());
1570 A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` statements
1573 ### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected}
1575 *Uninteresting* calls and *unexpected* calls are different concepts in gMock.
1578 A call `x.Y(...)` is **uninteresting** if there's *not even a single*
1579 `EXPECT_CALL(x, Y(...))` set. In other words, the test isn't interested in the
1580 `x.Y()` method at all, as evident in that the test doesn't care to say anything
1583 A call `x.Y(...)` is **unexpected** if there are *some* `EXPECT_CALL(x,
1584 Y(...))`s set, but none of them matches the call. Put another way, the test is
1585 interested in the `x.Y()` method (therefore it explicitly sets some
1586 `EXPECT_CALL` to verify how it's called); however, the verification fails as the
1587 test doesn't expect this particular call to happen.
1589 **An unexpected call is always an error,** as the code under test doesn't behave
1590 the way the test expects it to behave.
1592 **By default, an uninteresting call is not an error,** as it violates no
1593 constraint specified by the test. (gMock's philosophy is that saying nothing
1594 means there is no constraint.) However, it leads to a warning, as it *might*
1595 indicate a problem (e.g. the test author might have forgotten to specify a
1598 In gMock, `NiceMock` and `StrictMock` can be used to make a mock class "nice" or
1599 "strict". How does this affect uninteresting calls and unexpected calls?
1601 A **nice mock** suppresses uninteresting call *warnings*. It is less chatty than
1602 the default mock, but otherwise is the same. If a test fails with a default
1603 mock, it will also fail using a nice mock instead. And vice versa. Don't expect
1604 making a mock nice to change the test's result.
1606 A **strict mock** turns uninteresting call warnings into errors. So making a
1607 mock strict may change the test's result.
1609 Let's look at an example:
1613 NiceMock<MockDomainRegistry> mock_registry;
1614 EXPECT_CALL(mock_registry, GetDomainOwner("google.com"))
1615 .WillRepeatedly(Return("Larry Page"));
1617 // Use mock_registry in code under test.
1618 ... &mock_registry ...
1622 The sole `EXPECT_CALL` here says that all calls to `GetDomainOwner()` must have
1623 `"google.com"` as the argument. If `GetDomainOwner("yahoo.com")` is called, it
1624 will be an unexpected call, and thus an error. *Having a nice mock doesn't
1625 change the severity of an unexpected call.*
1627 So how do we tell gMock that `GetDomainOwner()` can be called with some other
1628 arguments as well? The standard technique is to add a "catch all" `EXPECT_CALL`:
1631 EXPECT_CALL(mock_registry, GetDomainOwner(_))
1632 .Times(AnyNumber()); // catches all other calls to this method.
1633 EXPECT_CALL(mock_registry, GetDomainOwner("google.com"))
1634 .WillRepeatedly(Return("Larry Page"));
1637 Remember that `_` is the wildcard matcher that matches anything. With this, if
1638 `GetDomainOwner("google.com")` is called, it will do what the second
1639 `EXPECT_CALL` says; if it is called with a different argument, it will do what
1640 the first `EXPECT_CALL` says.
1642 Note that the order of the two `EXPECT_CALL`s is important, as a newer
1643 `EXPECT_CALL` takes precedence over an older one.
1645 For more on uninteresting calls, nice mocks, and strict mocks, read
1646 ["The Nice, the Strict, and the Naggy"](#NiceStrictNaggy).
1648 ### Ignoring Uninteresting Arguments {#ParameterlessExpectations}
1650 If your test doesn't care about the parameters (it only cares about the number
1651 or order of calls), you can often simply omit the parameter list:
1654 // Expect foo.Bar( ... ) twice with any arguments.
1655 EXPECT_CALL(foo, Bar).Times(2);
1657 // Delegate to the given method whenever the factory is invoked.
1658 ON_CALL(foo_factory, MakeFoo)
1659 .WillByDefault(&BuildFooForTest);
1662 This functionality is only available when a method is not overloaded; to prevent
1663 unexpected behavior it is a compilation error to try to set an expectation on a
1664 method where the specific overload is ambiguous. You can work around this by
1665 supplying a [simpler mock interface](#SimplerInterfaces) than the mocked class
1668 This pattern is also useful when the arguments are interesting, but match logic
1669 is substantially complex. You can leave the argument list unspecified and use
1670 SaveArg actions to [save the values for later verification](#SaveArgVerify). If
1671 you do that, you can easily differentiate calling the method the wrong number of
1672 times from calling it with the wrong arguments.
1674 ### Expecting Ordered Calls {#OrderedCalls}
1676 Although an `EXPECT_CALL()` statement defined later takes precedence when gMock
1677 tries to match a function call with an expectation, by default calls don't have
1678 to happen in the order `EXPECT_CALL()` statements are written. For example, if
1679 the arguments match the matchers in the second `EXPECT_CALL()`, but not those in
1680 the first and third, then the second expectation will be used.
1682 If you would rather have all calls occur in the order of the expectations, put
1683 the `EXPECT_CALL()` statements in a block where you define a variable of type
1688 using ::testing::InSequence;
1693 EXPECT_CALL(foo, DoThis(5));
1694 EXPECT_CALL(bar, DoThat(_))
1696 EXPECT_CALL(foo, DoThis(6));
1700 In this example, we expect a call to `foo.DoThis(5)`, followed by two calls to
1701 `bar.DoThat()` where the argument can be anything, which are in turn followed by
1702 a call to `foo.DoThis(6)`. If a call occurred out-of-order, gMock will report an
1705 ### Expecting Partially Ordered Calls {#PartialOrder}
1707 Sometimes requiring everything to occur in a predetermined order can lead to
1708 brittle tests. For example, we may care about `A` occurring before both `B` and
1709 `C`, but aren't interested in the relative order of `B` and `C`. In this case,
1710 the test should reflect our real intent, instead of being overly constraining.
1712 gMock allows you to impose an arbitrary DAG (directed acyclic graph) on the
1713 calls. One way to express the DAG is to use the
1714 [`After` clause](reference/mocking.md#EXPECT_CALL.After) of `EXPECT_CALL`.
1716 Another way is via the `InSequence()` clause (not the same as the `InSequence`
1717 class), which we borrowed from jMock 2. It's less flexible than `After()`, but
1718 more convenient when you have long chains of sequential calls, as it doesn't
1719 require you to come up with different names for the expectations in the chains.
1720 Here's how it works:
1722 If we view `EXPECT_CALL()` statements as nodes in a graph, and add an edge from
1723 node A to node B wherever A must occur before B, we can get a DAG. We use the
1724 term "sequence" to mean a directed path in this DAG. Now, if we decompose the
1725 DAG into sequences, we just need to know which sequences each `EXPECT_CALL()`
1726 belongs to in order to be able to reconstruct the original DAG.
1728 So, to specify the partial order on the expectations we need to do two things:
1729 first to define some `Sequence` objects, and then for each `EXPECT_CALL()` say
1730 which `Sequence` objects it is part of.
1732 Expectations in the same sequence must occur in the order they are written. For
1736 using ::testing::Sequence;
1740 EXPECT_CALL(foo, A())
1741 .InSequence(s1, s2);
1742 EXPECT_CALL(bar, B())
1744 EXPECT_CALL(bar, C())
1746 EXPECT_CALL(foo, D())
1750 specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> C -> D`):
1760 This means that A must occur before B and C, and C must occur before D. There's
1761 no restriction about the order other than these.
1763 ### Controlling When an Expectation Retires
1765 When a mock method is called, gMock only considers expectations that are still
1766 active. An expectation is active when created, and becomes inactive (aka
1767 *retires*) when a call that has to occur later has occurred. For example, in
1771 using ::testing::Sequence;
1775 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1
1777 .InSequence(s1, s2);
1778 EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2
1780 EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3
1784 as soon as either #2 or #3 is matched, #1 will retire. If a warning `"File too
1785 large."` is logged after this, it will be an error.
1787 Note that an expectation doesn't retire automatically when it's saturated. For
1793 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1794 EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2
1797 says that there will be exactly one warning with the message `"File too
1798 large."`. If the second warning contains this message too, #2 will match again
1799 and result in an upper-bound-violated error.
1801 If this is not what you want, you can ask an expectation to retire as soon as it
1807 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1808 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2
1809 .RetiresOnSaturation();
1812 Here #2 can be used only once, so if you have two warnings with the message
1813 `"File too large."`, the first will match #2 and the second will match #1 -
1814 there will be no error.
1818 ### Returning References from Mock Methods
1820 If a mock function's return type is a reference, you need to use `ReturnRef()`
1821 instead of `Return()` to return a result:
1824 using ::testing::ReturnRef;
1826 class MockFoo : public Foo {
1828 MOCK_METHOD(Bar&, GetBar, (), (override));
1833 EXPECT_CALL(foo, GetBar())
1834 .WillOnce(ReturnRef(bar));
1838 ### Returning Live Values from Mock Methods
1840 The `Return(x)` action saves a copy of `x` when the action is created, and
1841 always returns the same value whenever it's executed. Sometimes you may want to
1842 instead return the *live* value of `x` (i.e. its value at the time when the
1843 action is *executed*.). Use either `ReturnRef()` or `ReturnPointee()` for this
1846 If the mock function's return type is a reference, you can do it using
1847 `ReturnRef(x)`, as shown in the previous recipe ("Returning References from Mock
1848 Methods"). However, gMock doesn't let you use `ReturnRef()` in a mock function
1849 whose return type is not a reference, as doing that usually indicates a user
1850 error. So, what shall you do?
1852 Though you may be tempted, DO NOT use `std::ref()`:
1855 using testing::Return;
1857 class MockFoo : public Foo {
1859 MOCK_METHOD(int, GetValue, (), (override));
1864 EXPECT_CALL(foo, GetValue())
1865 .WillRepeatedly(Return(std::ref(x))); // Wrong!
1867 EXPECT_EQ(42, foo.GetValue());
1870 Unfortunately, it doesn't work here. The above code will fail with error:
1873 Value of: foo.GetValue()
1878 The reason is that `Return(*value*)` converts `value` to the actual return type
1879 of the mock function at the time when the action is *created*, not when it is
1880 *executed*. (This behavior was chosen for the action to be safe when `value` is
1881 a proxy object that references some temporary objects.) As a result,
1882 `std::ref(x)` is converted to an `int` value (instead of a `const int&`) when
1883 the expectation is set, and `Return(std::ref(x))` will always return 0.
1885 `ReturnPointee(pointer)` was provided to solve this problem specifically. It
1886 returns the value pointed to by `pointer` at the time the action is *executed*:
1889 using testing::ReturnPointee;
1893 EXPECT_CALL(foo, GetValue())
1894 .WillRepeatedly(ReturnPointee(&x)); // Note the & here.
1896 EXPECT_EQ(42, foo.GetValue()); // This will succeed now.
1899 ### Combining Actions
1901 Want to do more than one thing when a function is called? That's fine. `DoAll()`
1902 allow you to do sequence of actions every time. Only the return value of the
1903 last action in the sequence will be used.
1907 using ::testing::DoAll;
1909 class MockFoo : public Foo {
1911 MOCK_METHOD(bool, Bar, (int n), (override));
1914 EXPECT_CALL(foo, Bar(_))
1915 .WillOnce(DoAll(action_1,
1921 ### Verifying Complex Arguments {#SaveArgVerify}
1923 If you want to verify that a method is called with a particular argument but the
1924 match criteria is complex, it can be difficult to distinguish between
1925 cardinality failures (calling the method the wrong number of times) and argument
1926 match failures. Similarly, if you are matching multiple parameters, it may not
1927 be easy to distinguishing which argument failed to match. For example:
1930 // Not ideal: this could fail because of a problem with arg1 or arg2, or maybe
1931 // just the method wasn't called.
1932 EXPECT_CALL(foo, SendValues(_, ElementsAre(1, 4, 4, 7), EqualsProto( ... )));
1935 You can instead save the arguments and test them individually:
1938 EXPECT_CALL(foo, SendValues)
1939 .WillOnce(DoAll(SaveArg<1>(&actual_array), SaveArg<2>(&actual_proto)));
1941 EXPECT_THAT(actual_array, ElementsAre(1, 4, 4, 7));
1942 EXPECT_THAT(actual_proto, EqualsProto( ... ));
1945 ### Mocking Side Effects {#MockingSideEffects}
1947 Sometimes a method exhibits its effect not via returning a value but via side
1948 effects. For example, it may change some global state or modify an output
1949 argument. To mock side effects, in general you can define your own action by
1950 implementing `::testing::ActionInterface`.
1952 If all you need to do is to change an output argument, the built-in
1953 `SetArgPointee()` action is convenient:
1957 using ::testing::SetArgPointee;
1959 class MockMutator : public Mutator {
1961 MOCK_METHOD(void, Mutate, (bool mutate, int* value), (override));
1965 MockMutator mutator;
1966 EXPECT_CALL(mutator, Mutate(true, _))
1967 .WillOnce(SetArgPointee<1>(5));
1970 In this example, when `mutator.Mutate()` is called, we will assign 5 to the
1971 `int` variable pointed to by argument #1 (0-based).
1973 `SetArgPointee()` conveniently makes an internal copy of the value you pass to
1974 it, removing the need to keep the value in scope and alive. The implication
1975 however is that the value must have a copy constructor and assignment operator.
1977 If the mock method also needs to return a value as well, you can chain
1978 `SetArgPointee()` with `Return()` using `DoAll()`, remembering to put the
1979 `Return()` statement last:
1983 using ::testing::Return;
1984 using ::testing::SetArgPointee;
1986 class MockMutator : public Mutator {
1989 MOCK_METHOD(bool, MutateInt, (int* value), (override));
1992 MockMutator mutator;
1993 EXPECT_CALL(mutator, MutateInt(_))
1994 .WillOnce(DoAll(SetArgPointee<0>(5),
1998 Note, however, that if you use the `ReturnOKWith()` method, it will override the
1999 values provided by `SetArgPointee()` in the response parameters of your function
2002 If the output argument is an array, use the `SetArrayArgument<N>(first, last)`
2003 action instead. It copies the elements in source range `[first, last)` to the
2004 array pointed to by the `N`-th (0-based) argument:
2007 using ::testing::NotNull;
2008 using ::testing::SetArrayArgument;
2010 class MockArrayMutator : public ArrayMutator {
2012 MOCK_METHOD(void, Mutate, (int* values, int num_values), (override));
2016 MockArrayMutator mutator;
2017 int values[5] = {1, 2, 3, 4, 5};
2018 EXPECT_CALL(mutator, Mutate(NotNull(), 5))
2019 .WillOnce(SetArrayArgument<0>(values, values + 5));
2022 This also works when the argument is an output iterator:
2026 using ::testing::SetArrayArgument;
2028 class MockRolodex : public Rolodex {
2030 MOCK_METHOD(void, GetNames, (std::back_insert_iterator<vector<string>>),
2035 MockRolodex rolodex;
2036 vector<string> names;
2037 names.push_back("George");
2038 names.push_back("John");
2039 names.push_back("Thomas");
2040 EXPECT_CALL(rolodex, GetNames(_))
2041 .WillOnce(SetArrayArgument<0>(names.begin(), names.end()));
2044 ### Changing a Mock Object's Behavior Based on the State
2046 If you expect a call to change the behavior of a mock object, you can use
2047 `::testing::InSequence` to specify different behaviors before and after the
2051 using ::testing::InSequence;
2052 using ::testing::Return;
2057 EXPECT_CALL(my_mock, IsDirty())
2058 .WillRepeatedly(Return(true));
2059 EXPECT_CALL(my_mock, Flush());
2060 EXPECT_CALL(my_mock, IsDirty())
2061 .WillRepeatedly(Return(false));
2063 my_mock.FlushIfDirty();
2066 This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called
2067 and return `false` afterwards.
2069 If the behavior change is more complex, you can store the effects in a variable
2070 and make a mock method get its return value from that variable:
2074 using ::testing::SaveArg;
2075 using ::testing::Return;
2077 ACTION_P(ReturnPointee, p) { return *p; }
2079 int previous_value = 0;
2080 EXPECT_CALL(my_mock, GetPrevValue)
2081 .WillRepeatedly(ReturnPointee(&previous_value));
2082 EXPECT_CALL(my_mock, UpdateValue)
2083 .WillRepeatedly(SaveArg<0>(&previous_value));
2084 my_mock.DoSomethingToUpdateValue();
2087 Here `my_mock.GetPrevValue()` will always return the argument of the last
2088 `UpdateValue()` call.
2090 ### Setting the Default Value for a Return Type {#DefaultValue}
2092 If a mock method's return type is a built-in C++ type or pointer, by default it
2093 will return 0 when invoked. Also, in C++ 11 and above, a mock method whose
2094 return type has a default constructor will return a default-constructed value by
2095 default. You only need to specify an action if this default value doesn't work
2098 Sometimes, you may want to change this default value, or you may want to specify
2099 a default value for types gMock doesn't know about. You can do this using the
2100 `::testing::DefaultValue` class template:
2103 using ::testing::DefaultValue;
2105 class MockFoo : public Foo {
2107 MOCK_METHOD(Bar, CalculateBar, (), (override));
2113 // Sets the default return value for type Bar.
2114 DefaultValue<Bar>::Set(default_bar);
2118 // We don't need to specify an action here, as the default
2119 // return value works for us.
2120 EXPECT_CALL(foo, CalculateBar());
2122 foo.CalculateBar(); // This should return default_bar.
2124 // Unsets the default return value.
2125 DefaultValue<Bar>::Clear();
2128 Please note that changing the default value for a type can make your tests hard
2129 to understand. We recommend you to use this feature judiciously. For example,
2130 you may want to make sure the `Set()` and `Clear()` calls are right next to the
2131 code that uses your mock.
2133 ### Setting the Default Actions for a Mock Method
2135 You've learned how to change the default value of a given type. However, this
2136 may be too coarse for your purpose: perhaps you have two mock methods with the
2137 same return type and you want them to have different behaviors. The `ON_CALL()`
2138 macro allows you to customize your mock's behavior at the method level:
2142 using ::testing::AnyNumber;
2143 using ::testing::Gt;
2144 using ::testing::Return;
2146 ON_CALL(foo, Sign(_))
2147 .WillByDefault(Return(-1));
2148 ON_CALL(foo, Sign(0))
2149 .WillByDefault(Return(0));
2150 ON_CALL(foo, Sign(Gt(0)))
2151 .WillByDefault(Return(1));
2153 EXPECT_CALL(foo, Sign(_))
2154 .Times(AnyNumber());
2156 foo.Sign(5); // This should return 1.
2157 foo.Sign(-9); // This should return -1.
2158 foo.Sign(0); // This should return 0.
2161 As you may have guessed, when there are more than one `ON_CALL()` statements,
2162 the newer ones in the order take precedence over the older ones. In other words,
2163 the **last** one that matches the function arguments will be used. This matching
2164 order allows you to set up the common behavior in a mock object's constructor or
2165 the test fixture's set-up phase and specialize the mock's behavior later.
2167 Note that both `ON_CALL` and `EXPECT_CALL` have the same "later statements take
2168 precedence" rule, but they don't interact. That is, `EXPECT_CALL`s have their
2169 own precedence order distinct from the `ON_CALL` precedence order.
2171 ### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions}
2173 If the built-in actions don't suit you, you can use an existing callable
2174 (function, `std::function`, method, functor, lambda) as an action.
2177 using ::testing::_; using ::testing::Invoke;
2179 class MockFoo : public Foo {
2181 MOCK_METHOD(int, Sum, (int x, int y), (override));
2182 MOCK_METHOD(bool, ComplexJob, (int x), (override));
2185 int CalculateSum(int x, int y) { return x + y; }
2186 int Sum3(int x, int y, int z) { return x + y + z; }
2190 bool ComplexJob(int x);
2196 EXPECT_CALL(foo, Sum(_, _))
2197 .WillOnce(&CalculateSum)
2198 .WillRepeatedly(Invoke(NewPermanentCallback(Sum3, 1)));
2199 EXPECT_CALL(foo, ComplexJob(_))
2200 .WillOnce(Invoke(&helper, &Helper::ComplexJob))
2201 .WillOnce([] { return true; })
2202 .WillRepeatedly([](int x) { return x > 0; });
2204 foo.Sum(5, 6); // Invokes CalculateSum(5, 6).
2205 foo.Sum(2, 3); // Invokes Sum3(1, 2, 3).
2206 foo.ComplexJob(10); // Invokes helper.ComplexJob(10).
2207 foo.ComplexJob(-1); // Invokes the inline lambda.
2210 The only requirement is that the type of the function, etc must be *compatible*
2211 with the signature of the mock function, meaning that the latter's arguments (if
2212 it takes any) can be implicitly converted to the corresponding arguments of the
2213 former, and the former's return type can be implicitly converted to that of the
2214 latter. So, you can invoke something whose type is *not* exactly the same as the
2215 mock function, as long as it's safe to do so - nice, huh?
2219 * The action takes ownership of the callback and will delete it when the
2220 action itself is destructed.
2221 * If the type of a callback is derived from a base callback type `C`, you need
2222 to implicitly cast it to `C` to resolve the overloading, e.g.
2225 using ::testing::Invoke;
2227 ResultCallback<bool>* is_ok = ...;
2228 ... Invoke(is_ok) ...; // This works.
2230 BlockingClosure* done = new BlockingClosure;
2231 ... Invoke(implicit_cast<Closure*>(done)) ...; // The cast is necessary.
2234 ### Using Functions with Extra Info as Actions
2236 The function or functor you call using `Invoke()` must have the same number of
2237 arguments as the mock function you use it for. Sometimes you may have a function
2238 that takes more arguments, and you are willing to pass in the extra arguments
2239 yourself to fill the gap. You can do this in gMock using callbacks with
2240 pre-bound arguments. Here's an example:
2243 using ::testing::Invoke;
2245 class MockFoo : public Foo {
2247 MOCK_METHOD(char, DoThis, (int n), (override));
2250 char SignOfSum(int x, int y) {
2251 const int sum = x + y;
2252 return (sum > 0) ? '+' : (sum < 0) ? '-' : '0';
2255 TEST_F(FooTest, Test) {
2258 EXPECT_CALL(foo, DoThis(2))
2259 .WillOnce(Invoke(NewPermanentCallback(SignOfSum, 5)));
2260 EXPECT_EQ('+', foo.DoThis(2)); // Invokes SignOfSum(5, 2).
2264 ### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments
2266 `Invoke()` passes the mock function's arguments to the function, etc being
2267 invoked such that the callee has the full context of the call to work with. If
2268 the invoked function is not interested in some or all of the arguments, it can
2271 Yet, a common pattern is that a test author wants to invoke a function without
2272 the arguments of the mock function. She could do that using a wrapper function
2273 that throws away the arguments before invoking an underlining nullary function.
2274 Needless to say, this can be tedious and obscures the intent of the test.
2276 There are two solutions to this problem. First, you can pass any callable of
2277 zero args as an action. Alternatively, use `InvokeWithoutArgs()`, which is like
2278 `Invoke()` except that it doesn't pass the mock function's arguments to the
2279 callee. Here's an example of each:
2283 using ::testing::InvokeWithoutArgs;
2285 class MockFoo : public Foo {
2287 MOCK_METHOD(bool, ComplexJob, (int n), (override));
2291 bool Job2(int n, char c) { ... }
2295 EXPECT_CALL(foo, ComplexJob(_))
2296 .WillOnce([] { Job1(); });
2297 .WillOnce(InvokeWithoutArgs(NewPermanentCallback(Job2, 5, 'a')));
2299 foo.ComplexJob(10); // Invokes Job1().
2300 foo.ComplexJob(20); // Invokes Job2(5, 'a').
2305 * The action takes ownership of the callback and will delete it when the
2306 action itself is destructed.
2307 * If the type of a callback is derived from a base callback type `C`, you need
2308 to implicitly cast it to `C` to resolve the overloading, e.g.
2311 using ::testing::InvokeWithoutArgs;
2313 ResultCallback<bool>* is_ok = ...;
2314 ... InvokeWithoutArgs(is_ok) ...; // This works.
2316 BlockingClosure* done = ...;
2317 ... InvokeWithoutArgs(implicit_cast<Closure*>(done)) ...;
2318 // The cast is necessary.
2321 ### Invoking an Argument of the Mock Function
2323 Sometimes a mock function will receive a function pointer, a functor (in other
2324 words, a "callable") as an argument, e.g.
2327 class MockFoo : public Foo {
2329 MOCK_METHOD(bool, DoThis, (int n, (ResultCallback1<bool, int>* callback)),
2334 and you may want to invoke this callable argument:
2340 EXPECT_CALL(foo, DoThis(_, _))
2342 // Will execute callback->Run(5), where callback is the
2343 // second argument DoThis() receives.
2347 NOTE: The section below is legacy documentation from before C++ had lambdas:
2349 Arghh, you need to refer to a mock function argument but C++ has no lambda
2350 (yet), so you have to define your own action. :-( Or do you really?
2352 Well, gMock has an action to solve *exactly* this problem:
2355 InvokeArgument<N>(arg_1, arg_2, ..., arg_m)
2358 will invoke the `N`-th (0-based) argument the mock function receives, with
2359 `arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is a function
2360 pointer, a functor, or a callback. gMock handles them all.
2362 With that, you could write:
2366 using ::testing::InvokeArgument;
2368 EXPECT_CALL(foo, DoThis(_, _))
2369 .WillOnce(InvokeArgument<1>(5));
2370 // Will execute callback->Run(5), where callback is the
2371 // second argument DoThis() receives.
2374 What if the callable takes an argument by reference? No problem - just wrap it
2375 inside `std::ref()`:
2379 MOCK_METHOD(bool, Bar,
2380 ((ResultCallback2<bool, int, const Helper&>* callback)),
2384 using ::testing::InvokeArgument;
2389 EXPECT_CALL(foo, Bar(_))
2390 .WillOnce(InvokeArgument<0>(5, std::ref(helper)));
2391 // std::ref(helper) guarantees that a reference to helper, not a copy of
2392 // it, will be passed to the callback.
2395 What if the callable takes an argument by reference and we do **not** wrap the
2396 argument in `std::ref()`? Then `InvokeArgument()` will *make a copy* of the
2397 argument, and pass a *reference to the copy*, instead of a reference to the
2398 original value, to the callable. This is especially handy when the argument is a
2403 MOCK_METHOD(bool, DoThat, (bool (*f)(const double& x, const string& s)),
2407 using ::testing::InvokeArgument;
2411 EXPECT_CALL(foo, DoThat(_))
2412 .WillOnce(InvokeArgument<0>(5.0, string("Hi")));
2413 // Will execute (*f)(5.0, string("Hi")), where f is the function pointer
2414 // DoThat() receives. Note that the values 5.0 and string("Hi") are
2415 // temporary and dead once the EXPECT_CALL() statement finishes. Yet
2416 // it's fine to perform this action later, since a copy of the values
2417 // are kept inside the InvokeArgument action.
2420 ### Ignoring an Action's Result
2422 Sometimes you have an action that returns *something*, but you need an action
2423 that returns `void` (perhaps you want to use it in a mock function that returns
2424 `void`, or perhaps it needs to be used in `DoAll()` and it's not the last in the
2425 list). `IgnoreResult()` lets you do that. For example:
2429 using ::testing::DoAll;
2430 using ::testing::IgnoreResult;
2431 using ::testing::Return;
2433 int Process(const MyData& data);
2434 string DoSomething();
2436 class MockFoo : public Foo {
2438 MOCK_METHOD(void, Abc, (const MyData& data), (override));
2439 MOCK_METHOD(bool, Xyz, (), (override));
2444 EXPECT_CALL(foo, Abc(_))
2445 // .WillOnce(Invoke(Process));
2446 // The above line won't compile as Process() returns int but Abc() needs
2448 .WillOnce(IgnoreResult(Process));
2449 EXPECT_CALL(foo, Xyz())
2450 .WillOnce(DoAll(IgnoreResult(DoSomething),
2451 // Ignores the string DoSomething() returns.
2455 Note that you **cannot** use `IgnoreResult()` on an action that already returns
2456 `void`. Doing so will lead to ugly compiler errors.
2458 ### Selecting an Action's Arguments {#SelectingArgs}
2460 Say you have a mock function `Foo()` that takes seven arguments, and you have a
2461 custom action that you want to invoke when `Foo()` is called. Trouble is, the
2462 custom action only wants three arguments:
2466 using ::testing::Invoke;
2468 MOCK_METHOD(bool, Foo,
2469 (bool visible, const string& name, int x, int y,
2470 (const map<pair<int, int>>), double& weight, double min_weight,
2473 bool IsVisibleInQuadrant1(bool visible, int x, int y) {
2474 return visible && x >= 0 && y >= 0;
2477 EXPECT_CALL(mock, Foo)
2478 .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-(
2481 To please the compiler God, you need to define an "adaptor" that has the same
2482 signature as `Foo()` and calls the custom action with the right arguments:
2486 using ::testing::Invoke;
2488 bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y,
2489 const map<pair<int, int>, double>& weight,
2490 double min_weight, double max_wight) {
2491 return IsVisibleInQuadrant1(visible, x, y);
2494 EXPECT_CALL(mock, Foo)
2495 .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works.
2498 But isn't this awkward?
2500 gMock provides a generic *action adaptor*, so you can spend your time minding
2501 more important business than writing your own adaptors. Here's the syntax:
2504 WithArgs<N1, N2, ..., Nk>(action)
2507 creates an action that passes the arguments of the mock function at the given
2508 indices (0-based) to the inner `action` and performs it. Using `WithArgs`, our
2509 original example can be written as:
2513 using ::testing::Invoke;
2514 using ::testing::WithArgs;
2516 EXPECT_CALL(mock, Foo)
2517 .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); // No need to define your own adaptor.
2520 For better readability, gMock also gives you:
2522 * `WithoutArgs(action)` when the inner `action` takes *no* argument, and
2523 * `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes
2526 As you may have realized, `InvokeWithoutArgs(...)` is just syntactic sugar for
2527 `WithoutArgs(Invoke(...))`.
2531 * The inner action used in `WithArgs` and friends does not have to be
2532 `Invoke()` -- it can be anything.
2533 * You can repeat an argument in the argument list if necessary, e.g.
2534 `WithArgs<2, 3, 3, 5>(...)`.
2535 * You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`.
2536 * The types of the selected arguments do *not* have to match the signature of
2537 the inner action exactly. It works as long as they can be implicitly
2538 converted to the corresponding arguments of the inner action. For example,
2539 if the 4-th argument of the mock function is an `int` and `my_action` takes
2540 a `double`, `WithArg<4>(my_action)` will work.
2542 ### Ignoring Arguments in Action Functions
2544 The [selecting-an-action's-arguments](#SelectingArgs) recipe showed us one way
2545 to make a mock function and an action with incompatible argument lists fit
2546 together. The downside is that wrapping the action in `WithArgs<...>()` can get
2547 tedious for people writing the tests.
2549 If you are defining a function (or method, functor, lambda, callback) to be used
2550 with `Invoke*()`, and you are not interested in some of its arguments, an
2551 alternative to `WithArgs` is to declare the uninteresting arguments as `Unused`.
2552 This makes the definition less cluttered and less fragile in case the types of
2553 the uninteresting arguments change. It could also increase the chance the action
2554 function can be reused. For example, given
2558 MOCK_METHOD(double, Foo, double(const string& label, double x, double y),
2560 MOCK_METHOD(double, Bar, (int index, double x, double y), (override));
2567 using ::testing::Invoke;
2569 double DistanceToOriginWithLabel(const string& label, double x, double y) {
2570 return sqrt(x*x + y*y);
2572 double DistanceToOriginWithIndex(int index, double x, double y) {
2573 return sqrt(x*x + y*y);
2576 EXPECT_CALL(mock, Foo("abc", _, _))
2577 .WillOnce(Invoke(DistanceToOriginWithLabel));
2578 EXPECT_CALL(mock, Bar(5, _, _))
2579 .WillOnce(Invoke(DistanceToOriginWithIndex));
2586 using ::testing::Invoke;
2587 using ::testing::Unused;
2589 double DistanceToOrigin(Unused, double x, double y) {
2590 return sqrt(x*x + y*y);
2593 EXPECT_CALL(mock, Foo("abc", _, _))
2594 .WillOnce(Invoke(DistanceToOrigin));
2595 EXPECT_CALL(mock, Bar(5, _, _))
2596 .WillOnce(Invoke(DistanceToOrigin));
2601 Just like matchers, a gMock action object consists of a pointer to a ref-counted
2602 implementation object. Therefore copying actions is also allowed and very
2603 efficient. When the last action that references the implementation object dies,
2604 the implementation object will be deleted.
2606 If you have some complex action that you want to use again and again, you may
2607 not have to build it from scratch everytime. If the action doesn't have an
2608 internal state (i.e. if it always does the same thing no matter how many times
2609 it has been called), you can assign it to an action variable and use that
2610 variable repeatedly. For example:
2613 using ::testing::Action;
2614 using ::testing::DoAll;
2615 using ::testing::Return;
2616 using ::testing::SetArgPointee;
2618 Action<bool(int*)> set_flag = DoAll(SetArgPointee<0>(5),
2620 ... use set_flag in .WillOnce() and .WillRepeatedly() ...
2623 However, if the action has its own state, you may be surprised if you share the
2624 action object. Suppose you have an action factory `IncrementCounter(init)` which
2625 creates an action that increments and returns a counter whose initial value is
2626 `init`, using two actions created from the same expression and using a shared
2627 action will exhibit different behaviors. Example:
2630 EXPECT_CALL(foo, DoThis())
2631 .WillRepeatedly(IncrementCounter(0));
2632 EXPECT_CALL(foo, DoThat())
2633 .WillRepeatedly(IncrementCounter(0));
2634 foo.DoThis(); // Returns 1.
2635 foo.DoThis(); // Returns 2.
2636 foo.DoThat(); // Returns 1 - Blah() uses a different
2637 // counter than Bar()'s.
2643 using ::testing::Action;
2645 Action<int()> increment = IncrementCounter(0);
2646 EXPECT_CALL(foo, DoThis())
2647 .WillRepeatedly(increment);
2648 EXPECT_CALL(foo, DoThat())
2649 .WillRepeatedly(increment);
2650 foo.DoThis(); // Returns 1.
2651 foo.DoThis(); // Returns 2.
2652 foo.DoThat(); // Returns 3 - the counter is shared.
2655 ### Testing Asynchronous Behavior
2657 One oft-encountered problem with gMock is that it can be hard to test
2658 asynchronous behavior. Suppose you had a `EventQueue` class that you wanted to
2659 test, and you created a separate `EventDispatcher` interface so that you could
2660 easily mock it out. However, the implementation of the class fired all the
2661 events on a background thread, which made test timings difficult. You could just
2662 insert `sleep()` statements and hope for the best, but that makes your test
2663 behavior nondeterministic. A better way is to use gMock actions and
2664 `Notification` objects to force your asynchronous test to behave synchronously.
2667 class MockEventDispatcher : public EventDispatcher {
2668 MOCK_METHOD(bool, DispatchEvent, (int32), (override));
2671 TEST(EventQueueTest, EnqueueEventTest) {
2672 MockEventDispatcher mock_event_dispatcher;
2673 EventQueue event_queue(&mock_event_dispatcher);
2675 const int32 kEventId = 321;
2676 absl::Notification done;
2677 EXPECT_CALL(mock_event_dispatcher, DispatchEvent(kEventId))
2678 .WillOnce([&done] { done.Notify(); });
2680 event_queue.EnqueueEvent(kEventId);
2681 done.WaitForNotification();
2685 In the example above, we set our normal gMock expectations, but then add an
2686 additional action to notify the `Notification` object. Now we can just call
2687 `Notification::WaitForNotification()` in the main thread to wait for the
2688 asynchronous call to finish. After that, our test suite is complete and we can
2692 Note: this example has a downside: namely, if the expectation is not satisfied,
2693 our test will run forever. It will eventually time-out and fail, but it will
2694 take longer and be slightly harder to debug. To alleviate this problem, you can
2695 use `WaitForNotificationWithTimeout(ms)` instead of `WaitForNotification()`.
2697 ## Misc Recipes on Using gMock
2699 ### Mocking Methods That Use Move-Only Types
2701 C++11 introduced *move-only types*. A move-only-typed value can be moved from
2702 one object to another, but cannot be copied. `std::unique_ptr<T>` is probably
2703 the most commonly used move-only type.
2705 Mocking a method that takes and/or returns move-only types presents some
2706 challenges, but nothing insurmountable. This recipe shows you how you can do it.
2707 Note that the support for move-only method arguments was only introduced to
2708 gMock in April 2017; in older code, you may find more complex
2709 [workarounds](#LegacyMoveOnly) for lack of this feature.
2711 Let’s say we are working on a fictional project that lets one post and share
2712 snippets called “buzzes”. Your code uses these types:
2715 enum class AccessLevel { kInternal, kPublic };
2719 explicit Buzz(AccessLevel access) { ... }
2725 virtual ~Buzzer() {}
2726 virtual std::unique_ptr<Buzz> MakeBuzz(StringPiece text) = 0;
2727 virtual bool ShareBuzz(std::unique_ptr<Buzz> buzz, int64_t timestamp) = 0;
2732 A `Buzz` object represents a snippet being posted. A class that implements the
2733 `Buzzer` interface is capable of creating and sharing `Buzz`es. Methods in
2734 `Buzzer` may return a `unique_ptr<Buzz>` or take a `unique_ptr<Buzz>`. Now we
2735 need to mock `Buzzer` in our tests.
2737 To mock a method that accepts or returns move-only types, you just use the
2738 familiar `MOCK_METHOD` syntax as usual:
2741 class MockBuzzer : public Buzzer {
2743 MOCK_METHOD(std::unique_ptr<Buzz>, MakeBuzz, (StringPiece text), (override));
2744 MOCK_METHOD(bool, ShareBuzz, (std::unique_ptr<Buzz> buzz, int64_t timestamp),
2749 Now that we have the mock class defined, we can use it in tests. In the
2750 following code examples, we assume that we have defined a `MockBuzzer` object
2751 named `mock_buzzer_`:
2754 MockBuzzer mock_buzzer_;
2757 First let’s see how we can set expectations on the `MakeBuzz()` method, which
2758 returns a `unique_ptr<Buzz>`.
2760 As usual, if you set an expectation without an action (i.e. the `.WillOnce()` or
2761 `.WillRepeatedly()` clause), when that expectation fires, the default action for
2762 that method will be taken. Since `unique_ptr<>` has a default constructor that
2763 returns a null `unique_ptr`, that’s what you’ll get if you don’t specify an
2767 // Use the default action.
2768 EXPECT_CALL(mock_buzzer_, MakeBuzz("hello"));
2770 // Triggers the previous EXPECT_CALL.
2771 EXPECT_EQ(nullptr, mock_buzzer_.MakeBuzz("hello"));
2774 If you are not happy with the default action, you can tweak it as usual; see
2775 [Setting Default Actions](#OnCall).
2777 If you just need to return a pre-defined move-only value, you can use the
2778 `Return(ByMove(...))` action:
2781 // When this fires, the unique_ptr<> specified by ByMove(...) will
2783 EXPECT_CALL(mock_buzzer_, MakeBuzz("world"))
2784 .WillOnce(Return(ByMove(MakeUnique<Buzz>(AccessLevel::kInternal))));
2786 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("world"));
2789 Note that `ByMove()` is essential here - if you drop it, the code won’t compile.
2791 Quiz time! What do you think will happen if a `Return(ByMove(...))` action is
2792 performed more than once (e.g. you write `...
2793 .WillRepeatedly(Return(ByMove(...)));`)? Come think of it, after the first time
2794 the action runs, the source value will be consumed (since it’s a move-only
2795 value), so the next time around, there’s no value to move from -- you’ll get a
2796 run-time error that `Return(ByMove(...))` can only be run once.
2798 If you need your mock method to do more than just moving a pre-defined value,
2799 remember that you can always use a lambda or a callable object, which can do
2800 pretty much anything you want:
2803 EXPECT_CALL(mock_buzzer_, MakeBuzz("x"))
2804 .WillRepeatedly([](StringPiece text) {
2805 return MakeUnique<Buzz>(AccessLevel::kInternal);
2808 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x"));
2809 EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x"));
2812 Every time this `EXPECT_CALL` fires, a new `unique_ptr<Buzz>` will be created
2813 and returned. You cannot do this with `Return(ByMove(...))`.
2815 That covers returning move-only values; but how do we work with methods
2816 accepting move-only arguments? The answer is that they work normally, although
2817 some actions will not compile when any of method's arguments are move-only. You
2818 can always use `Return`, or a [lambda or functor](#FunctionsAsActions):
2821 using ::testing::Unused;
2823 EXPECT_CALL(mock_buzzer_, ShareBuzz(NotNull(), _)).WillOnce(Return(true));
2824 EXPECT_TRUE(mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal)),
2827 EXPECT_CALL(mock_buzzer_, ShareBuzz(_, _)).WillOnce(
2828 [](std::unique_ptr<Buzz> buzz, Unused) { return buzz != nullptr; });
2829 EXPECT_FALSE(mock_buzzer_.ShareBuzz(nullptr, 0));
2832 Many built-in actions (`WithArgs`, `WithoutArgs`,`DeleteArg`, `SaveArg`, ...)
2833 could in principle support move-only arguments, but the support for this is not
2834 implemented yet. If this is blocking you, please file a bug.
2836 A few actions (e.g. `DoAll`) copy their arguments internally, so they can never
2837 work with non-copyable objects; you'll have to use functors instead.
2839 #### Legacy workarounds for move-only types {#LegacyMoveOnly}
2841 Support for move-only function arguments was only introduced to gMock in April
2842 of 2017. In older code, you may encounter the following workaround for the lack
2843 of this feature (it is no longer necessary - we're including it just for
2847 class MockBuzzer : public Buzzer {
2849 MOCK_METHOD(bool, DoShareBuzz, (Buzz* buzz, Time timestamp));
2850 bool ShareBuzz(std::unique_ptr<Buzz> buzz, Time timestamp) override {
2851 return DoShareBuzz(buzz.get(), timestamp);
2856 The trick is to delegate the `ShareBuzz()` method to a mock method (let’s call
2857 it `DoShareBuzz()`) that does not take move-only parameters. Then, instead of
2858 setting expectations on `ShareBuzz()`, you set them on the `DoShareBuzz()` mock
2862 MockBuzzer mock_buzzer_;
2863 EXPECT_CALL(mock_buzzer_, DoShareBuzz(NotNull(), _));
2865 // When one calls ShareBuzz() on the MockBuzzer like this, the call is
2866 // forwarded to DoShareBuzz(), which is mocked. Therefore this statement
2867 // will trigger the above EXPECT_CALL.
2868 mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal), 0);
2871 ### Making the Compilation Faster
2873 Believe it or not, the *vast majority* of the time spent on compiling a mock
2874 class is in generating its constructor and destructor, as they perform
2875 non-trivial tasks (e.g. verification of the expectations). What's more, mock
2876 methods with different signatures have different types and thus their
2877 constructors/destructors need to be generated by the compiler separately. As a
2878 result, if you mock many different types of methods, compiling your mock class
2879 can get really slow.
2881 If you are experiencing slow compilation, you can move the definition of your
2882 mock class' constructor and destructor out of the class body and into a `.cc`
2883 file. This way, even if you `#include` your mock class in N files, the compiler
2884 only needs to generate its constructor and destructor once, resulting in a much
2887 Let's illustrate the idea using an example. Here's the definition of a mock
2888 class before applying this recipe:
2893 class MockFoo : public Foo {
2895 // Since we don't declare the constructor or the destructor,
2896 // the compiler will generate them in every translation unit
2897 // where this mock class is used.
2899 MOCK_METHOD(int, DoThis, (), (override));
2900 MOCK_METHOD(bool, DoThat, (const char* str), (override));
2901 ... more mock methods ...
2905 After the change, it would look like:
2910 class MockFoo : public Foo {
2912 // The constructor and destructor are declared, but not defined, here.
2916 MOCK_METHOD(int, DoThis, (), (override));
2917 MOCK_METHOD(bool, DoThat, (const char* str), (override));
2918 ... more mock methods ...
2925 // File mock_foo.cc.
2926 #include "path/to/mock_foo.h"
2928 // The definitions may appear trivial, but the functions actually do a
2929 // lot of things through the constructors/destructors of the member
2930 // variables used to implement the mock methods.
2931 MockFoo::MockFoo() {}
2932 MockFoo::~MockFoo() {}
2935 ### Forcing a Verification
2937 When it's being destroyed, your friendly mock object will automatically verify
2938 that all expectations on it have been satisfied, and will generate googletest
2939 failures if not. This is convenient as it leaves you with one less thing to
2940 worry about. That is, unless you are not sure if your mock object will be
2943 How could it be that your mock object won't eventually be destroyed? Well, it
2944 might be created on the heap and owned by the code you are testing. Suppose
2945 there's a bug in that code and it doesn't delete the mock object properly - you
2946 could end up with a passing test when there's actually a bug.
2948 Using a heap checker is a good idea and can alleviate the concern, but its
2949 implementation is not 100% reliable. So, sometimes you do want to *force* gMock
2950 to verify a mock object before it is (hopefully) destructed. You can do this
2951 with `Mock::VerifyAndClearExpectations(&mock_object)`:
2954 TEST(MyServerTest, ProcessesRequest) {
2955 using ::testing::Mock;
2957 MockFoo* const foo = new MockFoo;
2958 EXPECT_CALL(*foo, ...)...;
2959 // ... other expectations ...
2961 // server now owns foo.
2962 MyServer server(foo);
2963 server.ProcessRequest(...);
2965 // In case that server's destructor will forget to delete foo,
2966 // this will verify the expectations anyway.
2967 Mock::VerifyAndClearExpectations(foo);
2968 } // server is destroyed when it goes out of scope here.
2972 **Tip:** The `Mock::VerifyAndClearExpectations()` function returns a `bool` to
2973 indicate whether the verification was successful (`true` for yes), so you can
2974 wrap that function call inside a `ASSERT_TRUE()` if there is no point going
2975 further when the verification has failed.
2977 Do not set new expectations after verifying and clearing a mock after its use.
2978 Setting expectations after code that exercises the mock has undefined behavior.
2979 See [Using Mocks in Tests](gmock_for_dummies.md#using-mocks-in-tests) for more
2982 ### Using Checkpoints {#UsingCheckPoints}
2984 Sometimes you might want to test a mock object's behavior in phases whose sizes
2985 are each manageable, or you might want to set more detailed expectations about
2986 which API calls invoke which mock functions.
2988 A technique you can use is to put the expectations in a sequence and insert
2989 calls to a dummy "checkpoint" function at specific places. Then you can verify
2990 that the mock function calls do happen at the right time. For example, if you
2991 are exercising the code:
2999 and want to verify that `Foo(1)` and `Foo(3)` both invoke `mock.Bar("a")`, but
3000 `Foo(2)` doesn't invoke anything, you can write:
3003 using ::testing::MockFunction;
3005 TEST(FooTest, InvokesBarCorrectly) {
3007 // Class MockFunction<F> has exactly one mock method. It is named
3008 // Call() and has type F.
3009 MockFunction<void(string check_point_name)> check;
3013 EXPECT_CALL(mock, Bar("a"));
3014 EXPECT_CALL(check, Call("1"));
3015 EXPECT_CALL(check, Call("2"));
3016 EXPECT_CALL(mock, Bar("a"));
3026 The expectation spec says that the first `Bar("a")` call must happen before
3027 checkpoint "1", the second `Bar("a")` call must happen after checkpoint "2", and
3028 nothing should happen between the two checkpoints. The explicit checkpoints make
3029 it clear which `Bar("a")` is called by which call to `Foo()`.
3031 ### Mocking Destructors
3033 Sometimes you want to make sure a mock object is destructed at the right time,
3034 e.g. after `bar->A()` is called but before `bar->B()` is called. We already know
3035 that you can specify constraints on the [order](#OrderedCalls) of mock function
3036 calls, so all we need to do is to mock the destructor of the mock function.
3038 This sounds simple, except for one problem: a destructor is a special function
3039 with special syntax and special semantics, and the `MOCK_METHOD` macro doesn't
3043 MOCK_METHOD(void, ~MockFoo, ()); // Won't compile!
3046 The good news is that you can use a simple pattern to achieve the same effect.
3047 First, add a mock function `Die()` to your mock class and call it in the
3048 destructor, like this:
3051 class MockFoo : public Foo {
3053 // Add the following two lines to the mock class.
3054 MOCK_METHOD(void, Die, ());
3055 ~MockFoo() override { Die(); }
3059 (If the name `Die()` clashes with an existing symbol, choose another name.) Now,
3060 we have translated the problem of testing when a `MockFoo` object dies to
3061 testing when its `Die()` method is called:
3064 MockFoo* foo = new MockFoo;
3065 MockBar* bar = new MockBar;
3070 // Expects *foo to die after bar->A() and before bar->B().
3071 EXPECT_CALL(*bar, A());
3072 EXPECT_CALL(*foo, Die());
3073 EXPECT_CALL(*bar, B());
3079 ### Using gMock and Threads {#UsingThreads}
3081 In a **unit** test, it's best if you could isolate and test a piece of code in a
3082 single-threaded context. That avoids race conditions and dead locks, and makes
3083 debugging your test much easier.
3085 Yet most programs are multi-threaded, and sometimes to test something we need to
3086 pound on it from more than one thread. gMock works for this purpose too.
3088 Remember the steps for using a mock:
3090 1. Create a mock object `foo`.
3091 2. Set its default actions and expectations using `ON_CALL()` and
3093 3. The code under test calls methods of `foo`.
3094 4. Optionally, verify and reset the mock.
3095 5. Destroy the mock yourself, or let the code under test destroy it. The
3096 destructor will automatically verify it.
3098 If you follow the following simple rules, your mocks and threads can live
3101 * Execute your *test code* (as opposed to the code being tested) in *one*
3102 thread. This makes your test easy to follow.
3103 * Obviously, you can do step #1 without locking.
3104 * When doing step #2 and #5, make sure no other thread is accessing `foo`.
3106 * #3 and #4 can be done either in one thread or in multiple threads - anyway
3107 you want. gMock takes care of the locking, so you don't have to do any -
3108 unless required by your test logic.
3110 If you violate the rules (for example, if you set expectations on a mock while
3111 another thread is calling its methods), you get undefined behavior. That's not
3112 fun, so don't do it.
3114 gMock guarantees that the action for a mock function is done in the same thread
3115 that called the mock function. For example, in
3118 EXPECT_CALL(mock, Foo(1))
3120 EXPECT_CALL(mock, Foo(2))
3124 if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, gMock will
3125 execute `action1` in thread 1 and `action2` in thread 2.
3127 gMock does *not* impose a sequence on actions performed in different threads
3128 (doing so may create deadlocks as the actions may need to cooperate). This means
3129 that the execution of `action1` and `action2` in the above example *may*
3130 interleave. If this is a problem, you should add proper synchronization logic to
3131 `action1` and `action2` to make the test thread-safe.
3133 Also, remember that `DefaultValue<T>` is a global resource that potentially
3134 affects *all* living mock objects in your program. Naturally, you won't want to
3135 mess with it from multiple threads or when there still are mocks in action.
3137 ### Controlling How Much Information gMock Prints
3139 When gMock sees something that has the potential of being an error (e.g. a mock
3140 function with no expectation is called, a.k.a. an uninteresting call, which is
3141 allowed but perhaps you forgot to explicitly ban the call), it prints some
3142 warning messages, including the arguments of the function, the return value, and
3143 the stack trace. Hopefully this will remind you to take a look and see if there
3144 is indeed a problem.
3146 Sometimes you are confident that your tests are correct and may not appreciate
3147 such friendly messages. Some other times, you are debugging your tests or
3148 learning about the behavior of the code you are testing, and wish you could
3149 observe every mock call that happens (including argument values, the return
3150 value, and the stack trace). Clearly, one size doesn't fit all.
3152 You can control how much gMock tells you using the `--gmock_verbose=LEVEL`
3153 command-line flag, where `LEVEL` is a string with three possible values:
3155 * `info`: gMock will print all informational messages, warnings, and errors
3156 (most verbose). At this setting, gMock will also log any calls to the
3157 `ON_CALL/EXPECT_CALL` macros. It will include a stack trace in
3158 "uninteresting call" warnings.
3159 * `warning`: gMock will print both warnings and errors (less verbose); it will
3160 omit the stack traces in "uninteresting call" warnings. This is the default.
3161 * `error`: gMock will print errors only (least verbose).
3163 Alternatively, you can adjust the value of that flag from within your tests like
3167 ::testing::FLAGS_gmock_verbose = "error";
3170 If you find gMock printing too many stack frames with its informational or
3171 warning messages, remember that you can control their amount with the
3172 `--gtest_stack_trace_depth=max_depth` flag.
3174 Now, judiciously use the right flag to enable gMock serve you better!
3176 ### Gaining Super Vision into Mock Calls
3178 You have a test using gMock. It fails: gMock tells you some expectations aren't
3179 satisfied. However, you aren't sure why: Is there a typo somewhere in the
3180 matchers? Did you mess up the order of the `EXPECT_CALL`s? Or is the code under
3181 test doing something wrong? How can you find out the cause?
3183 Won't it be nice if you have X-ray vision and can actually see the trace of all
3184 `EXPECT_CALL`s and mock method calls as they are made? For each call, would you
3185 like to see its actual argument values and which `EXPECT_CALL` gMock thinks it
3186 matches? If you still need some help to figure out who made these calls, how
3187 about being able to see the complete stack trace at each mock call?
3189 You can unlock this power by running your test with the `--gmock_verbose=info`
3190 flag. For example, given the test program:
3193 #include "gmock/gmock.h"
3196 using testing::HasSubstr;
3197 using testing::Return;
3201 MOCK_METHOD(void, F, (const string& x, const string& y));
3206 EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return());
3207 EXPECT_CALL(mock, F("a", "b"));
3208 EXPECT_CALL(mock, F("c", HasSubstr("d")));
3210 mock.F("a", "good");
3215 if you run it with `--gmock_verbose=info`, you will see this output:
3220 foo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked
3223 foo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked
3226 foo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked
3229 foo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))...
3230 Function call: F(@0x7fff7c8dad40"a",@0x7fff7c8dad10"good")
3233 foo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))...
3234 Function call: F(@0x7fff7c8dada0"a",@0x7fff7c8dad70"b")
3237 foo_test.cc:16: Failure
3238 Actual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))...
3239 Expected: to be called once
3240 Actual: never called - unsatisfied and active
3244 Suppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo and
3245 should actually be `"a"`. With the above message, you should see that the actual
3246 `F("a", "good")` call is matched by the first `EXPECT_CALL`, not the third as
3247 you thought. From that it should be obvious that the third `EXPECT_CALL` is
3248 written wrong. Case solved.
3250 If you are interested in the mock call trace but not the stack traces, you can
3251 combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test
3254 ### Running Tests in Emacs
3256 If you build and run your tests in Emacs using the `M-x google-compile` command
3257 (as many googletest users do), the source file locations of gMock and googletest
3258 errors will be highlighted. Just press `<Enter>` on one of them and you'll be
3259 taken to the offending line. Or, you can just type `C-x`` to jump to the next
3262 To make it even easier, you can add the following lines to your `~/.emacs` file:
3265 (global-set-key "\M-m" 'google-compile) ; m is for make
3266 (global-set-key [M-down] 'next-error)
3267 (global-set-key [M-up] '(lambda () (interactive) (next-error -1)))
3270 Then you can type `M-m` to start a build (if you want to run the test as well,
3271 just make sure `foo_test.run` or `runtests` is in the build command you supply
3272 after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors.
3276 ### Writing New Matchers Quickly {#NewMatchers}
3278 {: .callout .warning}
3279 WARNING: gMock does not guarantee when or how many times a matcher will be
3280 invoked. Therefore, all matchers must be functionally pure. See
3281 [this section](#PureMatchers) for more details.
3283 The `MATCHER*` family of macros can be used to define custom matchers easily.
3287 MATCHER(name, description_string_expression) { statements; }
3290 will define a matcher with the given name that executes the statements, which
3291 must return a `bool` to indicate if the match succeeds. Inside the statements,
3292 you can refer to the value being matched by `arg`, and refer to its type by
3295 The *description string* is a `string`-typed expression that documents what the
3296 matcher does, and is used to generate the failure message when the match fails.
3297 It can (and should) reference the special `bool` variable `negation`, and should
3298 evaluate to the description of the matcher when `negation` is `false`, or that
3299 of the matcher's negation when `negation` is `true`.
3301 For convenience, we allow the description string to be empty (`""`), in which
3302 case gMock will use the sequence of words in the matcher name as the
3308 MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; }
3314 // Expects mock_foo.Bar(n) to be called where n is divisible by 7.
3315 EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7()));
3321 using ::testing::Not;
3323 // Verifies that a value is divisible by 7 and the other is not.
3324 EXPECT_THAT(some_expression, IsDivisibleBy7());
3325 EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7()));
3328 If the above assertions fail, they will print something like:
3331 Value of: some_expression
3332 Expected: is divisible by 7
3335 Value of: some_other_expression
3336 Expected: not (is divisible by 7)
3340 where the descriptions `"is divisible by 7"` and `"not (is divisible by 7)"` are
3341 automatically calculated from the matcher name `IsDivisibleBy7`.
3343 As you may have noticed, the auto-generated descriptions (especially those for
3344 the negation) may not be so great. You can always override them with a `string`
3345 expression of your own:
3348 MATCHER(IsDivisibleBy7,
3349 absl::StrCat(negation ? "isn't" : "is", " divisible by 7")) {
3350 return (arg % 7) == 0;
3354 Optionally, you can stream additional information to a hidden argument named
3355 `result_listener` to explain the match result. For example, a better definition
3356 of `IsDivisibleBy7` is:
3359 MATCHER(IsDivisibleBy7, "") {
3363 *result_listener << "the remainder is " << (arg % 7);
3368 With this definition, the above assertion will give a better message:
3371 Value of: some_expression
3372 Expected: is divisible by 7
3373 Actual: 27 (the remainder is 6)
3376 You should let `MatchAndExplain()` print *any additional information* that can
3377 help a user understand the match result. Note that it should explain why the
3378 match succeeds in case of a success (unless it's obvious) - this is useful when
3379 the matcher is used inside `Not()`. There is no need to print the argument value
3380 itself, as gMock already prints it for you.
3383 NOTE: The type of the value being matched (`arg_type`) is determined by the
3384 context in which you use the matcher and is supplied to you by the compiler, so
3385 you don't need to worry about declaring it (nor can you). This allows the
3386 matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match
3387 any type where the value of `(arg % 7) == 0` can be implicitly converted to a
3388 `bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an
3389 `int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will
3390 be `unsigned long`; and so on.
3392 ### Writing New Parameterized Matchers Quickly
3394 Sometimes you'll want to define a matcher that has parameters. For that you can
3398 MATCHER_P(name, param_name, description_string) { statements; }
3401 where the description string can be either `""` or a `string` expression that
3402 references `negation` and `param_name`.
3407 MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
3410 will allow you to write:
3413 EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
3416 which may lead to this message (assuming `n` is 10):
3420 Expected: has absolute value 10
3424 Note that both the matcher description and its parameter are printed, making the
3425 message human-friendly.
3427 In the matcher definition body, you can write `foo_type` to reference the type
3428 of a parameter named `foo`. For example, in the body of
3429 `MATCHER_P(HasAbsoluteValue, value)` above, you can write `value_type` to refer
3430 to the type of `value`.
3432 gMock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to `MATCHER_P10` to
3433 support multi-parameter matchers:
3436 MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; }
3439 Please note that the custom description string is for a particular *instance* of
3440 the matcher, where the parameters have been bound to actual values. Therefore
3441 usually you'll want the parameter values to be part of the description. gMock
3442 lets you do that by referencing the matcher parameters in the description string
3448 using ::testing::PrintToString;
3449 MATCHER_P2(InClosedRange, low, hi,
3450 absl::StrFormat("%s in range [%s, %s]", negation ? "isn't" : "is",
3451 PrintToString(low), PrintToString(hi))) {
3452 return low <= arg && arg <= hi;
3455 EXPECT_THAT(3, InClosedRange(4, 6));
3458 would generate a failure that contains the message:
3461 Expected: is in range [4, 6]
3464 If you specify `""` as the description, the failure message will contain the
3465 sequence of words in the matcher name followed by the parameter values printed
3466 as a tuple. For example,
3469 MATCHER_P2(InClosedRange, low, hi, "") { ... }
3471 EXPECT_THAT(3, InClosedRange(4, 6));
3474 would generate a failure that contains the text:
3477 Expected: in closed range (4, 6)
3480 For the purpose of typing, you can view
3483 MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
3489 template <typename p1_type, ..., typename pk_type>
3490 FooMatcherPk<p1_type, ..., pk_type>
3491 Foo(p1_type p1, ..., pk_type pk) { ... }
3494 When you write `Foo(v1, ..., vk)`, the compiler infers the types of the
3495 parameters `v1`, ..., and `vk` for you. If you are not happy with the result of
3496 the type inference, you can specify the types by explicitly instantiating the
3497 template, as in `Foo<long, bool>(5, false)`. As said earlier, you don't get to
3498 (or need to) specify `arg_type` as that's determined by the context in which the
3501 You can assign the result of expression `Foo(p1, ..., pk)` to a variable of type
3502 `FooMatcherPk<p1_type, ..., pk_type>`. This can be useful when composing
3503 matchers. Matchers that don't have a parameter or have only one parameter have
3504 special types: you can assign `Foo()` to a `FooMatcher`-typed variable, and
3505 assign `Foo(p)` to a `FooMatcherP<p_type>`-typed variable.
3507 While you can instantiate a matcher template with reference types, passing the
3508 parameters by pointer usually makes your code more readable. If, however, you
3509 still want to pass a parameter by reference, be aware that in the failure
3510 message generated by the matcher you will see the value of the referenced object
3511 but not its address.
3513 You can overload matchers with different numbers of parameters:
3516 MATCHER_P(Blah, a, description_string_1) { ... }
3517 MATCHER_P2(Blah, a, b, description_string_2) { ... }
3520 While it's tempting to always use the `MATCHER*` macros when defining a new
3521 matcher, you should also consider implementing the matcher interface directly
3522 instead (see the recipes that follow), especially if you need to use the matcher
3523 a lot. While these approaches require more work, they give you more control on
3524 the types of the value being matched and the matcher parameters, which in
3525 general leads to better compiler error messages that pay off in the long run.
3526 They also allow overloading matchers based on parameter types (as opposed to
3527 just based on the number of parameters).
3529 ### Writing New Monomorphic Matchers
3531 A matcher of argument type `T` implements the matcher interface for `T` and does
3532 two things: it tests whether a value of type `T` matches the matcher, and can
3533 describe what kind of values it matches. The latter ability is used for
3534 generating readable error messages when expectations are violated.
3536 A matcher of `T` must declare a typedef like:
3539 using is_gtest_matcher = void;
3542 and supports the following operations:
3545 // Match a value and optionally explain into an ostream.
3546 bool matched = matcher.MatchAndExplain(value, maybe_os);
3547 // where `value` is of type `T` and
3548 // `maybe_os` is of type `std::ostream*`, where it can be null if the caller
3549 // is not interested in there textual explanation.
3551 matcher.DescribeTo(os);
3552 matcher.DescribeNegationTo(os);
3553 // where `os` is of type `std::ostream*`.
3556 If you need a custom matcher but `Truly()` is not a good option (for example,
3557 you may not be happy with the way `Truly(predicate)` describes itself, or you
3558 may want your matcher to be polymorphic as `Eq(value)` is), you can define a
3559 matcher to do whatever you want in two steps: first implement the matcher
3560 interface, and then define a factory function to create a matcher instance. The
3561 second step is not strictly needed but it makes the syntax of using the matcher
3564 For example, you can define a matcher to test whether an `int` is divisible by 7
3565 and then use it like this:
3568 using ::testing::Matcher;
3570 class DivisibleBy7Matcher {
3572 using is_gtest_matcher = void;
3574 bool MatchAndExplain(int n, std::ostream*) const {
3575 return (n % 7) == 0;
3578 void DescribeTo(std::ostream* os) const {
3579 *os << "is divisible by 7";
3582 void DescribeNegationTo(std::ostream* os) const {
3583 *os << "is not divisible by 7";
3587 Matcher<int> DivisibleBy7() {
3588 return DivisibleBy7Matcher();
3592 EXPECT_CALL(foo, Bar(DivisibleBy7()));
3595 You may improve the matcher message by streaming additional information to the
3596 `os` argument in `MatchAndExplain()`:
3599 class DivisibleBy7Matcher {
3601 bool MatchAndExplain(int n, std::ostream* os) const {
3602 const int remainder = n % 7;
3603 if (remainder != 0 && os != nullptr) {
3604 *os << "the remainder is " << remainder;
3606 return remainder == 0;
3612 Then, `EXPECT_THAT(x, DivisibleBy7());` may generate a message like this:
3616 Expected: is divisible by 7
3617 Actual: 23 (the remainder is 2)
3621 Tip: for convenience, `MatchAndExplain()` can take a `MatchResultListener*`
3622 instead of `std::ostream*`.
3624 ### Writing New Polymorphic Matchers
3626 Expanding what we learned above to *polymorphic* matchers is now just as simple
3627 as adding templates in the right place.
3631 class NotNullMatcher {
3633 using is_gtest_matcher = void;
3635 // To implement a polymorphic matcher, we just need to make MatchAndExplain a
3636 // template on its first argument.
3638 // In this example, we want to use NotNull() with any pointer, so
3639 // MatchAndExplain() accepts a pointer of any type as its first argument.
3640 // In general, you can define MatchAndExplain() as an ordinary method or
3641 // a method template, or even overload it.
3642 template <typename T>
3643 bool MatchAndExplain(T* p, std::ostream*) const {
3644 return p != nullptr;
3647 // Describes the property of a value matching this matcher.
3648 void DescribeTo(std::ostream* os) const { *os << "is not NULL"; }
3650 // Describes the property of a value NOT matching this matcher.
3651 void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; }
3654 NotNullMatcher NotNull() {
3655 return NotNullMatcher();
3660 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
3663 ### Legacy Matcher Implementation
3665 Defining matchers used to be somewhat more complicated, in which it required
3666 several supporting classes and virtual functions. To implement a matcher for
3667 type `T` using the legacy API you have to derive from `MatcherInterface<T>` and
3668 call `MakeMatcher` to construct the object.
3670 The interface looks like this:
3673 class MatchResultListener {
3676 // Streams x to the underlying ostream; does nothing if the ostream
3678 template <typename T>
3679 MatchResultListener& operator<<(const T& x);
3681 // Returns the underlying ostream.
3682 std::ostream* stream();
3685 template <typename T>
3686 class MatcherInterface {
3688 virtual ~MatcherInterface();
3690 // Returns true if and only if the matcher matches x; also explains the match
3691 // result to 'listener'.
3692 virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0;
3694 // Describes this matcher to an ostream.
3695 virtual void DescribeTo(std::ostream* os) const = 0;
3697 // Describes the negation of this matcher to an ostream.
3698 virtual void DescribeNegationTo(std::ostream* os) const;
3702 Fortunately, most of the time you can define a polymorphic matcher easily with
3703 the help of `MakePolymorphicMatcher()`. Here's how you can define `NotNull()` as
3707 using ::testing::MakePolymorphicMatcher;
3708 using ::testing::MatchResultListener;
3709 using ::testing::PolymorphicMatcher;
3711 class NotNullMatcher {
3713 // To implement a polymorphic matcher, first define a COPYABLE class
3714 // that has three members MatchAndExplain(), DescribeTo(), and
3715 // DescribeNegationTo(), like the following.
3717 // In this example, we want to use NotNull() with any pointer, so
3718 // MatchAndExplain() accepts a pointer of any type as its first argument.
3719 // In general, you can define MatchAndExplain() as an ordinary method or
3720 // a method template, or even overload it.
3721 template <typename T>
3722 bool MatchAndExplain(T* p,
3723 MatchResultListener* /* listener */) const {
3727 // Describes the property of a value matching this matcher.
3728 void DescribeTo(std::ostream* os) const { *os << "is not NULL"; }
3730 // Describes the property of a value NOT matching this matcher.
3731 void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; }
3734 // To construct a polymorphic matcher, pass an instance of the class
3735 // to MakePolymorphicMatcher(). Note the return type.
3736 PolymorphicMatcher<NotNullMatcher> NotNull() {
3737 return MakePolymorphicMatcher(NotNullMatcher());
3742 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
3746 **Note:** Your polymorphic matcher class does **not** need to inherit from
3747 `MatcherInterface` or any other class, and its methods do **not** need to be
3750 Like in a monomorphic matcher, you may explain the match result by streaming
3751 additional information to the `listener` argument in `MatchAndExplain()`.
3753 ### Writing New Cardinalities
3755 A cardinality is used in `Times()` to tell gMock how many times you expect a
3756 call to occur. It doesn't have to be exact. For example, you can say
3757 `AtLeast(5)` or `Between(2, 4)`.
3759 If the [built-in set](gmock_cheat_sheet.md#CardinalityList) of cardinalities
3760 doesn't suit you, you are free to define your own by implementing the following
3761 interface (in namespace `testing`):
3764 class CardinalityInterface {
3766 virtual ~CardinalityInterface();
3768 // Returns true if and only if call_count calls will satisfy this cardinality.
3769 virtual bool IsSatisfiedByCallCount(int call_count) const = 0;
3771 // Returns true if and only if call_count calls will saturate this
3773 virtual bool IsSaturatedByCallCount(int call_count) const = 0;
3775 // Describes self to an ostream.
3776 virtual void DescribeTo(std::ostream* os) const = 0;
3780 For example, to specify that a call must occur even number of times, you can
3784 using ::testing::Cardinality;
3785 using ::testing::CardinalityInterface;
3786 using ::testing::MakeCardinality;
3788 class EvenNumberCardinality : public CardinalityInterface {
3790 bool IsSatisfiedByCallCount(int call_count) const override {
3791 return (call_count % 2) == 0;
3794 bool IsSaturatedByCallCount(int call_count) const override {
3798 void DescribeTo(std::ostream* os) const {
3799 *os << "called even number of times";
3803 Cardinality EvenNumber() {
3804 return MakeCardinality(new EvenNumberCardinality);
3808 EXPECT_CALL(foo, Bar(3))
3809 .Times(EvenNumber());
3812 ### Writing New Actions Quickly {#QuickNewActions}
3814 If the built-in actions don't work for you, you can easily define your own one.
3815 Just define a functor class with a (possibly templated) call operator, matching
3816 the signature of your action.
3820 template <typename T>
3821 T operator()(T* arg) {
3827 The same approach works with stateful functors (or any callable, really):
3831 template <typename T>
3832 T operator()(T arg) { return arg * multiplier; }
3838 // EXPECT_CALL(...).WillOnce(MultiplyBy{7});
3841 #### Legacy macro-based Actions
3843 Before C++11, the functor-based actions were not supported; the old way of
3844 writing actions was through a set of `ACTION*` macros. We suggest to avoid them
3845 in new code; they hide a lot of logic behind the macro, potentially leading to
3846 harder-to-understand compiler errors. Nevertheless, we cover them here for
3852 ACTION(name) { statements; }
3855 in a namespace scope (i.e. not inside a class or function), you will define an
3856 action with the given name that executes the statements. The value returned by
3857 `statements` will be used as the return value of the action. Inside the
3858 statements, you can refer to the K-th (0-based) argument of the mock function as
3859 `argK`. For example:
3862 ACTION(IncrementArg1) { return ++(*arg1); }
3868 ... WillOnce(IncrementArg1());
3871 Note that you don't need to specify the types of the mock function arguments.
3872 Rest assured that your code is type-safe though: you'll get a compiler error if
3873 `*arg1` doesn't support the `++` operator, or if the type of `++(*arg1)` isn't
3874 compatible with the mock function's return type.
3887 defines an action `Foo()` that invokes argument #2 (a function pointer) with 5,
3888 calls function `Blah()`, sets the value pointed to by argument #1 to 0, and
3889 returns argument #0.
3891 For more convenience and flexibility, you can also use the following pre-defined
3892 symbols in the body of `ACTION`:
3894 `argK_type` | The type of the K-th (0-based) argument of the mock function
3895 :-------------- | :-----------------------------------------------------------
3896 `args` | All arguments of the mock function as a tuple
3897 `args_type` | The type of all arguments of the mock function as a tuple
3898 `return_type` | The return type of the mock function
3899 `function_type` | The type of the mock function
3901 For example, when using an `ACTION` as a stub action for mock function:
3904 int DoSomething(bool flag, int* ptr);
3909 Pre-defined Symbol | Is Bound To
3910 ------------------ | ---------------------------------
3911 `arg0` | the value of `flag`
3912 `arg0_type` | the type `bool`
3913 `arg1` | the value of `ptr`
3914 `arg1_type` | the type `int*`
3915 `args` | the tuple `(flag, ptr)`
3916 `args_type` | the type `std::tuple<bool, int*>`
3917 `return_type` | the type `int`
3918 `function_type` | the type `int(bool, int*)`
3920 #### Legacy macro-based parameterized Actions
3922 Sometimes you'll want to parameterize an action you define. For that we have
3926 ACTION_P(name, param) { statements; }
3932 ACTION_P(Add, n) { return arg0 + n; }
3935 will allow you to write
3938 // Returns argument #0 + 5.
3939 ... WillOnce(Add(5));
3942 For convenience, we use the term *arguments* for the values used to invoke the
3943 mock function, and the term *parameters* for the values used to instantiate an
3946 Note that you don't need to provide the type of the parameter either. Suppose
3947 the parameter is named `param`, you can also use the gMock-defined symbol
3948 `param_type` to refer to the type of the parameter as inferred by the compiler.
3949 For example, in the body of `ACTION_P(Add, n)` above, you can write `n_type` for
3952 gMock also provides `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter
3953 actions. For example,
3956 ACTION_P2(ReturnDistanceTo, x, y) {
3957 double dx = arg0 - x;
3958 double dy = arg1 - y;
3959 return sqrt(dx*dx + dy*dy);
3966 ... WillOnce(ReturnDistanceTo(5.0, 26.5));
3969 You can view `ACTION` as a degenerated parameterized action where the number of
3972 You can also easily define actions overloaded on the number of parameters:
3975 ACTION_P(Plus, a) { ... }
3976 ACTION_P2(Plus, a, b) { ... }
3979 ### Restricting the Type of an Argument or Parameter in an ACTION
3981 For maximum brevity and reusability, the `ACTION*` macros don't ask you to
3982 provide the types of the mock function arguments and the action parameters.
3983 Instead, we let the compiler infer the types for us.
3985 Sometimes, however, we may want to be more explicit about the types. There are
3986 several tricks to do that. For example:
3990 // Makes sure arg0 can be converted to int.
3992 ... use n instead of arg0 here ...
3995 ACTION_P(Bar, param) {
3996 // Makes sure the type of arg1 is const char*.
3997 ::testing::StaticAssertTypeEq<const char*, arg1_type>();
3999 // Makes sure param can be converted to bool.
4004 where `StaticAssertTypeEq` is a compile-time assertion in googletest that
4005 verifies two types are the same.
4007 ### Writing New Action Templates Quickly
4009 Sometimes you want to give an action explicit template parameters that cannot be
4010 inferred from its value parameters. `ACTION_TEMPLATE()` supports that and can be
4011 viewed as an extension to `ACTION()` and `ACTION_P*()`.
4016 ACTION_TEMPLATE(ActionName,
4017 HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m),
4018 AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; }
4021 defines an action template that takes *m* explicit template parameters and *n*
4022 value parameters, where *m* is in [1, 10] and *n* is in [0, 10]. `name_i` is the
4023 name of the *i*-th template parameter, and `kind_i` specifies whether it's a
4024 `typename`, an integral constant, or a template. `p_i` is the name of the *i*-th
4030 // DuplicateArg<k, T>(output) converts the k-th argument of the mock
4031 // function to type T and copies it to *output.
4032 ACTION_TEMPLATE(DuplicateArg,
4033 // Note the comma between int and k:
4034 HAS_2_TEMPLATE_PARAMS(int, k, typename, T),
4035 AND_1_VALUE_PARAMS(output)) {
4036 *output = T(std::get<k>(args));
4040 To create an instance of an action template, write:
4043 ActionName<t1, ..., t_m>(v1, ..., v_n)
4046 where the `t`s are the template arguments and the `v`s are the value arguments.
4047 The value argument types are inferred by the compiler. For example:
4053 EXPECT_CALL(mock, Foo).WillOnce(DuplicateArg<1, unsigned char>(&n));
4056 If you want to explicitly specify the value argument types, you can provide
4057 additional template arguments:
4060 ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n)
4063 where `u_i` is the desired type of `v_i`.
4065 `ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the number of
4066 value parameters, but not on the number of template parameters. Without the
4067 restriction, the meaning of the following is unclear:
4070 OverloadedAction<int, bool>(x);
4073 Are we using a single-template-parameter action where `bool` refers to the type
4074 of `x`, or a two-template-parameter action where the compiler is asked to infer
4077 ### Using the ACTION Object's Type
4079 If you are writing a function that returns an `ACTION` object, you'll need to
4080 know its type. The type depends on the macro used to define the action and the
4081 parameter types. The rule is relatively simple:
4084 | Given Definition | Expression | Has Type |
4085 | ----------------------------- | ------------------- | --------------------- |
4086 | `ACTION(Foo)` | `Foo()` | `FooAction` |
4087 | `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` |
4088 | `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` |
4089 | `ACTION_TEMPLATE(Bar, HAS_m_TEMPLATE_PARAMS(...), AND_1_VALUE_PARAMS(p1))` | `Bar<t1, ..., t_m>(int_value)` | `BarActionP<t1, ..., t_m, int>` |
4090 | `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` |
4091 | `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>` |
4095 Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`,
4096 and etc) for actions with different numbers of value parameters, or the action
4097 definitions cannot be overloaded on the number of them.
4099 ### Writing New Monomorphic Actions {#NewMonoActions}
4101 While the `ACTION*` macros are very convenient, sometimes they are
4102 inappropriate. For example, despite the tricks shown in the previous recipes,
4103 they don't let you directly specify the types of the mock function arguments and
4104 the action parameters, which in general leads to unoptimized compiler error
4105 messages that can baffle unfamiliar users. They also don't allow overloading
4106 actions based on parameter types without jumping through some hoops.
4108 An alternative to the `ACTION*` macros is to implement
4109 `::testing::ActionInterface<F>`, where `F` is the type of the mock function in
4110 which the action will be used. For example:
4113 template <typename F>
4114 class ActionInterface {
4116 virtual ~ActionInterface();
4118 // Performs the action. Result is the return type of function type
4119 // F, and ArgumentTuple is the tuple of arguments of F.
4122 // For example, if F is int(bool, const string&), then Result would
4123 // be int, and ArgumentTuple would be std::tuple<bool, const string&>.
4124 virtual Result Perform(const ArgumentTuple& args) = 0;
4130 using ::testing::Action;
4131 using ::testing::ActionInterface;
4132 using ::testing::MakeAction;
4134 typedef int IncrementMethod(int*);
4136 class IncrementArgumentAction : public ActionInterface<IncrementMethod> {
4138 int Perform(const std::tuple<int*>& args) override {
4139 int* p = std::get<0>(args); // Grabs the first argument.
4144 Action<IncrementMethod> IncrementArgument() {
4145 return MakeAction(new IncrementArgumentAction);
4149 EXPECT_CALL(foo, Baz(_))
4150 .WillOnce(IncrementArgument());
4153 foo.Baz(&n); // Should return 5 and change n to 6.
4156 ### Writing New Polymorphic Actions {#NewPolyActions}
4158 The previous recipe showed you how to define your own action. This is all good,
4159 except that you need to know the type of the function in which the action will
4160 be used. Sometimes that can be a problem. For example, if you want to use the
4161 action in functions with *different* types (e.g. like `Return()` and
4164 If an action can be used in several types of mock functions, we say it's
4165 *polymorphic*. The `MakePolymorphicAction()` function template makes it easy to
4166 define such an action:
4170 template <typename Impl>
4171 PolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl);
4172 } // namespace testing
4175 As an example, let's define an action that returns the second argument in the
4176 mock function's argument list. The first step is to define an implementation
4180 class ReturnSecondArgumentAction {
4182 template <typename Result, typename ArgumentTuple>
4183 Result Perform(const ArgumentTuple& args) const {
4184 // To get the i-th (0-based) argument, use std::get(args).
4185 return std::get<1>(args);
4190 This implementation class does *not* need to inherit from any particular class.
4191 What matters is that it must have a `Perform()` method template. This method
4192 template takes the mock function's arguments as a tuple in a **single**
4193 argument, and returns the result of the action. It can be either `const` or not,
4194 but must be invokable with exactly one template argument, which is the result
4195 type. In other words, you must be able to call `Perform<R>(args)` where `R` is
4196 the mock function's return type and `args` is its arguments in a tuple.
4198 Next, we use `MakePolymorphicAction()` to turn an instance of the implementation
4199 class into the polymorphic action we need. It will be convenient to have a
4203 using ::testing::MakePolymorphicAction;
4204 using ::testing::PolymorphicAction;
4206 PolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() {
4207 return MakePolymorphicAction(ReturnSecondArgumentAction());
4211 Now, you can use this polymorphic action the same way you use the built-in ones:
4216 class MockFoo : public Foo {
4218 MOCK_METHOD(int, DoThis, (bool flag, int n), (override));
4219 MOCK_METHOD(string, DoThat, (int x, const char* str1, const char* str2),
4225 EXPECT_CALL(foo, DoThis).WillOnce(ReturnSecondArgument());
4226 EXPECT_CALL(foo, DoThat).WillOnce(ReturnSecondArgument());
4228 foo.DoThis(true, 5); // Will return 5.
4229 foo.DoThat(1, "Hi", "Bye"); // Will return "Hi".
4232 ### Teaching gMock How to Print Your Values
4234 When an uninteresting or unexpected call occurs, gMock prints the argument
4235 values and the stack trace to help you debug. Assertion macros like
4236 `EXPECT_THAT` and `EXPECT_EQ` also print the values in question when the
4237 assertion fails. gMock and googletest do this using googletest's user-extensible
4240 This printer knows how to print built-in C++ types, native arrays, STL
4241 containers, and any type that supports the `<<` operator. For other types, it
4242 prints the raw bytes in the value and hopes that you the user can figure it out.
4243 [The GoogleTest advanced guide](advanced.md#teaching-googletest-how-to-print-your-values)
4244 explains how to extend the printer to do a better job at printing your
4245 particular type than to dump the bytes.
4247 ## Useful Mocks Created Using gMock
4249 <!--#include file="includes/g3_testing_LOGs.md"-->
4250 <!--#include file="includes/g3_mock_callbacks.md"-->
4252 ### Mock std::function {#MockFunction}
4254 `std::function` is a general function type introduced in C++11. It is a
4255 preferred way of passing callbacks to new interfaces. Functions are copiable,
4256 and are not usually passed around by pointer, which makes them tricky to mock.
4257 But fear not - `MockFunction` can help you with that.
4259 `MockFunction<R(T1, ..., Tn)>` has a mock method `Call()` with the signature:
4262 R Call(T1, ..., Tn);
4265 It also has a `AsStdFunction()` method, which creates a `std::function` proxy
4269 std::function<R(T1, ..., Tn)> AsStdFunction();
4272 To use `MockFunction`, first create `MockFunction` object and set up
4273 expectations on its `Call` method. Then pass proxy obtained from
4274 `AsStdFunction()` to the code you are testing. For example:
4277 TEST(FooTest, RunsCallbackWithBarArgument) {
4278 // 1. Create a mock object.
4279 MockFunction<int(string)> mock_function;
4281 // 2. Set expectations on Call() method.
4282 EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1));
4284 // 3. Exercise code that uses std::function.
4285 Foo(mock_function.AsStdFunction());
4286 // Foo's signature can be either of:
4287 // void Foo(const std::function<int(string)>& fun);
4288 // void Foo(std::function<int(string)> fun);
4290 // 4. All expectations will be verified when mock_function
4291 // goes out of scope and is destroyed.
4295 Remember that function objects created with `AsStdFunction()` are just
4296 forwarders. If you create multiple of them, they will share the same set of
4299 Although `std::function` supports unlimited number of arguments, `MockFunction`
4300 implementation is limited to ten. If you ever hit that limit... well, your
4301 callback has bigger problems than being mockable. :-)