3 You can find recipes for using Google Mock here. If you haven't yet,
4 please read the [ForDummies](V1_7_ForDummies.md) document first to make sure you understand
7 **Note:** Google Mock lives in the `testing` name space. For
8 readability, it is recommended to write `using ::testing::Foo;` once in
9 your file before using the name `Foo` defined by Google Mock. We omit
10 such `using` statements in this page for brevity, but you should do it
13 # Creating Mock Classes #
15 ## Mocking Private or Protected Methods ##
17 You must always put a mock method definition (`MOCK_METHOD*`) in a
18 `public:` section of the mock class, regardless of the method being
19 mocked being `public`, `protected`, or `private` in the base class.
20 This allows `ON_CALL` and `EXPECT_CALL` to reference the mock function
21 from outside of the mock class. (Yes, C++ allows a subclass to change
22 the access level of a virtual function in the base class.) Example:
28 virtual bool Transform(Gadget* g) = 0;
31 virtual void Resume();
34 virtual int GetTimeOut();
37 class MockFoo : public Foo {
40 MOCK_METHOD1(Transform, bool(Gadget* g));
42 // The following must be in the public section, even though the
43 // methods are protected or private in the base class.
44 MOCK_METHOD0(Resume, void());
45 MOCK_METHOD0(GetTimeOut, int());
49 ## Mocking Overloaded Methods ##
51 You can mock overloaded functions as usual. No special attention is required:
57 // Must be virtual as we'll inherit from Foo.
60 // Overloaded on the types and/or numbers of arguments.
61 virtual int Add(Element x);
62 virtual int Add(int times, Element x);
64 // Overloaded on the const-ness of this object.
65 virtual Bar& GetBar();
66 virtual const Bar& GetBar() const;
69 class MockFoo : public Foo {
71 MOCK_METHOD1(Add, int(Element x));
72 MOCK_METHOD2(Add, int(int times, Element x);
74 MOCK_METHOD0(GetBar, Bar&());
75 MOCK_CONST_METHOD0(GetBar, const Bar&());
79 **Note:** if you don't mock all versions of the overloaded method, the
80 compiler will give you a warning about some methods in the base class
81 being hidden. To fix that, use `using` to bring them in scope:
84 class MockFoo : public Foo {
87 MOCK_METHOD1(Add, int(Element x));
88 // We don't want to mock int Add(int times, Element x);
93 ## Mocking Class Templates ##
95 To mock a class template, append `_T` to the `MOCK_*` macros:
98 template <typename Elem>
99 class StackInterface {
101 // Must be virtual as we'll inherit from StackInterface.
102 virtual ~StackInterface();
104 virtual int GetSize() const = 0;
105 virtual void Push(const Elem& x) = 0;
108 template <typename Elem>
109 class MockStack : public StackInterface<Elem> {
111 MOCK_CONST_METHOD0_T(GetSize, int());
112 MOCK_METHOD1_T(Push, void(const Elem& x));
116 ## Mocking Nonvirtual Methods ##
118 Google Mock can mock non-virtual functions to be used in what we call _hi-perf
119 dependency injection_.
121 In this case, instead of sharing a common base class with the real
122 class, your mock class will be _unrelated_ to the real class, but
123 contain methods with the same signatures. The syntax for mocking
124 non-virtual methods is the _same_ as mocking virtual methods:
127 // A simple packet stream class. None of its members is virtual.
128 class ConcretePacketStream {
130 void AppendPacket(Packet* new_packet);
131 const Packet* GetPacket(size_t packet_number) const;
132 size_t NumberOfPackets() const;
136 // A mock packet stream class. It inherits from no other, but defines
137 // GetPacket() and NumberOfPackets().
138 class MockPacketStream {
140 MOCK_CONST_METHOD1(GetPacket, const Packet*(size_t packet_number));
141 MOCK_CONST_METHOD0(NumberOfPackets, size_t());
146 Note that the mock class doesn't define `AppendPacket()`, unlike the
147 real class. That's fine as long as the test doesn't need to call it.
149 Next, you need a way to say that you want to use
150 `ConcretePacketStream` in production code, and use `MockPacketStream`
151 in tests. Since the functions are not virtual and the two classes are
152 unrelated, you must specify your choice at _compile time_ (as opposed
155 One way to do it is to templatize your code that needs to use a packet
156 stream. More specifically, you will give your code a template type
157 argument for the type of the packet stream. In production, you will
158 instantiate your template with `ConcretePacketStream` as the type
159 argument. In tests, you will instantiate the same template with
160 `MockPacketStream`. For example, you may write:
163 template <class PacketStream>
164 void CreateConnection(PacketStream* stream) { ... }
166 template <class PacketStream>
169 void ReadPackets(PacketStream* stream, size_t packet_num);
173 Then you can use `CreateConnection<ConcretePacketStream>()` and
174 `PacketReader<ConcretePacketStream>` in production code, and use
175 `CreateConnection<MockPacketStream>()` and
176 `PacketReader<MockPacketStream>` in tests.
179 MockPacketStream mock_stream;
180 EXPECT_CALL(mock_stream, ...)...;
181 .. set more expectations on mock_stream ...
182 PacketReader<MockPacketStream> reader(&mock_stream);
183 ... exercise reader ...
186 ## Mocking Free Functions ##
188 It's possible to use Google Mock to mock a free function (i.e. a
189 C-style function or a static method). You just need to rewrite your
190 code to use an interface (abstract class).
192 Instead of calling a free function (say, `OpenFile`) directly,
193 introduce an interface for it and have a concrete subclass that calls
197 class FileInterface {
200 virtual bool Open(const char* path, const char* mode) = 0;
203 class File : public FileInterface {
206 virtual bool Open(const char* path, const char* mode) {
207 return OpenFile(path, mode);
212 Your code should talk to `FileInterface` to open a file. Now it's
213 easy to mock out the function.
215 This may seem much hassle, but in practice you often have multiple
216 related functions that you can put in the same interface, so the
217 per-function syntactic overhead will be much lower.
219 If you are concerned about the performance overhead incurred by
220 virtual functions, and profiling confirms your concern, you can
221 combine this with the recipe for [mocking non-virtual methods](#Mocking_Nonvirtual_Methods.md).
223 ## The Nice, the Strict, and the Naggy ##
225 If a mock method has no `EXPECT_CALL` spec but is called, Google Mock
226 will print a warning about the "uninteresting call". The rationale is:
228 * New methods may be added to an interface after a test is written. We shouldn't fail a test just because a method it doesn't know about is called.
229 * However, this may also mean there's a bug in the test, so Google Mock shouldn't be silent either. If the user believes these calls are harmless, he can add an `EXPECT_CALL()` to suppress the warning.
231 However, sometimes you may want to suppress all "uninteresting call"
232 warnings, while sometimes you may want the opposite, i.e. to treat all
233 of them as errors. Google Mock lets you make the decision on a
234 per-mock-object basis.
236 Suppose your test uses a mock class `MockFoo`:
241 EXPECT_CALL(mock_foo, DoThis());
242 ... code that uses mock_foo ...
246 If a method of `mock_foo` other than `DoThis()` is called, it will be
247 reported by Google Mock as a warning. However, if you rewrite your
248 test to use `NiceMock<MockFoo>` instead, the warning will be gone,
249 resulting in a cleaner test output:
252 using ::testing::NiceMock;
255 NiceMock<MockFoo> mock_foo;
256 EXPECT_CALL(mock_foo, DoThis());
257 ... code that uses mock_foo ...
261 `NiceMock<MockFoo>` is a subclass of `MockFoo`, so it can be used
262 wherever `MockFoo` is accepted.
264 It also works if `MockFoo`'s constructor takes some arguments, as
265 `NiceMock<MockFoo>` "inherits" `MockFoo`'s constructors:
268 using ::testing::NiceMock;
271 NiceMock<MockFoo> mock_foo(5, "hi"); // Calls MockFoo(5, "hi").
272 EXPECT_CALL(mock_foo, DoThis());
273 ... code that uses mock_foo ...
277 The usage of `StrictMock` is similar, except that it makes all
278 uninteresting calls failures:
281 using ::testing::StrictMock;
284 StrictMock<MockFoo> mock_foo;
285 EXPECT_CALL(mock_foo, DoThis());
286 ... code that uses mock_foo ...
288 // The test will fail if a method of mock_foo other than DoThis()
293 There are some caveats though (I don't like them just as much as the
294 next guy, but sadly they are side effects of C++'s limitations):
296 1. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` only work for mock methods defined using the `MOCK_METHOD*` family of macros **directly** in the `MockFoo` class. If a mock method is defined in a **base class** of `MockFoo`, the "nice" or "strict" modifier may not affect it, depending on the compiler. In particular, nesting `NiceMock` and `StrictMock` (e.g. `NiceMock<StrictMock<MockFoo> >`) is **not** supported.
297 1. The constructors of the base mock (`MockFoo`) cannot have arguments passed by non-const reference, which happens to be banned by the [Google C++ style guide](http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml).
298 1. During the constructor or destructor of `MockFoo`, the mock object is _not_ nice or strict. This may cause surprises if the constructor or destructor calls a mock method on `this` object. (This behavior, however, is consistent with C++'s general rule: if a constructor or destructor calls a virtual method of `this` object, that method is treated as non-virtual. In other words, to the base class's constructor or destructor, `this` object behaves like an instance of the base class, not the derived class. This rule is required for safety. Otherwise a base constructor may use members of a derived class before they are initialized, or a base destructor may use members of a derived class after they have been destroyed.)
300 Finally, you should be **very cautious** about when to use naggy or strict mocks, as they tend to make tests more brittle and harder to maintain. When you refactor your code without changing its externally visible behavior, ideally you should't need to update any tests. If your code interacts with a naggy mock, however, you may start to get spammed with warnings as the result of your change. Worse, if your code interacts with a strict mock, your tests may start to fail and you'll be forced to fix them. Our general recommendation is to use nice mocks (not yet the default) most of the time, use naggy mocks (the current default) when developing or debugging tests, and use strict mocks only as the last resort.
302 ## Simplifying the Interface without Breaking Existing Code ##
304 Sometimes a method has a long list of arguments that is mostly
305 uninteresting. For example,
311 virtual void send(LogSeverity severity, const char* full_filename,
312 const char* base_filename, int line,
313 const struct tm* tm_time,
314 const char* message, size_t message_len) = 0;
318 This method's argument list is lengthy and hard to work with (let's
319 say that the `message` argument is not even 0-terminated). If we mock
320 it as is, using the mock will be awkward. If, however, we try to
321 simplify this interface, we'll need to fix all clients depending on
322 it, which is often infeasible.
324 The trick is to re-dispatch the method in the mock class:
327 class ScopedMockLog : public LogSink {
330 virtual void send(LogSeverity severity, const char* full_filename,
331 const char* base_filename, int line, const tm* tm_time,
332 const char* message, size_t message_len) {
333 // We are only interested in the log severity, full file name, and
335 Log(severity, full_filename, std::string(message, message_len));
338 // Implements the mock method:
340 // void Log(LogSeverity severity,
341 // const string& file_path,
342 // const string& message);
343 MOCK_METHOD3(Log, void(LogSeverity severity, const string& file_path,
344 const string& message));
348 By defining a new mock method with a trimmed argument list, we make
349 the mock class much more user-friendly.
351 ## Alternative to Mocking Concrete Classes ##
353 Often you may find yourself using classes that don't implement
354 interfaces. In order to test your code that uses such a class (let's
355 call it `Concrete`), you may be tempted to make the methods of
356 `Concrete` virtual and then mock it.
360 Making a non-virtual function virtual is a big decision. It creates an
361 extension point where subclasses can tweak your class' behavior. This
362 weakens your control on the class because now it's harder to maintain
363 the class' invariants. You should make a function virtual only when
364 there is a valid reason for a subclass to override it.
366 Mocking concrete classes directly is problematic as it creates a tight
367 coupling between the class and the tests - any small change in the
368 class may invalidate your tests and make test maintenance a pain.
370 To avoid such problems, many programmers have been practicing "coding
371 to interfaces": instead of talking to the `Concrete` class, your code
372 would define an interface and talk to it. Then you implement that
373 interface as an adaptor on top of `Concrete`. In tests, you can easily
374 mock that interface to observe how your code is doing.
376 This technique incurs some overhead:
378 * You pay the cost of virtual function calls (usually not a problem).
379 * There is more abstraction for the programmers to learn.
381 However, it can also bring significant benefits in addition to better
384 * `Concrete`'s API may not fit your problem domain very well, as you may not be the only client it tries to serve. By designing your own interface, you have a chance to tailor it to your need - you may add higher-level functionalities, rename stuff, etc instead of just trimming the class. This allows you to write your code (user of the interface) in a more natural way, which means it will be more readable, more maintainable, and you'll be more productive.
385 * If `Concrete`'s implementation ever has to change, you don't have to rewrite everywhere it is used. Instead, you can absorb the change in your implementation of the interface, and your other code and tests will be insulated from this change.
387 Some people worry that if everyone is practicing this technique, they
388 will end up writing lots of redundant code. This concern is totally
389 understandable. However, there are two reasons why it may not be the
392 * Different projects may need to use `Concrete` in different ways, so the best interfaces for them will be different. Therefore, each of them will have its own domain-specific interface on top of `Concrete`, and they will not be the same code.
393 * If enough projects want to use the same interface, they can always share it, just like they have been sharing `Concrete`. You can check in the interface and the adaptor somewhere near `Concrete` (perhaps in a `contrib` sub-directory) and let many projects use it.
395 You need to weigh the pros and cons carefully for your particular
396 problem, but I'd like to assure you that the Java community has been
397 practicing this for a long time and it's a proven effective technique
398 applicable in a wide variety of situations. :-)
400 ## Delegating Calls to a Fake ##
402 Some times you have a non-trivial fake implementation of an
403 interface. For example:
409 virtual char DoThis(int n) = 0;
410 virtual void DoThat(const char* s, int* p) = 0;
413 class FakeFoo : public Foo {
415 virtual char DoThis(int n) {
416 return (n > 0) ? '+' :
420 virtual void DoThat(const char* s, int* p) {
426 Now you want to mock this interface such that you can set expectations
427 on it. However, you also want to use `FakeFoo` for the default
428 behavior, as duplicating it in the mock object is, well, a lot of
431 When you define the mock class using Google Mock, you can have it
432 delegate its default action to a fake class you already have, using
437 using ::testing::Invoke;
439 class MockFoo : public Foo {
441 // Normal mock method definitions using Google Mock.
442 MOCK_METHOD1(DoThis, char(int n));
443 MOCK_METHOD2(DoThat, void(const char* s, int* p));
445 // Delegates the default actions of the methods to a FakeFoo object.
446 // This must be called *before* the custom ON_CALL() statements.
447 void DelegateToFake() {
448 ON_CALL(*this, DoThis(_))
449 .WillByDefault(Invoke(&fake_, &FakeFoo::DoThis));
450 ON_CALL(*this, DoThat(_, _))
451 .WillByDefault(Invoke(&fake_, &FakeFoo::DoThat));
454 FakeFoo fake_; // Keeps an instance of the fake in the mock.
458 With that, you can use `MockFoo` in your tests as usual. Just remember
459 that if you don't explicitly set an action in an `ON_CALL()` or
460 `EXPECT_CALL()`, the fake will be called upon to do it:
467 foo.DelegateToFake(); // Enables the fake for delegation.
469 // Put your ON_CALL(foo, ...)s here, if any.
471 // No action specified, meaning to use the default action.
472 EXPECT_CALL(foo, DoThis(5));
473 EXPECT_CALL(foo, DoThat(_, _));
476 EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked.
477 foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked.
484 * If you want, you can still override the default action by providing your own `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`.
485 * In `DelegateToFake()`, you only need to delegate the methods whose fake implementation you intend to use.
486 * The general technique discussed here works for overloaded methods, but you'll need to tell the compiler which version you mean. To disambiguate a mock function (the one you specify inside the parentheses of `ON_CALL()`), see the "Selecting Between Overloaded Functions" section on this page; to disambiguate a fake function (the one you place inside `Invoke()`), use a `static_cast` to specify the function's type. For instance, if class `Foo` has methods `char DoThis(int n)` and `bool DoThis(double x) const`, and you want to invoke the latter, you need to write `Invoke(&fake_, static_cast<bool (FakeFoo::*)(double) const>(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)` (The strange-looking thing inside the angled brackets of `static_cast` is the type of a function pointer to the second `DoThis()` method.).
487 * Having to mix a mock and a fake is often a sign of something gone wrong. Perhaps you haven't got used to the interaction-based way of testing yet. Or perhaps your interface is taking on too many roles and should be split up. Therefore, **don't abuse this**. We would only recommend to do it as an intermediate step when you are refactoring your code.
489 Regarding the tip on mixing a mock and a fake, here's an example on
490 why it may be a bad sign: Suppose you have a class `System` for
491 low-level system operations. In particular, it does file and I/O
492 operations. And suppose you want to test how your code uses `System`
493 to do I/O, and you just want the file operations to work normally. If
494 you mock out the entire `System` class, you'll have to provide a fake
495 implementation for the file operation part, which suggests that
496 `System` is taking on too many roles.
498 Instead, you can define a `FileOps` interface and an `IOOps` interface
499 and split `System`'s functionalities into the two. Then you can mock
500 `IOOps` without mocking `FileOps`.
502 ## Delegating Calls to a Real Object ##
504 When using testing doubles (mocks, fakes, stubs, and etc), sometimes
505 their behaviors will differ from those of the real objects. This
506 difference could be either intentional (as in simulating an error such
507 that you can test the error handling code) or unintentional. If your
508 mocks have different behaviors than the real objects by mistake, you
509 could end up with code that passes the tests but fails in production.
511 You can use the _delegating-to-real_ technique to ensure that your
512 mock has the same behavior as the real object while retaining the
513 ability to validate calls. This technique is very similar to the
514 delegating-to-fake technique, the difference being that we use a real
515 object instead of a fake. Here's an example:
519 using ::testing::AtLeast;
520 using ::testing::Invoke;
522 class MockFoo : public Foo {
525 // By default, all calls are delegated to the real object.
526 ON_CALL(*this, DoThis())
527 .WillByDefault(Invoke(&real_, &Foo::DoThis));
528 ON_CALL(*this, DoThat(_))
529 .WillByDefault(Invoke(&real_, &Foo::DoThat));
532 MOCK_METHOD0(DoThis, ...);
533 MOCK_METHOD1(DoThat, ...);
542 EXPECT_CALL(mock, DoThis())
544 EXPECT_CALL(mock, DoThat("Hi"))
546 ... use mock in test ...
549 With this, Google Mock will verify that your code made the right calls
550 (with the right arguments, in the right order, called the right number
551 of times, etc), and a real object will answer the calls (so the
552 behavior will be the same as in production). This gives you the best
555 ## Delegating Calls to a Parent Class ##
557 Ideally, you should code to interfaces, whose methods are all pure
558 virtual. In reality, sometimes you do need to mock a virtual method
559 that is not pure (i.e, it already has an implementation). For example:
566 virtual void Pure(int n) = 0;
567 virtual int Concrete(const char* str) { ... }
570 class MockFoo : public Foo {
572 // Mocking a pure method.
573 MOCK_METHOD1(Pure, void(int n));
574 // Mocking a concrete method. Foo::Concrete() is shadowed.
575 MOCK_METHOD1(Concrete, int(const char* str));
579 Sometimes you may want to call `Foo::Concrete()` instead of
580 `MockFoo::Concrete()`. Perhaps you want to do it as part of a stub
581 action, or perhaps your test doesn't need to mock `Concrete()` at all
582 (but it would be oh-so painful to have to define a new mock class
583 whenever you don't need to mock one of its methods).
585 The trick is to leave a back door in your mock class for accessing the
586 real methods in the base class:
589 class MockFoo : public Foo {
591 // Mocking a pure method.
592 MOCK_METHOD1(Pure, void(int n));
593 // Mocking a concrete method. Foo::Concrete() is shadowed.
594 MOCK_METHOD1(Concrete, int(const char* str));
596 // Use this to call Concrete() defined in Foo.
597 int FooConcrete(const char* str) { return Foo::Concrete(str); }
601 Now, you can call `Foo::Concrete()` inside an action by:
605 using ::testing::Invoke;
607 EXPECT_CALL(foo, Concrete(_))
608 .WillOnce(Invoke(&foo, &MockFoo::FooConcrete));
611 or tell the mock object that you don't want to mock `Concrete()`:
614 using ::testing::Invoke;
616 ON_CALL(foo, Concrete(_))
617 .WillByDefault(Invoke(&foo, &MockFoo::FooConcrete));
620 (Why don't we just write `Invoke(&foo, &Foo::Concrete)`? If you do
621 that, `MockFoo::Concrete()` will be called (and cause an infinite
622 recursion) since `Foo::Concrete()` is virtual. That's just how C++
627 ## Matching Argument Values Exactly ##
629 You can specify exactly which arguments a mock method is expecting:
632 using ::testing::Return;
634 EXPECT_CALL(foo, DoThis(5))
635 .WillOnce(Return('a'));
636 EXPECT_CALL(foo, DoThat("Hello", bar));
639 ## Using Simple Matchers ##
641 You can use matchers to match arguments that have a certain property:
645 using ::testing::NotNull;
646 using ::testing::Return;
648 EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5.
649 .WillOnce(Return('a'));
650 EXPECT_CALL(foo, DoThat("Hello", NotNull()));
651 // The second argument must not be NULL.
654 A frequently used matcher is `_`, which matches anything:
658 using ::testing::NotNull;
660 EXPECT_CALL(foo, DoThat(_, NotNull()));
663 ## Combining Matchers ##
665 You can build complex matchers from existing ones using `AllOf()`,
666 `AnyOf()`, and `Not()`:
669 using ::testing::AllOf;
671 using ::testing::HasSubstr;
673 using ::testing::Not;
675 // The argument must be > 5 and != 10.
676 EXPECT_CALL(foo, DoThis(AllOf(Gt(5),
679 // The first argument must not contain sub-string "blah".
680 EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")),
684 ## Casting Matchers ##
686 Google Mock matchers are statically typed, meaning that the compiler
687 can catch your mistake if you use a matcher of the wrong type (for
688 example, if you use `Eq(5)` to match a `string` argument). Good for
691 Sometimes, however, you know what you're doing and want the compiler
692 to give you some slack. One example is that you have a matcher for
693 `long` and the argument you want to match is `int`. While the two
694 types aren't exactly the same, there is nothing really wrong with
695 using a `Matcher<long>` to match an `int` - after all, we can first
696 convert the `int` argument to a `long` before giving it to the
699 To support this need, Google Mock gives you the
700 `SafeMatcherCast<T>(m)` function. It casts a matcher `m` to type
701 `Matcher<T>`. To ensure safety, Google Mock checks that (let `U` be the
704 1. Type `T` can be implicitly cast to type `U`;
705 1. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and floating-point numbers), the conversion from `T` to `U` is not lossy (in other words, any value representable by `T` can also be represented by `U`); and
706 1. When `U` is a reference, `T` must also be a reference (as the underlying matcher may be interested in the address of the `U` value).
708 The code won't compile if any of these conditions isn't met.
713 using ::testing::SafeMatcherCast;
715 // A base class and a child class.
717 class Derived : public Base { ... };
719 class MockFoo : public Foo {
721 MOCK_METHOD1(DoThis, void(Derived* derived));
726 // m is a Matcher<Base*> we got from somewhere.
727 EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m)));
730 If you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar
731 function `MatcherCast<T>(m)`. The difference is that `MatcherCast` works
732 as long as you can `static_cast` type `T` to type `U`.
734 `MatcherCast` essentially lets you bypass C++'s type system
735 (`static_cast` isn't always safe as it could throw away information,
736 for example), so be careful not to misuse/abuse it.
738 ## Selecting Between Overloaded Functions ##
740 If you expect an overloaded function to be called, the compiler may
741 need some help on which overloaded version it is.
743 To disambiguate functions overloaded on the const-ness of this object,
744 use the `Const()` argument wrapper.
747 using ::testing::ReturnRef;
749 class MockFoo : public Foo {
751 MOCK_METHOD0(GetBar, Bar&());
752 MOCK_CONST_METHOD0(GetBar, const Bar&());
758 EXPECT_CALL(foo, GetBar()) // The non-const GetBar().
759 .WillOnce(ReturnRef(bar1));
760 EXPECT_CALL(Const(foo), GetBar()) // The const GetBar().
761 .WillOnce(ReturnRef(bar2));
764 (`Const()` is defined by Google Mock and returns a `const` reference
767 To disambiguate overloaded functions with the same number of arguments
768 but different argument types, you may need to specify the exact type
769 of a matcher, either by wrapping your matcher in `Matcher<type>()`, or
770 using a matcher whose type is fixed (`TypedEq<type>`, `An<type>()`,
776 using ::testing::Matcher;
777 using ::testing::TypedEq;
779 class MockPrinter : public Printer {
781 MOCK_METHOD1(Print, void(int n));
782 MOCK_METHOD1(Print, void(char c));
785 TEST(PrinterTest, Print) {
788 EXPECT_CALL(printer, Print(An<int>())); // void Print(int);
789 EXPECT_CALL(printer, Print(Matcher<int>(Lt(5)))); // void Print(int);
790 EXPECT_CALL(printer, Print(TypedEq<char>('a'))); // void Print(char);
798 ## Performing Different Actions Based on the Arguments ##
800 When a mock method is called, the _last_ matching expectation that's
801 still active will be selected (think "newer overrides older"). So, you
802 can make a method do different things depending on its argument values
808 using ::testing::Return;
811 EXPECT_CALL(foo, DoThis(_))
812 .WillRepeatedly(Return('b'));
814 // The more specific case.
815 EXPECT_CALL(foo, DoThis(Lt(5)))
816 .WillRepeatedly(Return('a'));
819 Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will
820 be returned; otherwise `'b'` will be returned.
822 ## Matching Multiple Arguments as a Whole ##
824 Sometimes it's not enough to match the arguments individually. For
825 example, we may want to say that the first argument must be less than
826 the second argument. The `With()` clause allows us to match
827 all arguments of a mock function as a whole. For example,
834 EXPECT_CALL(foo, InRange(Ne(0), _))
838 says that the first argument of `InRange()` must not be 0, and must be
839 less than the second argument.
841 The expression inside `With()` must be a matcher of type
842 `Matcher<tr1::tuple<A1, ..., An> >`, where `A1`, ..., `An` are the
843 types of the function arguments.
845 You can also write `AllArgs(m)` instead of `m` inside `.With()`. The
846 two forms are equivalent, but `.With(AllArgs(Lt()))` is more readable
849 You can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments
850 (as a tuple) against `m`. For example,
854 using ::testing::AllOf;
855 using ::testing::Args;
858 EXPECT_CALL(foo, Blah(_, _, _))
859 .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt())));
862 says that `Blah()` will be called with arguments `x`, `y`, and `z` where
865 As a convenience and example, Google Mock provides some matchers for
866 2-tuples, including the `Lt()` matcher above. See the [CheatSheet](V1_7_CheatSheet.md) for
869 Note that if you want to pass the arguments to a predicate of your own
870 (e.g. `.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be
871 written to take a `tr1::tuple` as its argument; Google Mock will pass the `n`
872 selected arguments as _one_ single tuple to the predicate.
874 ## Using Matchers as Predicates ##
876 Have you noticed that a matcher is just a fancy predicate that also
877 knows how to describe itself? Many existing algorithms take predicates
878 as arguments (e.g. those defined in STL's `<algorithm>` header), and
879 it would be a shame if Google Mock matchers are not allowed to
882 Luckily, you can use a matcher where a unary predicate functor is
883 expected by wrapping it inside the `Matches()` function. For example,
891 // How many elements in v are >= 10?
892 const int count = count_if(v.begin(), v.end(), Matches(Ge(10)));
895 Since you can build complex matchers from simpler ones easily using
896 Google Mock, this gives you a way to conveniently construct composite
897 predicates (doing the same using STL's `<functional>` header is just
898 painful). For example, here's a predicate that's satisfied by any
899 number that is >= 0, <= 100, and != 50:
902 Matches(AllOf(Ge(0), Le(100), Ne(50)))
905 ## Using Matchers in Google Test Assertions ##
907 Since matchers are basically predicates that also know how to describe
908 themselves, there is a way to take advantage of them in
909 [Google Test](http://code.google.com/p/googletest/) assertions. It's
910 called `ASSERT_THAT` and `EXPECT_THAT`:
913 ASSERT_THAT(value, matcher); // Asserts that value matches matcher.
914 EXPECT_THAT(value, matcher); // The non-fatal version.
917 For example, in a Google Test test you can write:
920 #include "gmock/gmock.h"
922 using ::testing::AllOf;
925 using ::testing::MatchesRegex;
926 using ::testing::StartsWith;
929 EXPECT_THAT(Foo(), StartsWith("Hello"));
930 EXPECT_THAT(Bar(), MatchesRegex("Line \\d+"));
931 ASSERT_THAT(Baz(), AllOf(Ge(5), Le(10)));
934 which (as you can probably guess) executes `Foo()`, `Bar()`, and
935 `Baz()`, and verifies that:
937 * `Foo()` returns a string that starts with `"Hello"`.
938 * `Bar()` returns a string that matches regular expression `"Line \\d+"`.
939 * `Baz()` returns a number in the range [5, 10].
941 The nice thing about these macros is that _they read like
942 English_. They generate informative messages too. For example, if the
943 first `EXPECT_THAT()` above fails, the message will be something like:
948 Expected: starts with "Hello"
951 **Credit:** The idea of `(ASSERT|EXPECT)_THAT` was stolen from the
952 [Hamcrest](http://code.google.com/p/hamcrest/) project, which adds
953 `assertThat()` to JUnit.
955 ## Using Predicates as Matchers ##
957 Google Mock provides a built-in set of matchers. In case you find them
958 lacking, you can use an arbitray unary predicate function or functor
959 as a matcher - as long as the predicate accepts a value of the type
960 you want. You do this by wrapping the predicate inside the `Truly()`
961 function, for example:
964 using ::testing::Truly;
966 int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; }
969 // Bar() must be called with an even number.
970 EXPECT_CALL(foo, Bar(Truly(IsEven)));
973 Note that the predicate function / functor doesn't have to return
974 `bool`. It works as long as the return value can be used as the
975 condition in statement `if (condition) ...`.
977 ## Matching Arguments that Are Not Copyable ##
979 When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, Google Mock saves
980 away a copy of `bar`. When `Foo()` is called later, Google Mock
981 compares the argument to `Foo()` with the saved copy of `bar`. This
982 way, you don't need to worry about `bar` being modified or destroyed
983 after the `EXPECT_CALL()` is executed. The same is true when you use
984 matchers like `Eq(bar)`, `Le(bar)`, and so on.
986 But what if `bar` cannot be copied (i.e. has no copy constructor)? You
987 could define your own matcher function and use it with `Truly()`, as
988 the previous couple of recipes have shown. Or, you may be able to get
989 away from it if you can guarantee that `bar` won't be changed after
990 the `EXPECT_CALL()` is executed. Just tell Google Mock that it should
991 save a reference to `bar`, instead of a copy of it. Here's how:
995 using ::testing::ByRef;
998 // Expects that Foo()'s argument == bar.
999 EXPECT_CALL(mock_obj, Foo(Eq(ByRef(bar))));
1001 // Expects that Foo()'s argument < bar.
1002 EXPECT_CALL(mock_obj, Foo(Lt(ByRef(bar))));
1005 Remember: if you do this, don't change `bar` after the
1006 `EXPECT_CALL()`, or the result is undefined.
1008 ## Validating a Member of an Object ##
1010 Often a mock function takes a reference to object as an argument. When
1011 matching the argument, you may not want to compare the entire object
1012 against a fixed object, as that may be over-specification. Instead,
1013 you may need to validate a certain member variable or the result of a
1014 certain getter method of the object. You can do this with `Field()`
1015 and `Property()`. More specifically,
1021 is a matcher that matches a `Foo` object whose `bar` member variable
1022 satisfies matcher `m`.
1025 Property(&Foo::baz, m)
1028 is a matcher that matches a `Foo` object whose `baz()` method returns
1029 a value that satisfies matcher `m`.
1033 > | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. |
1034 |:-----------------------------|:-----------------------------------|
1035 > | `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. |
1037 Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no
1038 argument and be declared as `const`.
1040 BTW, `Field()` and `Property()` can also match plain pointers to
1041 objects. For instance,
1044 Field(&Foo::number, Ge(3))
1047 matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`,
1048 the match will always fail regardless of the inner matcher.
1050 What if you want to validate more than one members at the same time?
1051 Remember that there is `AllOf()`.
1053 ## Validating the Value Pointed to by a Pointer Argument ##
1055 C++ functions often take pointers as arguments. You can use matchers
1056 like `IsNull()`, `NotNull()`, and other comparison matchers to match a
1057 pointer, but what if you want to make sure the value _pointed to_ by
1058 the pointer, instead of the pointer itself, has a certain property?
1059 Well, you can use the `Pointee(m)` matcher.
1061 `Pointee(m)` matches a pointer iff `m` matches the value the pointer
1062 points to. For example:
1065 using ::testing::Ge;
1066 using ::testing::Pointee;
1068 EXPECT_CALL(foo, Bar(Pointee(Ge(3))));
1071 expects `foo.Bar()` to be called with a pointer that points to a value
1072 greater than or equal to 3.
1074 One nice thing about `Pointee()` is that it treats a `NULL` pointer as
1075 a match failure, so you can write `Pointee(m)` instead of
1078 AllOf(NotNull(), Pointee(m))
1081 without worrying that a `NULL` pointer will crash your test.
1083 Also, did we tell you that `Pointee()` works with both raw pointers
1084 **and** smart pointers (`linked_ptr`, `shared_ptr`, `scoped_ptr`, and
1087 What if you have a pointer to pointer? You guessed it - you can use
1088 nested `Pointee()` to probe deeper inside the value. For example,
1089 `Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer
1090 that points to a number less than 3 (what a mouthful...).
1092 ## Testing a Certain Property of an Object ##
1094 Sometimes you want to specify that an object argument has a certain
1095 property, but there is no existing matcher that does this. If you want
1096 good error messages, you should define a matcher. If you want to do it
1097 quick and dirty, you could get away with writing an ordinary function.
1099 Let's say you have a mock function that takes an object of type `Foo`,
1100 which has an `int bar()` method and an `int baz()` method, and you
1101 want to constrain that the argument's `bar()` value plus its `baz()`
1102 value is a given number. Here's how you can define a matcher to do it:
1105 using ::testing::MatcherInterface;
1106 using ::testing::MatchResultListener;
1108 class BarPlusBazEqMatcher : public MatcherInterface<const Foo&> {
1110 explicit BarPlusBazEqMatcher(int expected_sum)
1111 : expected_sum_(expected_sum) {}
1113 virtual bool MatchAndExplain(const Foo& foo,
1114 MatchResultListener* listener) const {
1115 return (foo.bar() + foo.baz()) == expected_sum_;
1118 virtual void DescribeTo(::std::ostream* os) const {
1119 *os << "bar() + baz() equals " << expected_sum_;
1122 virtual void DescribeNegationTo(::std::ostream* os) const {
1123 *os << "bar() + baz() does not equal " << expected_sum_;
1126 const int expected_sum_;
1129 inline Matcher<const Foo&> BarPlusBazEq(int expected_sum) {
1130 return MakeMatcher(new BarPlusBazEqMatcher(expected_sum));
1135 EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...;
1138 ## Matching Containers ##
1140 Sometimes an STL container (e.g. list, vector, map, ...) is passed to
1141 a mock function and you may want to validate it. Since most STL
1142 containers support the `==` operator, you can write
1143 `Eq(expected_container)` or simply `expected_container` to match a
1146 Sometimes, though, you may want to be more flexible (for example, the
1147 first element must be an exact match, but the second element can be
1148 any positive number, and so on). Also, containers used in tests often
1149 have a small number of elements, and having to define the expected
1150 container out-of-line is a bit of a hassle.
1152 You can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in
1157 using ::testing::ElementsAre;
1158 using ::testing::Gt;
1161 MOCK_METHOD1(Foo, void(const vector<int>& numbers));
1164 EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5)));
1167 The above matcher says that the container must have 4 elements, which
1168 must be 1, greater than 0, anything, and 5 respectively.
1170 If you instead write:
1174 using ::testing::Gt;
1175 using ::testing::UnorderedElementsAre;
1178 MOCK_METHOD1(Foo, void(const vector<int>& numbers));
1181 EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5)));
1184 It means that the container must have 4 elements, which under some
1185 permutation must be 1, greater than 0, anything, and 5 respectively.
1187 `ElementsAre()` and `UnorderedElementsAre()` are overloaded to take 0
1188 to 10 arguments. If more are needed, you can place them in a C-style
1189 array and use `ElementsAreArray()` or `UnorderedElementsAreArray()`
1193 using ::testing::ElementsAreArray;
1196 // ElementsAreArray accepts an array of element values.
1197 const int expected_vector1[] = { 1, 5, 2, 4, ... };
1198 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1)));
1200 // Or, an array of element matchers.
1201 Matcher<int> expected_vector2 = { 1, Gt(2), _, 3, ... };
1202 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2)));
1205 In case the array needs to be dynamically created (and therefore the
1206 array size cannot be inferred by the compiler), you can give
1207 `ElementsAreArray()` an additional argument to specify the array size:
1210 using ::testing::ElementsAreArray;
1212 int* const expected_vector3 = new int[count];
1213 ... fill expected_vector3 with values ...
1214 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count)));
1219 * `ElementsAre*()` can be used to match _any_ container that implements the STL iterator pattern (i.e. it has a `const_iterator` type and supports `begin()/end()`), not just the ones defined in STL. It will even work with container types yet to be written - as long as they follows the above pattern.
1220 * You can use nested `ElementsAre*()` to match nested (multi-dimensional) containers.
1221 * If the container is passed by pointer instead of by reference, just write `Pointee(ElementsAre*(...))`.
1222 * The order of elements _matters_ for `ElementsAre*()`. Therefore don't use it with containers whose element order is undefined (e.g. `hash_map`).
1224 ## Sharing Matchers ##
1226 Under the hood, a Google Mock matcher object consists of a pointer to
1227 a ref-counted implementation object. Copying matchers is allowed and
1228 very efficient, as only the pointer is copied. When the last matcher
1229 that references the implementation object dies, the implementation
1230 object will be deleted.
1232 Therefore, if you have some complex matcher that you want to use again
1233 and again, there is no need to build it everytime. Just assign it to a
1234 matcher variable and use that variable repeatedly! For example,
1237 Matcher<int> in_range = AllOf(Gt(5), Le(10));
1238 ... use in_range as a matcher in multiple EXPECT_CALLs ...
1241 # Setting Expectations #
1243 ## Knowing When to Expect ##
1245 `ON_CALL` is likely the single most under-utilized construct in Google Mock.
1247 There are basically two constructs for defining the behavior of a mock object: `ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when a mock method is called, but _doesn't imply any expectation on the method being called._ `EXPECT_CALL` not only defines the behavior, but also sets an expectation that _the method will be called with the given arguments, for the given number of times_ (and _in the given order_ when you specify the order too).
1249 Since `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every `EXPECT_CALL` adds a constraint on the behavior of the code under test. Having more constraints than necessary is _baaad_ - even worse than not having enough constraints.
1251 This may be counter-intuitive. How could tests that verify more be worse than tests that verify less? Isn't verification the whole point of tests?
1253 The answer, lies in _what_ a test should verify. **A good test verifies the contract of the code.** If a test over-specifies, it doesn't leave enough freedom to the implementation. As a result, changing the implementation without breaking the contract (e.g. refactoring and optimization), which should be perfectly fine to do, can break such tests. Then you have to spend time fixing them, only to see them broken again the next time the implementation is changed.
1255 Keep in mind that one doesn't have to verify more than one property in one test. In fact, **it's a good style to verify only one thing in one test.** If you do that, a bug will likely break only one or two tests instead of dozens (which case would you rather debug?). If you are also in the habit of giving tests descriptive names that tell what they verify, you can often easily guess what's wrong just from the test log itself.
1257 So use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend to verify that the call is made. For example, you may have a bunch of `ON_CALL`s in your test fixture to set the common mock behavior shared by all tests in the same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s to verify different aspects of the code's behavior. Compared with the style where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more resilient to implementational changes (and thus less likely to require maintenance) and makes the intent of the tests more obvious (so they are easier to maintain when you do need to maintain them).
1259 ## Ignoring Uninteresting Calls ##
1261 If you are not interested in how a mock method is called, just don't
1262 say anything about it. In this case, if the method is ever called,
1263 Google Mock will perform its default action to allow the test program
1264 to continue. If you are not happy with the default action taken by
1265 Google Mock, you can override it using `DefaultValue<T>::Set()`
1266 (described later in this document) or `ON_CALL()`.
1268 Please note that once you expressed interest in a particular mock
1269 method (via `EXPECT_CALL()`), all invocations to it must match some
1270 expectation. If this function is called but the arguments don't match
1271 any `EXPECT_CALL()` statement, it will be an error.
1273 ## Disallowing Unexpected Calls ##
1275 If a mock method shouldn't be called at all, explicitly say so:
1280 EXPECT_CALL(foo, Bar(_))
1284 If some calls to the method are allowed, but the rest are not, just
1285 list all the expected calls:
1288 using ::testing::AnyNumber;
1289 using ::testing::Gt;
1291 EXPECT_CALL(foo, Bar(5));
1292 EXPECT_CALL(foo, Bar(Gt(10)))
1293 .Times(AnyNumber());
1296 A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()`
1297 statements will be an error.
1299 ## Expecting Ordered Calls ##
1301 Although an `EXPECT_CALL()` statement defined earlier takes precedence
1302 when Google Mock tries to match a function call with an expectation,
1303 by default calls don't have to happen in the order `EXPECT_CALL()`
1304 statements are written. For example, if the arguments match the
1305 matchers in the third `EXPECT_CALL()`, but not those in the first two,
1306 then the third expectation will be used.
1308 If you would rather have all calls occur in the order of the
1309 expectations, put the `EXPECT_CALL()` statements in a block where you
1310 define a variable of type `InSequence`:
1314 using ::testing::InSequence;
1319 EXPECT_CALL(foo, DoThis(5));
1320 EXPECT_CALL(bar, DoThat(_))
1322 EXPECT_CALL(foo, DoThis(6));
1326 In this example, we expect a call to `foo.DoThis(5)`, followed by two
1327 calls to `bar.DoThat()` where the argument can be anything, which are
1328 in turn followed by a call to `foo.DoThis(6)`. If a call occurred
1329 out-of-order, Google Mock will report an error.
1331 ## Expecting Partially Ordered Calls ##
1333 Sometimes requiring everything to occur in a predetermined order can
1334 lead to brittle tests. For example, we may care about `A` occurring
1335 before both `B` and `C`, but aren't interested in the relative order
1336 of `B` and `C`. In this case, the test should reflect our real intent,
1337 instead of being overly constraining.
1339 Google Mock allows you to impose an arbitrary DAG (directed acyclic
1340 graph) on the calls. One way to express the DAG is to use the
1341 [After](http://code.google.com/p/googlemock/wiki/V1_7_CheatSheet#The_After_Clause) clause of `EXPECT_CALL`.
1343 Another way is via the `InSequence()` clause (not the same as the
1344 `InSequence` class), which we borrowed from jMock 2. It's less
1345 flexible than `After()`, but more convenient when you have long chains
1346 of sequential calls, as it doesn't require you to come up with
1347 different names for the expectations in the chains. Here's how it
1350 If we view `EXPECT_CALL()` statements as nodes in a graph, and add an
1351 edge from node A to node B wherever A must occur before B, we can get
1352 a DAG. We use the term "sequence" to mean a directed path in this
1353 DAG. Now, if we decompose the DAG into sequences, we just need to know
1354 which sequences each `EXPECT_CALL()` belongs to in order to be able to
1355 reconstruct the orginal DAG.
1357 So, to specify the partial order on the expectations we need to do two
1358 things: first to define some `Sequence` objects, and then for each
1359 `EXPECT_CALL()` say which `Sequence` objects it is part
1360 of. Expectations in the same sequence must occur in the order they are
1361 written. For example,
1364 using ::testing::Sequence;
1368 EXPECT_CALL(foo, A())
1369 .InSequence(s1, s2);
1370 EXPECT_CALL(bar, B())
1372 EXPECT_CALL(bar, C())
1374 EXPECT_CALL(foo, D())
1378 specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A ->
1389 This means that A must occur before B and C, and C must occur before
1390 D. There's no restriction about the order other than these.
1392 ## Controlling When an Expectation Retires ##
1394 When a mock method is called, Google Mock only consider expectations
1395 that are still active. An expectation is active when created, and
1396 becomes inactive (aka _retires_) when a call that has to occur later
1397 has occurred. For example, in
1401 using ::testing::Sequence;
1405 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1
1407 .InSequence(s1, s2);
1408 EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2
1410 EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3
1414 as soon as either #2 or #3 is matched, #1 will retire. If a warning
1415 `"File too large."` is logged after this, it will be an error.
1417 Note that an expectation doesn't retire automatically when it's
1418 saturated. For example,
1423 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1424 EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2
1427 says that there will be exactly one warning with the message `"File
1428 too large."`. If the second warning contains this message too, #2 will
1429 match again and result in an upper-bound-violated error.
1431 If this is not what you want, you can ask an expectation to retire as
1432 soon as it becomes saturated:
1437 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1438 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2
1439 .RetiresOnSaturation();
1442 Here #2 can be used only once, so if you have two warnings with the
1443 message `"File too large."`, the first will match #2 and the second
1444 will match #1 - there will be no error.
1448 ## Returning References from Mock Methods ##
1450 If a mock function's return type is a reference, you need to use
1451 `ReturnRef()` instead of `Return()` to return a result:
1454 using ::testing::ReturnRef;
1456 class MockFoo : public Foo {
1458 MOCK_METHOD0(GetBar, Bar&());
1464 EXPECT_CALL(foo, GetBar())
1465 .WillOnce(ReturnRef(bar));
1468 ## Returning Live Values from Mock Methods ##
1470 The `Return(x)` action saves a copy of `x` when the action is
1471 _created_, and always returns the same value whenever it's
1472 executed. Sometimes you may want to instead return the _live_ value of
1473 `x` (i.e. its value at the time when the action is _executed_.).
1475 If the mock function's return type is a reference, you can do it using
1476 `ReturnRef(x)`, as shown in the previous recipe ("Returning References
1477 from Mock Methods"). However, Google Mock doesn't let you use
1478 `ReturnRef()` in a mock function whose return type is not a reference,
1479 as doing that usually indicates a user error. So, what shall you do?
1481 You may be tempted to try `ByRef()`:
1484 using testing::ByRef;
1485 using testing::Return;
1487 class MockFoo : public Foo {
1489 MOCK_METHOD0(GetValue, int());
1494 EXPECT_CALL(foo, GetValue())
1495 .WillRepeatedly(Return(ByRef(x)));
1497 EXPECT_EQ(42, foo.GetValue());
1500 Unfortunately, it doesn't work here. The above code will fail with error:
1503 Value of: foo.GetValue()
1508 The reason is that `Return(value)` converts `value` to the actual
1509 return type of the mock function at the time when the action is
1510 _created_, not when it is _executed_. (This behavior was chosen for
1511 the action to be safe when `value` is a proxy object that references
1512 some temporary objects.) As a result, `ByRef(x)` is converted to an
1513 `int` value (instead of a `const int&`) when the expectation is set,
1514 and `Return(ByRef(x))` will always return 0.
1516 `ReturnPointee(pointer)` was provided to solve this problem
1517 specifically. It returns the value pointed to by `pointer` at the time
1518 the action is _executed_:
1521 using testing::ReturnPointee;
1525 EXPECT_CALL(foo, GetValue())
1526 .WillRepeatedly(ReturnPointee(&x)); // Note the & here.
1528 EXPECT_EQ(42, foo.GetValue()); // This will succeed now.
1531 ## Combining Actions ##
1533 Want to do more than one thing when a function is called? That's
1534 fine. `DoAll()` allow you to do sequence of actions every time. Only
1535 the return value of the last action in the sequence will be used.
1538 using ::testing::DoAll;
1540 class MockFoo : public Foo {
1542 MOCK_METHOD1(Bar, bool(int n));
1546 EXPECT_CALL(foo, Bar(_))
1547 .WillOnce(DoAll(action_1,
1553 ## Mocking Side Effects ##
1555 Sometimes a method exhibits its effect not via returning a value but
1556 via side effects. For example, it may change some global state or
1557 modify an output argument. To mock side effects, in general you can
1558 define your own action by implementing `::testing::ActionInterface`.
1560 If all you need to do is to change an output argument, the built-in
1561 `SetArgPointee()` action is convenient:
1564 using ::testing::SetArgPointee;
1566 class MockMutator : public Mutator {
1568 MOCK_METHOD2(Mutate, void(bool mutate, int* value));
1573 MockMutator mutator;
1574 EXPECT_CALL(mutator, Mutate(true, _))
1575 .WillOnce(SetArgPointee<1>(5));
1578 In this example, when `mutator.Mutate()` is called, we will assign 5
1579 to the `int` variable pointed to by argument #1
1582 `SetArgPointee()` conveniently makes an internal copy of the
1583 value you pass to it, removing the need to keep the value in scope and
1584 alive. The implication however is that the value must have a copy
1585 constructor and assignment operator.
1587 If the mock method also needs to return a value as well, you can chain
1588 `SetArgPointee()` with `Return()` using `DoAll()`:
1592 using ::testing::Return;
1593 using ::testing::SetArgPointee;
1595 class MockMutator : public Mutator {
1598 MOCK_METHOD1(MutateInt, bool(int* value));
1602 MockMutator mutator;
1603 EXPECT_CALL(mutator, MutateInt(_))
1604 .WillOnce(DoAll(SetArgPointee<0>(5),
1608 If the output argument is an array, use the
1609 `SetArrayArgument<N>(first, last)` action instead. It copies the
1610 elements in source range `[first, last)` to the array pointed to by
1611 the `N`-th (0-based) argument:
1614 using ::testing::NotNull;
1615 using ::testing::SetArrayArgument;
1617 class MockArrayMutator : public ArrayMutator {
1619 MOCK_METHOD2(Mutate, void(int* values, int num_values));
1624 MockArrayMutator mutator;
1625 int values[5] = { 1, 2, 3, 4, 5 };
1626 EXPECT_CALL(mutator, Mutate(NotNull(), 5))
1627 .WillOnce(SetArrayArgument<0>(values, values + 5));
1630 This also works when the argument is an output iterator:
1634 using ::testing::SeArrayArgument;
1636 class MockRolodex : public Rolodex {
1638 MOCK_METHOD1(GetNames, void(std::back_insert_iterator<vector<string> >));
1643 MockRolodex rolodex;
1644 vector<string> names;
1645 names.push_back("George");
1646 names.push_back("John");
1647 names.push_back("Thomas");
1648 EXPECT_CALL(rolodex, GetNames(_))
1649 .WillOnce(SetArrayArgument<0>(names.begin(), names.end()));
1652 ## Changing a Mock Object's Behavior Based on the State ##
1654 If you expect a call to change the behavior of a mock object, you can use `::testing::InSequence` to specify different behaviors before and after the call:
1657 using ::testing::InSequence;
1658 using ::testing::Return;
1663 EXPECT_CALL(my_mock, IsDirty())
1664 .WillRepeatedly(Return(true));
1665 EXPECT_CALL(my_mock, Flush());
1666 EXPECT_CALL(my_mock, IsDirty())
1667 .WillRepeatedly(Return(false));
1669 my_mock.FlushIfDirty();
1672 This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called and return `false` afterwards.
1674 If the behavior change is more complex, you can store the effects in a variable and make a mock method get its return value from that variable:
1678 using ::testing::SaveArg;
1679 using ::testing::Return;
1681 ACTION_P(ReturnPointee, p) { return *p; }
1683 int previous_value = 0;
1684 EXPECT_CALL(my_mock, GetPrevValue())
1685 .WillRepeatedly(ReturnPointee(&previous_value));
1686 EXPECT_CALL(my_mock, UpdateValue(_))
1687 .WillRepeatedly(SaveArg<0>(&previous_value));
1688 my_mock.DoSomethingToUpdateValue();
1691 Here `my_mock.GetPrevValue()` will always return the argument of the last `UpdateValue()` call.
1693 ## Setting the Default Value for a Return Type ##
1695 If a mock method's return type is a built-in C++ type or pointer, by
1696 default it will return 0 when invoked. You only need to specify an
1697 action if this default value doesn't work for you.
1699 Sometimes, you may want to change this default value, or you may want
1700 to specify a default value for types Google Mock doesn't know
1701 about. You can do this using the `::testing::DefaultValue` class
1705 class MockFoo : public Foo {
1707 MOCK_METHOD0(CalculateBar, Bar());
1712 // Sets the default return value for type Bar.
1713 DefaultValue<Bar>::Set(default_bar);
1717 // We don't need to specify an action here, as the default
1718 // return value works for us.
1719 EXPECT_CALL(foo, CalculateBar());
1721 foo.CalculateBar(); // This should return default_bar.
1723 // Unsets the default return value.
1724 DefaultValue<Bar>::Clear();
1727 Please note that changing the default value for a type can make you
1728 tests hard to understand. We recommend you to use this feature
1729 judiciously. For example, you may want to make sure the `Set()` and
1730 `Clear()` calls are right next to the code that uses your mock.
1732 ## Setting the Default Actions for a Mock Method ##
1734 You've learned how to change the default value of a given
1735 type. However, this may be too coarse for your purpose: perhaps you
1736 have two mock methods with the same return type and you want them to
1737 have different behaviors. The `ON_CALL()` macro allows you to
1738 customize your mock's behavior at the method level:
1742 using ::testing::AnyNumber;
1743 using ::testing::Gt;
1744 using ::testing::Return;
1746 ON_CALL(foo, Sign(_))
1747 .WillByDefault(Return(-1));
1748 ON_CALL(foo, Sign(0))
1749 .WillByDefault(Return(0));
1750 ON_CALL(foo, Sign(Gt(0)))
1751 .WillByDefault(Return(1));
1753 EXPECT_CALL(foo, Sign(_))
1754 .Times(AnyNumber());
1756 foo.Sign(5); // This should return 1.
1757 foo.Sign(-9); // This should return -1.
1758 foo.Sign(0); // This should return 0.
1761 As you may have guessed, when there are more than one `ON_CALL()`
1762 statements, the news order take precedence over the older ones. In
1763 other words, the **last** one that matches the function arguments will
1764 be used. This matching order allows you to set up the common behavior
1765 in a mock object's constructor or the test fixture's set-up phase and
1766 specialize the mock's behavior later.
1768 ## Using Functions/Methods/Functors as Actions ##
1770 If the built-in actions don't suit you, you can easily use an existing
1771 function, method, or functor as an action:
1775 using ::testing::Invoke;
1777 class MockFoo : public Foo {
1779 MOCK_METHOD2(Sum, int(int x, int y));
1780 MOCK_METHOD1(ComplexJob, bool(int x));
1783 int CalculateSum(int x, int y) { return x + y; }
1787 bool ComplexJob(int x);
1793 EXPECT_CALL(foo, Sum(_, _))
1794 .WillOnce(Invoke(CalculateSum));
1795 EXPECT_CALL(foo, ComplexJob(_))
1796 .WillOnce(Invoke(&helper, &Helper::ComplexJob));
1798 foo.Sum(5, 6); // Invokes CalculateSum(5, 6).
1799 foo.ComplexJob(10); // Invokes helper.ComplexJob(10);
1802 The only requirement is that the type of the function, etc must be
1803 _compatible_ with the signature of the mock function, meaning that the
1804 latter's arguments can be implicitly converted to the corresponding
1805 arguments of the former, and the former's return type can be
1806 implicitly converted to that of the latter. So, you can invoke
1807 something whose type is _not_ exactly the same as the mock function,
1808 as long as it's safe to do so - nice, huh?
1810 ## Invoking a Function/Method/Functor Without Arguments ##
1812 `Invoke()` is very useful for doing actions that are more complex. It
1813 passes the mock function's arguments to the function or functor being
1814 invoked such that the callee has the full context of the call to work
1815 with. If the invoked function is not interested in some or all of the
1816 arguments, it can simply ignore them.
1818 Yet, a common pattern is that a test author wants to invoke a function
1819 without the arguments of the mock function. `Invoke()` allows her to
1820 do that using a wrapper function that throws away the arguments before
1821 invoking an underlining nullary function. Needless to say, this can be
1822 tedious and obscures the intent of the test.
1824 `InvokeWithoutArgs()` solves this problem. It's like `Invoke()` except
1825 that it doesn't pass the mock function's arguments to the
1826 callee. Here's an example:
1830 using ::testing::InvokeWithoutArgs;
1832 class MockFoo : public Foo {
1834 MOCK_METHOD1(ComplexJob, bool(int n));
1841 EXPECT_CALL(foo, ComplexJob(_))
1842 .WillOnce(InvokeWithoutArgs(Job1));
1844 foo.ComplexJob(10); // Invokes Job1().
1847 ## Invoking an Argument of the Mock Function ##
1849 Sometimes a mock function will receive a function pointer or a functor
1850 (in other words, a "callable") as an argument, e.g.
1853 class MockFoo : public Foo {
1855 MOCK_METHOD2(DoThis, bool(int n, bool (*fp)(int)));
1859 and you may want to invoke this callable argument:
1865 EXPECT_CALL(foo, DoThis(_, _))
1867 // Will execute (*fp)(5), where fp is the
1868 // second argument DoThis() receives.
1871 Arghh, you need to refer to a mock function argument but C++ has no
1872 lambda (yet), so you have to define your own action. :-( Or do you
1875 Well, Google Mock has an action to solve _exactly_ this problem:
1878 InvokeArgument<N>(arg_1, arg_2, ..., arg_m)
1881 will invoke the `N`-th (0-based) argument the mock function receives,
1882 with `arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is
1883 a function pointer or a functor, Google Mock handles them both.
1885 With that, you could write:
1889 using ::testing::InvokeArgument;
1891 EXPECT_CALL(foo, DoThis(_, _))
1892 .WillOnce(InvokeArgument<1>(5));
1893 // Will execute (*fp)(5), where fp is the
1894 // second argument DoThis() receives.
1897 What if the callable takes an argument by reference? No problem - just
1898 wrap it inside `ByRef()`:
1902 MOCK_METHOD1(Bar, bool(bool (*fp)(int, const Helper&)));
1905 using ::testing::ByRef;
1906 using ::testing::InvokeArgument;
1912 EXPECT_CALL(foo, Bar(_))
1913 .WillOnce(InvokeArgument<0>(5, ByRef(helper)));
1914 // ByRef(helper) guarantees that a reference to helper, not a copy of it,
1915 // will be passed to the callable.
1918 What if the callable takes an argument by reference and we do **not**
1919 wrap the argument in `ByRef()`? Then `InvokeArgument()` will _make a
1920 copy_ of the argument, and pass a _reference to the copy_, instead of
1921 a reference to the original value, to the callable. This is especially
1922 handy when the argument is a temporary value:
1926 MOCK_METHOD1(DoThat, bool(bool (*f)(const double& x, const string& s)));
1929 using ::testing::InvokeArgument;
1934 EXPECT_CALL(foo, DoThat(_))
1935 .WillOnce(InvokeArgument<0>(5.0, string("Hi")));
1936 // Will execute (*f)(5.0, string("Hi")), where f is the function pointer
1937 // DoThat() receives. Note that the values 5.0 and string("Hi") are
1938 // temporary and dead once the EXPECT_CALL() statement finishes. Yet
1939 // it's fine to perform this action later, since a copy of the values
1940 // are kept inside the InvokeArgument action.
1943 ## Ignoring an Action's Result ##
1945 Sometimes you have an action that returns _something_, but you need an
1946 action that returns `void` (perhaps you want to use it in a mock
1947 function that returns `void`, or perhaps it needs to be used in
1948 `DoAll()` and it's not the last in the list). `IgnoreResult()` lets
1949 you do that. For example:
1953 using ::testing::Invoke;
1954 using ::testing::Return;
1956 int Process(const MyData& data);
1957 string DoSomething();
1959 class MockFoo : public Foo {
1961 MOCK_METHOD1(Abc, void(const MyData& data));
1962 MOCK_METHOD0(Xyz, bool());
1967 EXPECT_CALL(foo, Abc(_))
1968 // .WillOnce(Invoke(Process));
1969 // The above line won't compile as Process() returns int but Abc() needs
1971 .WillOnce(IgnoreResult(Invoke(Process)));
1973 EXPECT_CALL(foo, Xyz())
1974 .WillOnce(DoAll(IgnoreResult(Invoke(DoSomething)),
1975 // Ignores the string DoSomething() returns.
1979 Note that you **cannot** use `IgnoreResult()` on an action that already
1980 returns `void`. Doing so will lead to ugly compiler errors.
1982 ## Selecting an Action's Arguments ##
1984 Say you have a mock function `Foo()` that takes seven arguments, and
1985 you have a custom action that you want to invoke when `Foo()` is
1986 called. Trouble is, the custom action only wants three arguments:
1990 using ::testing::Invoke;
1992 MOCK_METHOD7(Foo, bool(bool visible, const string& name, int x, int y,
1993 const map<pair<int, int>, double>& weight,
1994 double min_weight, double max_wight));
1997 bool IsVisibleInQuadrant1(bool visible, int x, int y) {
1998 return visible && x >= 0 && y >= 0;
2002 EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _))
2003 .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-(
2006 To please the compiler God, you can to define an "adaptor" that has
2007 the same signature as `Foo()` and calls the custom action with the
2012 using ::testing::Invoke;
2014 bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y,
2015 const map<pair<int, int>, double>& weight,
2016 double min_weight, double max_wight) {
2017 return IsVisibleInQuadrant1(visible, x, y);
2021 EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _))
2022 .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works.
2025 But isn't this awkward?
2027 Google Mock provides a generic _action adaptor_, so you can spend your
2028 time minding more important business than writing your own
2029 adaptors. Here's the syntax:
2032 WithArgs<N1, N2, ..., Nk>(action)
2035 creates an action that passes the arguments of the mock function at
2036 the given indices (0-based) to the inner `action` and performs
2037 it. Using `WithArgs`, our original example can be written as:
2041 using ::testing::Invoke;
2042 using ::testing::WithArgs;
2044 EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _))
2045 .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1)));
2046 // No need to define your own adaptor.
2049 For better readability, Google Mock also gives you:
2051 * `WithoutArgs(action)` when the inner `action` takes _no_ argument, and
2052 * `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes _one_ argument.
2054 As you may have realized, `InvokeWithoutArgs(...)` is just syntactic
2055 sugar for `WithoutArgs(Inovke(...))`.
2059 * The inner action used in `WithArgs` and friends does not have to be `Invoke()` -- it can be anything.
2060 * You can repeat an argument in the argument list if necessary, e.g. `WithArgs<2, 3, 3, 5>(...)`.
2061 * You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`.
2062 * The types of the selected arguments do _not_ have to match the signature of the inner action exactly. It works as long as they can be implicitly converted to the corresponding arguments of the inner action. For example, if the 4-th argument of the mock function is an `int` and `my_action` takes a `double`, `WithArg<4>(my_action)` will work.
2064 ## Ignoring Arguments in Action Functions ##
2066 The selecting-an-action's-arguments recipe showed us one way to make a
2067 mock function and an action with incompatible argument lists fit
2068 together. The downside is that wrapping the action in
2069 `WithArgs<...>()` can get tedious for people writing the tests.
2071 If you are defining a function, method, or functor to be used with
2072 `Invoke*()`, and you are not interested in some of its arguments, an
2073 alternative to `WithArgs` is to declare the uninteresting arguments as
2074 `Unused`. This makes the definition less cluttered and less fragile in
2075 case the types of the uninteresting arguments change. It could also
2076 increase the chance the action function can be reused. For example,
2080 MOCK_METHOD3(Foo, double(const string& label, double x, double y));
2081 MOCK_METHOD3(Bar, double(int index, double x, double y));
2088 using ::testing::Invoke;
2090 double DistanceToOriginWithLabel(const string& label, double x, double y) {
2091 return sqrt(x*x + y*y);
2094 double DistanceToOriginWithIndex(int index, double x, double y) {
2095 return sqrt(x*x + y*y);
2099 EXEPCT_CALL(mock, Foo("abc", _, _))
2100 .WillOnce(Invoke(DistanceToOriginWithLabel));
2101 EXEPCT_CALL(mock, Bar(5, _, _))
2102 .WillOnce(Invoke(DistanceToOriginWithIndex));
2109 using ::testing::Invoke;
2110 using ::testing::Unused;
2112 double DistanceToOrigin(Unused, double x, double y) {
2113 return sqrt(x*x + y*y);
2117 EXEPCT_CALL(mock, Foo("abc", _, _))
2118 .WillOnce(Invoke(DistanceToOrigin));
2119 EXEPCT_CALL(mock, Bar(5, _, _))
2120 .WillOnce(Invoke(DistanceToOrigin));
2123 ## Sharing Actions ##
2125 Just like matchers, a Google Mock action object consists of a pointer
2126 to a ref-counted implementation object. Therefore copying actions is
2127 also allowed and very efficient. When the last action that references
2128 the implementation object dies, the implementation object will be
2131 If you have some complex action that you want to use again and again,
2132 you may not have to build it from scratch everytime. If the action
2133 doesn't have an internal state (i.e. if it always does the same thing
2134 no matter how many times it has been called), you can assign it to an
2135 action variable and use that variable repeatedly. For example:
2138 Action<bool(int*)> set_flag = DoAll(SetArgPointee<0>(5),
2140 ... use set_flag in .WillOnce() and .WillRepeatedly() ...
2143 However, if the action has its own state, you may be surprised if you
2144 share the action object. Suppose you have an action factory
2145 `IncrementCounter(init)` which creates an action that increments and
2146 returns a counter whose initial value is `init`, using two actions
2147 created from the same expression and using a shared action will
2148 exihibit different behaviors. Example:
2151 EXPECT_CALL(foo, DoThis())
2152 .WillRepeatedly(IncrementCounter(0));
2153 EXPECT_CALL(foo, DoThat())
2154 .WillRepeatedly(IncrementCounter(0));
2155 foo.DoThis(); // Returns 1.
2156 foo.DoThis(); // Returns 2.
2157 foo.DoThat(); // Returns 1 - Blah() uses a different
2158 // counter than Bar()'s.
2164 Action<int()> increment = IncrementCounter(0);
2166 EXPECT_CALL(foo, DoThis())
2167 .WillRepeatedly(increment);
2168 EXPECT_CALL(foo, DoThat())
2169 .WillRepeatedly(increment);
2170 foo.DoThis(); // Returns 1.
2171 foo.DoThis(); // Returns 2.
2172 foo.DoThat(); // Returns 3 - the counter is shared.
2175 # Misc Recipes on Using Google Mock #
2177 ## Making the Compilation Faster ##
2179 Believe it or not, the _vast majority_ of the time spent on compiling
2180 a mock class is in generating its constructor and destructor, as they
2181 perform non-trivial tasks (e.g. verification of the
2182 expectations). What's more, mock methods with different signatures
2183 have different types and thus their constructors/destructors need to
2184 be generated by the compiler separately. As a result, if you mock many
2185 different types of methods, compiling your mock class can get really
2188 If you are experiencing slow compilation, you can move the definition
2189 of your mock class' constructor and destructor out of the class body
2190 and into a `.cpp` file. This way, even if you `#include` your mock
2191 class in N files, the compiler only needs to generate its constructor
2192 and destructor once, resulting in a much faster compilation.
2194 Let's illustrate the idea using an example. Here's the definition of a
2195 mock class before applying this recipe:
2200 class MockFoo : public Foo {
2202 // Since we don't declare the constructor or the destructor,
2203 // the compiler will generate them in every translation unit
2204 // where this mock class is used.
2206 MOCK_METHOD0(DoThis, int());
2207 MOCK_METHOD1(DoThat, bool(const char* str));
2208 ... more mock methods ...
2212 After the change, it would look like:
2217 class MockFoo : public Foo {
2219 // The constructor and destructor are declared, but not defined, here.
2223 MOCK_METHOD0(DoThis, int());
2224 MOCK_METHOD1(DoThat, bool(const char* str));
2225 ... more mock methods ...
2230 // File mock_foo.cpp.
2231 #include "path/to/mock_foo.h"
2233 // The definitions may appear trivial, but the functions actually do a
2234 // lot of things through the constructors/destructors of the member
2235 // variables used to implement the mock methods.
2236 MockFoo::MockFoo() {}
2237 MockFoo::~MockFoo() {}
2240 ## Forcing a Verification ##
2242 When it's being destoyed, your friendly mock object will automatically
2243 verify that all expectations on it have been satisfied, and will
2244 generate [Google Test](http://code.google.com/p/googletest/) failures
2245 if not. This is convenient as it leaves you with one less thing to
2246 worry about. That is, unless you are not sure if your mock object will
2249 How could it be that your mock object won't eventually be destroyed?
2250 Well, it might be created on the heap and owned by the code you are
2251 testing. Suppose there's a bug in that code and it doesn't delete the
2252 mock object properly - you could end up with a passing test when
2253 there's actually a bug.
2255 Using a heap checker is a good idea and can alleviate the concern, but
2256 its implementation may not be 100% reliable. So, sometimes you do want
2257 to _force_ Google Mock to verify a mock object before it is
2258 (hopefully) destructed. You can do this with
2259 `Mock::VerifyAndClearExpectations(&mock_object)`:
2262 TEST(MyServerTest, ProcessesRequest) {
2263 using ::testing::Mock;
2265 MockFoo* const foo = new MockFoo;
2266 EXPECT_CALL(*foo, ...)...;
2267 // ... other expectations ...
2269 // server now owns foo.
2270 MyServer server(foo);
2271 server.ProcessRequest(...);
2273 // In case that server's destructor will forget to delete foo,
2274 // this will verify the expectations anyway.
2275 Mock::VerifyAndClearExpectations(foo);
2276 } // server is destroyed when it goes out of scope here.
2279 **Tip:** The `Mock::VerifyAndClearExpectations()` function returns a
2280 `bool` to indicate whether the verification was successful (`true` for
2281 yes), so you can wrap that function call inside a `ASSERT_TRUE()` if
2282 there is no point going further when the verification has failed.
2284 ## Using Check Points ##
2286 Sometimes you may want to "reset" a mock object at various check
2287 points in your test: at each check point, you verify that all existing
2288 expectations on the mock object have been satisfied, and then you set
2289 some new expectations on it as if it's newly created. This allows you
2290 to work with a mock object in "phases" whose sizes are each
2293 One such scenario is that in your test's `SetUp()` function, you may
2294 want to put the object you are testing into a certain state, with the
2295 help from a mock object. Once in the desired state, you want to clear
2296 all expectations on the mock, such that in the `TEST_F` body you can
2297 set fresh expectations on it.
2299 As you may have figured out, the `Mock::VerifyAndClearExpectations()`
2300 function we saw in the previous recipe can help you here. Or, if you
2301 are using `ON_CALL()` to set default actions on the mock object and
2302 want to clear the default actions as well, use
2303 `Mock::VerifyAndClear(&mock_object)` instead. This function does what
2304 `Mock::VerifyAndClearExpectations(&mock_object)` does and returns the
2305 same `bool`, **plus** it clears the `ON_CALL()` statements on
2308 Another trick you can use to achieve the same effect is to put the
2309 expectations in sequences and insert calls to a dummy "check-point"
2310 function at specific places. Then you can verify that the mock
2311 function calls do happen at the right time. For example, if you are
2320 and want to verify that `Foo(1)` and `Foo(3)` both invoke
2321 `mock.Bar("a")`, but `Foo(2)` doesn't invoke anything. You can write:
2324 using ::testing::MockFunction;
2326 TEST(FooTest, InvokesBarCorrectly) {
2328 // Class MockFunction<F> has exactly one mock method. It is named
2329 // Call() and has type F.
2330 MockFunction<void(string check_point_name)> check;
2334 EXPECT_CALL(mock, Bar("a"));
2335 EXPECT_CALL(check, Call("1"));
2336 EXPECT_CALL(check, Call("2"));
2337 EXPECT_CALL(mock, Bar("a"));
2347 The expectation spec says that the first `Bar("a")` must happen before
2348 check point "1", the second `Bar("a")` must happen after check point "2",
2349 and nothing should happen between the two check points. The explicit
2350 check points make it easy to tell which `Bar("a")` is called by which
2353 ## Mocking Destructors ##
2355 Sometimes you want to make sure a mock object is destructed at the
2356 right time, e.g. after `bar->A()` is called but before `bar->B()` is
2357 called. We already know that you can specify constraints on the order
2358 of mock function calls, so all we need to do is to mock the destructor
2359 of the mock function.
2361 This sounds simple, except for one problem: a destructor is a special
2362 function with special syntax and special semantics, and the
2363 `MOCK_METHOD0` macro doesn't work for it:
2366 MOCK_METHOD0(~MockFoo, void()); // Won't compile!
2369 The good news is that you can use a simple pattern to achieve the same
2370 effect. First, add a mock function `Die()` to your mock class and call
2371 it in the destructor, like this:
2374 class MockFoo : public Foo {
2376 // Add the following two lines to the mock class.
2377 MOCK_METHOD0(Die, void());
2378 virtual ~MockFoo() { Die(); }
2382 (If the name `Die()` clashes with an existing symbol, choose another
2383 name.) Now, we have translated the problem of testing when a `MockFoo`
2384 object dies to testing when its `Die()` method is called:
2387 MockFoo* foo = new MockFoo;
2388 MockBar* bar = new MockBar;
2393 // Expects *foo to die after bar->A() and before bar->B().
2394 EXPECT_CALL(*bar, A());
2395 EXPECT_CALL(*foo, Die());
2396 EXPECT_CALL(*bar, B());
2402 ## Using Google Mock and Threads ##
2404 **IMPORTANT NOTE:** What we describe in this recipe is **ONLY** true on
2405 platforms where Google Mock is thread-safe. Currently these are only
2406 platforms that support the pthreads library (this includes Linux and Mac).
2407 To make it thread-safe on other platforms we only need to implement
2408 some synchronization operations in `"gtest/internal/gtest-port.h"`.
2410 In a **unit** test, it's best if you could isolate and test a piece of
2411 code in a single-threaded context. That avoids race conditions and
2412 dead locks, and makes debugging your test much easier.
2414 Yet many programs are multi-threaded, and sometimes to test something
2415 we need to pound on it from more than one thread. Google Mock works
2416 for this purpose too.
2418 Remember the steps for using a mock:
2420 1. Create a mock object `foo`.
2421 1. Set its default actions and expectations using `ON_CALL()` and `EXPECT_CALL()`.
2422 1. The code under test calls methods of `foo`.
2423 1. Optionally, verify and reset the mock.
2424 1. Destroy the mock yourself, or let the code under test destroy it. The destructor will automatically verify it.
2426 If you follow the following simple rules, your mocks and threads can
2427 live happily togeter:
2429 * Execute your _test code_ (as opposed to the code being tested) in _one_ thread. This makes your test easy to follow.
2430 * Obviously, you can do step #1 without locking.
2431 * When doing step #2 and #5, make sure no other thread is accessing `foo`. Obvious too, huh?
2432 * #3 and #4 can be done either in one thread or in multiple threads - anyway you want. Google Mock takes care of the locking, so you don't have to do any - unless required by your test logic.
2434 If you violate the rules (for example, if you set expectations on a
2435 mock while another thread is calling its methods), you get undefined
2436 behavior. That's not fun, so don't do it.
2438 Google Mock guarantees that the action for a mock function is done in
2439 the same thread that called the mock function. For example, in
2442 EXPECT_CALL(mock, Foo(1))
2444 EXPECT_CALL(mock, Foo(2))
2448 if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2,
2449 Google Mock will execute `action1` in thread 1 and `action2` in thread
2452 Google Mock does _not_ impose a sequence on actions performed in
2453 different threads (doing so may create deadlocks as the actions may
2454 need to cooperate). This means that the execution of `action1` and
2455 `action2` in the above example _may_ interleave. If this is a problem,
2456 you should add proper synchronization logic to `action1` and `action2`
2457 to make the test thread-safe.
2460 Also, remember that `DefaultValue<T>` is a global resource that
2461 potentially affects _all_ living mock objects in your
2462 program. Naturally, you won't want to mess with it from multiple
2463 threads or when there still are mocks in action.
2465 ## Controlling How Much Information Google Mock Prints ##
2467 When Google Mock sees something that has the potential of being an
2468 error (e.g. a mock function with no expectation is called, a.k.a. an
2469 uninteresting call, which is allowed but perhaps you forgot to
2470 explicitly ban the call), it prints some warning messages, including
2471 the arguments of the function and the return value. Hopefully this
2472 will remind you to take a look and see if there is indeed a problem.
2474 Sometimes you are confident that your tests are correct and may not
2475 appreciate such friendly messages. Some other times, you are debugging
2476 your tests or learning about the behavior of the code you are testing,
2477 and wish you could observe every mock call that happens (including
2478 argument values and the return value). Clearly, one size doesn't fit
2481 You can control how much Google Mock tells you using the
2482 `--gmock_verbose=LEVEL` command-line flag, where `LEVEL` is a string
2483 with three possible values:
2485 * `info`: Google Mock will print all informational messages, warnings, and errors (most verbose). At this setting, Google Mock will also log any calls to the `ON_CALL/EXPECT_CALL` macros.
2486 * `warning`: Google Mock will print both warnings and errors (less verbose). This is the default.
2487 * `error`: Google Mock will print errors only (least verbose).
2489 Alternatively, you can adjust the value of that flag from within your
2493 ::testing::FLAGS_gmock_verbose = "error";
2496 Now, judiciously use the right flag to enable Google Mock serve you better!
2498 ## Gaining Super Vision into Mock Calls ##
2500 You have a test using Google Mock. It fails: Google Mock tells you
2501 that some expectations aren't satisfied. However, you aren't sure why:
2502 Is there a typo somewhere in the matchers? Did you mess up the order
2503 of the `EXPECT_CALL`s? Or is the code under test doing something
2504 wrong? How can you find out the cause?
2506 Won't it be nice if you have X-ray vision and can actually see the
2507 trace of all `EXPECT_CALL`s and mock method calls as they are made?
2508 For each call, would you like to see its actual argument values and
2509 which `EXPECT_CALL` Google Mock thinks it matches?
2511 You can unlock this power by running your test with the
2512 `--gmock_verbose=info` flag. For example, given the test program:
2516 using testing::HasSubstr;
2517 using testing::Return;
2521 MOCK_METHOD2(F, void(const string& x, const string& y));
2526 EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return());
2527 EXPECT_CALL(mock, F("a", "b"));
2528 EXPECT_CALL(mock, F("c", HasSubstr("d")));
2530 mock.F("a", "good");
2535 if you run it with `--gmock_verbose=info`, you will see this output:
2540 foo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked
2541 foo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked
2542 foo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked
2543 foo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))...
2544 Function call: F(@0x7fff7c8dad40"a", @0x7fff7c8dad10"good")
2545 foo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))...
2546 Function call: F(@0x7fff7c8dada0"a", @0x7fff7c8dad70"b")
2547 foo_test.cc:16: Failure
2548 Actual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))...
2549 Expected: to be called once
2550 Actual: never called - unsatisfied and active
2554 Suppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo
2555 and should actually be `"a"`. With the above message, you should see
2556 that the actual `F("a", "good")` call is matched by the first
2557 `EXPECT_CALL`, not the third as you thought. From that it should be
2558 obvious that the third `EXPECT_CALL` is written wrong. Case solved.
2560 ## Running Tests in Emacs ##
2562 If you build and run your tests in Emacs, the source file locations of
2563 Google Mock and [Google Test](http://code.google.com/p/googletest/)
2564 errors will be highlighted. Just press `<Enter>` on one of them and
2565 you'll be taken to the offending line. Or, you can just type `C-x ``
2566 to jump to the next error.
2568 To make it even easier, you can add the following lines to your
2572 (global-set-key "\M-m" 'compile) ; m is for make
2573 (global-set-key [M-down] 'next-error)
2574 (global-set-key [M-up] '(lambda () (interactive) (next-error -1)))
2577 Then you can type `M-m` to start a build, or `M-up`/`M-down` to move
2578 back and forth between errors.
2580 ## Fusing Google Mock Source Files ##
2582 Google Mock's implementation consists of dozens of files (excluding
2583 its own tests). Sometimes you may want them to be packaged up in
2584 fewer files instead, such that you can easily copy them to a new
2585 machine and start hacking there. For this we provide an experimental
2586 Python script `fuse_gmock_files.py` in the `scripts/` directory
2587 (starting with release 1.2.0). Assuming you have Python 2.4 or above
2588 installed on your machine, just go to that directory and run
2590 python fuse_gmock_files.py OUTPUT_DIR
2593 and you should see an `OUTPUT_DIR` directory being created with files
2594 `gtest/gtest.h`, `gmock/gmock.h`, and `gmock-gtest-all.cc` in it.
2595 These three files contain everything you need to use Google Mock (and
2596 Google Test). Just copy them to anywhere you want and you are ready
2597 to write tests and use mocks. You can use the
2598 [scrpts/test/Makefile](http://code.google.com/p/googlemock/source/browse/trunk/scripts/test/Makefile) file as an example on how to compile your tests
2601 # Extending Google Mock #
2603 ## Writing New Matchers Quickly ##
2605 The `MATCHER*` family of macros can be used to define custom matchers
2609 MATCHER(name, description_string_expression) { statements; }
2612 will define a matcher with the given name that executes the
2613 statements, which must return a `bool` to indicate if the match
2614 succeeds. Inside the statements, you can refer to the value being
2615 matched by `arg`, and refer to its type by `arg_type`.
2617 The description string is a `string`-typed expression that documents
2618 what the matcher does, and is used to generate the failure message
2619 when the match fails. It can (and should) reference the special
2620 `bool` variable `negation`, and should evaluate to the description of
2621 the matcher when `negation` is `false`, or that of the matcher's
2622 negation when `negation` is `true`.
2624 For convenience, we allow the description string to be empty (`""`),
2625 in which case Google Mock will use the sequence of words in the
2626 matcher name as the description.
2630 MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; }
2634 // Expects mock_foo.Bar(n) to be called where n is divisible by 7.
2635 EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7()));
2639 using ::testing::Not;
2641 EXPECT_THAT(some_expression, IsDivisibleBy7());
2642 EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7()));
2644 If the above assertions fail, they will print something like:
2646 Value of: some_expression
2647 Expected: is divisible by 7
2650 Value of: some_other_expression
2651 Expected: not (is divisible by 7)
2654 where the descriptions `"is divisible by 7"` and `"not (is divisible
2655 by 7)"` are automatically calculated from the matcher name
2658 As you may have noticed, the auto-generated descriptions (especially
2659 those for the negation) may not be so great. You can always override
2660 them with a string expression of your own:
2662 MATCHER(IsDivisibleBy7, std::string(negation ? "isn't" : "is") +
2663 " divisible by 7") {
2664 return (arg % 7) == 0;
2668 Optionally, you can stream additional information to a hidden argument
2669 named `result_listener` to explain the match result. For example, a
2670 better definition of `IsDivisibleBy7` is:
2672 MATCHER(IsDivisibleBy7, "") {
2676 *result_listener << "the remainder is " << (arg % 7);
2681 With this definition, the above assertion will give a better message:
2683 Value of: some_expression
2684 Expected: is divisible by 7
2685 Actual: 27 (the remainder is 6)
2688 You should let `MatchAndExplain()` print _any additional information_
2689 that can help a user understand the match result. Note that it should
2690 explain why the match succeeds in case of a success (unless it's
2691 obvious) - this is useful when the matcher is used inside
2692 `Not()`. There is no need to print the argument value itself, as
2693 Google Mock already prints it for you.
2697 1. The type of the value being matched (`arg_type`) is determined by the context in which you use the matcher and is supplied to you by the compiler, so you don't need to worry about declaring it (nor can you). This allows the matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match any type where the value of `(arg % 7) == 0` can be implicitly converted to a `bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an `int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will be `unsigned long`; and so on.
2698 1. Google Mock doesn't guarantee when or how many times a matcher will be invoked. Therefore the matcher logic must be _purely functional_ (i.e. it cannot have any side effect, and the result must not depend on anything other than the value being matched and the matcher parameters). This requirement must be satisfied no matter how you define the matcher (e.g. using one of the methods described in the following recipes). In particular, a matcher can never call a mock function, as that will affect the state of the mock object and Google Mock.
2700 ## Writing New Parameterized Matchers Quickly ##
2702 Sometimes you'll want to define a matcher that has parameters. For that you
2705 MATCHER_P(name, param_name, description_string) { statements; }
2707 where the description string can be either `""` or a string expression
2708 that references `negation` and `param_name`.
2712 MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
2714 will allow you to write:
2716 EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
2718 which may lead to this message (assuming `n` is 10):
2721 Expected: has absolute value 10
2725 Note that both the matcher description and its parameter are
2726 printed, making the message human-friendly.
2728 In the matcher definition body, you can write `foo_type` to
2729 reference the type of a parameter named `foo`. For example, in the
2730 body of `MATCHER_P(HasAbsoluteValue, value)` above, you can write
2731 `value_type` to refer to the type of `value`.
2733 Google Mock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to
2734 `MATCHER_P10` to support multi-parameter matchers:
2736 MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; }
2739 Please note that the custom description string is for a particular
2740 **instance** of the matcher, where the parameters have been bound to
2741 actual values. Therefore usually you'll want the parameter values to
2742 be part of the description. Google Mock lets you do that by
2743 referencing the matcher parameters in the description string
2748 using ::testing::PrintToString;
2749 MATCHER_P2(InClosedRange, low, hi,
2750 std::string(negation ? "isn't" : "is") + " in range [" +
2751 PrintToString(low) + ", " + PrintToString(hi) + "]") {
2752 return low <= arg && arg <= hi;
2755 EXPECT_THAT(3, InClosedRange(4, 6));
2757 would generate a failure that contains the message:
2759 Expected: is in range [4, 6]
2762 If you specify `""` as the description, the failure message will
2763 contain the sequence of words in the matcher name followed by the
2764 parameter values printed as a tuple. For example,
2766 MATCHER_P2(InClosedRange, low, hi, "") { ... }
2768 EXPECT_THAT(3, InClosedRange(4, 6));
2770 would generate a failure that contains the text:
2772 Expected: in closed range (4, 6)
2775 For the purpose of typing, you can view
2777 MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
2781 template <typename p1_type, ..., typename pk_type>
2782 FooMatcherPk<p1_type, ..., pk_type>
2783 Foo(p1_type p1, ..., pk_type pk) { ... }
2786 When you write `Foo(v1, ..., vk)`, the compiler infers the types of
2787 the parameters `v1`, ..., and `vk` for you. If you are not happy with
2788 the result of the type inference, you can specify the types by
2789 explicitly instantiating the template, as in `Foo<long, bool>(5, false)`.
2790 As said earlier, you don't get to (or need to) specify
2791 `arg_type` as that's determined by the context in which the matcher
2794 You can assign the result of expression `Foo(p1, ..., pk)` to a
2795 variable of type `FooMatcherPk<p1_type, ..., pk_type>`. This can be
2796 useful when composing matchers. Matchers that don't have a parameter
2797 or have only one parameter have special types: you can assign `Foo()`
2798 to a `FooMatcher`-typed variable, and assign `Foo(p)` to a
2799 `FooMatcherP<p_type>`-typed variable.
2801 While you can instantiate a matcher template with reference types,
2802 passing the parameters by pointer usually makes your code more
2803 readable. If, however, you still want to pass a parameter by
2804 reference, be aware that in the failure message generated by the
2805 matcher you will see the value of the referenced object but not its
2808 You can overload matchers with different numbers of parameters:
2810 MATCHER_P(Blah, a, description_string_1) { ... }
2811 MATCHER_P2(Blah, a, b, description_string_2) { ... }
2814 While it's tempting to always use the `MATCHER*` macros when defining
2815 a new matcher, you should also consider implementing
2816 `MatcherInterface` or using `MakePolymorphicMatcher()` instead (see
2817 the recipes that follow), especially if you need to use the matcher a
2818 lot. While these approaches require more work, they give you more
2819 control on the types of the value being matched and the matcher
2820 parameters, which in general leads to better compiler error messages
2821 that pay off in the long run. They also allow overloading matchers
2822 based on parameter types (as opposed to just based on the number of
2825 ## Writing New Monomorphic Matchers ##
2827 A matcher of argument type `T` implements
2828 `::testing::MatcherInterface<T>` and does two things: it tests whether a
2829 value of type `T` matches the matcher, and can describe what kind of
2830 values it matches. The latter ability is used for generating readable
2831 error messages when expectations are violated.
2833 The interface looks like this:
2836 class MatchResultListener {
2839 // Streams x to the underlying ostream; does nothing if the ostream
2841 template <typename T>
2842 MatchResultListener& operator<<(const T& x);
2844 // Returns the underlying ostream.
2845 ::std::ostream* stream();
2848 template <typename T>
2849 class MatcherInterface {
2851 virtual ~MatcherInterface();
2853 // Returns true iff the matcher matches x; also explains the match
2854 // result to 'listener'.
2855 virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0;
2857 // Describes this matcher to an ostream.
2858 virtual void DescribeTo(::std::ostream* os) const = 0;
2860 // Describes the negation of this matcher to an ostream.
2861 virtual void DescribeNegationTo(::std::ostream* os) const;
2865 If you need a custom matcher but `Truly()` is not a good option (for
2866 example, you may not be happy with the way `Truly(predicate)`
2867 describes itself, or you may want your matcher to be polymorphic as
2868 `Eq(value)` is), you can define a matcher to do whatever you want in
2869 two steps: first implement the matcher interface, and then define a
2870 factory function to create a matcher instance. The second step is not
2871 strictly needed but it makes the syntax of using the matcher nicer.
2873 For example, you can define a matcher to test whether an `int` is
2874 divisible by 7 and then use it like this:
2876 using ::testing::MakeMatcher;
2877 using ::testing::Matcher;
2878 using ::testing::MatcherInterface;
2879 using ::testing::MatchResultListener;
2881 class DivisibleBy7Matcher : public MatcherInterface<int> {
2883 virtual bool MatchAndExplain(int n, MatchResultListener* listener) const {
2884 return (n % 7) == 0;
2887 virtual void DescribeTo(::std::ostream* os) const {
2888 *os << "is divisible by 7";
2891 virtual void DescribeNegationTo(::std::ostream* os) const {
2892 *os << "is not divisible by 7";
2896 inline Matcher<int> DivisibleBy7() {
2897 return MakeMatcher(new DivisibleBy7Matcher);
2901 EXPECT_CALL(foo, Bar(DivisibleBy7()));
2904 You may improve the matcher message by streaming additional
2905 information to the `listener` argument in `MatchAndExplain()`:
2908 class DivisibleBy7Matcher : public MatcherInterface<int> {
2910 virtual bool MatchAndExplain(int n,
2911 MatchResultListener* listener) const {
2912 const int remainder = n % 7;
2913 if (remainder != 0) {
2914 *listener << "the remainder is " << remainder;
2916 return remainder == 0;
2922 Then, `EXPECT_THAT(x, DivisibleBy7());` may general a message like this:
2925 Expected: is divisible by 7
2926 Actual: 23 (the remainder is 2)
2929 ## Writing New Polymorphic Matchers ##
2931 You've learned how to write your own matchers in the previous
2932 recipe. Just one problem: a matcher created using `MakeMatcher()` only
2933 works for one particular type of arguments. If you want a
2934 _polymorphic_ matcher that works with arguments of several types (for
2935 instance, `Eq(x)` can be used to match a `value` as long as `value` ==
2936 `x` compiles -- `value` and `x` don't have to share the same type),
2937 you can learn the trick from `"gmock/gmock-matchers.h"` but it's a bit
2940 Fortunately, most of the time you can define a polymorphic matcher
2941 easily with the help of `MakePolymorphicMatcher()`. Here's how you can
2942 define `NotNull()` as an example:
2945 using ::testing::MakePolymorphicMatcher;
2946 using ::testing::MatchResultListener;
2947 using ::testing::NotNull;
2948 using ::testing::PolymorphicMatcher;
2950 class NotNullMatcher {
2952 // To implement a polymorphic matcher, first define a COPYABLE class
2953 // that has three members MatchAndExplain(), DescribeTo(), and
2954 // DescribeNegationTo(), like the following.
2956 // In this example, we want to use NotNull() with any pointer, so
2957 // MatchAndExplain() accepts a pointer of any type as its first argument.
2958 // In general, you can define MatchAndExplain() as an ordinary method or
2959 // a method template, or even overload it.
2960 template <typename T>
2961 bool MatchAndExplain(T* p,
2962 MatchResultListener* /* listener */) const {
2966 // Describes the property of a value matching this matcher.
2967 void DescribeTo(::std::ostream* os) const { *os << "is not NULL"; }
2969 // Describes the property of a value NOT matching this matcher.
2970 void DescribeNegationTo(::std::ostream* os) const { *os << "is NULL"; }
2973 // To construct a polymorphic matcher, pass an instance of the class
2974 // to MakePolymorphicMatcher(). Note the return type.
2975 inline PolymorphicMatcher<NotNullMatcher> NotNull() {
2976 return MakePolymorphicMatcher(NotNullMatcher());
2980 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
2983 **Note:** Your polymorphic matcher class does **not** need to inherit from
2984 `MatcherInterface` or any other class, and its methods do **not** need
2987 Like in a monomorphic matcher, you may explain the match result by
2988 streaming additional information to the `listener` argument in
2989 `MatchAndExplain()`.
2991 ## Writing New Cardinalities ##
2993 A cardinality is used in `Times()` to tell Google Mock how many times
2994 you expect a call to occur. It doesn't have to be exact. For example,
2995 you can say `AtLeast(5)` or `Between(2, 4)`.
2997 If the built-in set of cardinalities doesn't suit you, you are free to
2998 define your own by implementing the following interface (in namespace
3002 class CardinalityInterface {
3004 virtual ~CardinalityInterface();
3006 // Returns true iff call_count calls will satisfy this cardinality.
3007 virtual bool IsSatisfiedByCallCount(int call_count) const = 0;
3009 // Returns true iff call_count calls will saturate this cardinality.
3010 virtual bool IsSaturatedByCallCount(int call_count) const = 0;
3012 // Describes self to an ostream.
3013 virtual void DescribeTo(::std::ostream* os) const = 0;
3017 For example, to specify that a call must occur even number of times,
3021 using ::testing::Cardinality;
3022 using ::testing::CardinalityInterface;
3023 using ::testing::MakeCardinality;
3025 class EvenNumberCardinality : public CardinalityInterface {
3027 virtual bool IsSatisfiedByCallCount(int call_count) const {
3028 return (call_count % 2) == 0;
3031 virtual bool IsSaturatedByCallCount(int call_count) const {
3035 virtual void DescribeTo(::std::ostream* os) const {
3036 *os << "called even number of times";
3040 Cardinality EvenNumber() {
3041 return MakeCardinality(new EvenNumberCardinality);
3045 EXPECT_CALL(foo, Bar(3))
3046 .Times(EvenNumber());
3049 ## Writing New Actions Quickly ##
3051 If the built-in actions don't work for you, and you find it
3052 inconvenient to use `Invoke()`, you can use a macro from the `ACTION*`
3053 family to quickly define a new action that can be used in your code as
3054 if it's a built-in action.
3058 ACTION(name) { statements; }
3060 in a namespace scope (i.e. not inside a class or function), you will
3061 define an action with the given name that executes the statements.
3062 The value returned by `statements` will be used as the return value of
3063 the action. Inside the statements, you can refer to the K-th
3064 (0-based) argument of the mock function as `argK`. For example:
3066 ACTION(IncrementArg1) { return ++(*arg1); }
3070 ... WillOnce(IncrementArg1());
3073 Note that you don't need to specify the types of the mock function
3074 arguments. Rest assured that your code is type-safe though:
3075 you'll get a compiler error if `*arg1` doesn't support the `++`
3076 operator, or if the type of `++(*arg1)` isn't compatible with the mock
3077 function's return type.
3088 defines an action `Foo()` that invokes argument #2 (a function pointer)
3089 with 5, calls function `Blah()`, sets the value pointed to by argument
3090 #1 to 0, and returns argument #0.
3092 For more convenience and flexibility, you can also use the following
3093 pre-defined symbols in the body of `ACTION`:
3095 | `argK_type` | The type of the K-th (0-based) argument of the mock function |
3096 |:------------|:-------------------------------------------------------------|
3097 | `args` | All arguments of the mock function as a tuple |
3098 | `args_type` | The type of all arguments of the mock function as a tuple |
3099 | `return_type` | The return type of the mock function |
3100 | `function_type` | The type of the mock function |
3102 For example, when using an `ACTION` as a stub action for mock function:
3104 int DoSomething(bool flag, int* ptr);
3107 | **Pre-defined Symbol** | **Is Bound To** |
3108 |:-----------------------|:----------------|
3109 | `arg0` | the value of `flag` |
3110 | `arg0_type` | the type `bool` |
3111 | `arg1` | the value of `ptr` |
3112 | `arg1_type` | the type `int*` |
3113 | `args` | the tuple `(flag, ptr)` |
3114 | `args_type` | the type `std::tr1::tuple<bool, int*>` |
3115 | `return_type` | the type `int` |
3116 | `function_type` | the type `int(bool, int*)` |
3118 ## Writing New Parameterized Actions Quickly ##
3120 Sometimes you'll want to parameterize an action you define. For that
3121 we have another macro
3123 ACTION_P(name, param) { statements; }
3128 ACTION_P(Add, n) { return arg0 + n; }
3130 will allow you to write
3132 // Returns argument #0 + 5.
3133 ... WillOnce(Add(5));
3136 For convenience, we use the term _arguments_ for the values used to
3137 invoke the mock function, and the term _parameters_ for the values
3138 used to instantiate an action.
3140 Note that you don't need to provide the type of the parameter either.
3141 Suppose the parameter is named `param`, you can also use the
3142 Google-Mock-defined symbol `param_type` to refer to the type of the
3143 parameter as inferred by the compiler. For example, in the body of
3144 `ACTION_P(Add, n)` above, you can write `n_type` for the type of `n`.
3146 Google Mock also provides `ACTION_P2`, `ACTION_P3`, and etc to support
3147 multi-parameter actions. For example,
3149 ACTION_P2(ReturnDistanceTo, x, y) {
3150 double dx = arg0 - x;
3151 double dy = arg1 - y;
3152 return sqrt(dx*dx + dy*dy);
3157 ... WillOnce(ReturnDistanceTo(5.0, 26.5));
3160 You can view `ACTION` as a degenerated parameterized action where the
3161 number of parameters is 0.
3163 You can also easily define actions overloaded on the number of parameters:
3165 ACTION_P(Plus, a) { ... }
3166 ACTION_P2(Plus, a, b) { ... }
3169 ## Restricting the Type of an Argument or Parameter in an ACTION ##
3171 For maximum brevity and reusability, the `ACTION*` macros don't ask
3172 you to provide the types of the mock function arguments and the action
3173 parameters. Instead, we let the compiler infer the types for us.
3175 Sometimes, however, we may want to be more explicit about the types.
3176 There are several tricks to do that. For example:
3179 // Makes sure arg0 can be converted to int.
3181 ... use n instead of arg0 here ...
3184 ACTION_P(Bar, param) {
3185 // Makes sure the type of arg1 is const char*.
3186 ::testing::StaticAssertTypeEq<const char*, arg1_type>();
3188 // Makes sure param can be converted to bool.
3192 where `StaticAssertTypeEq` is a compile-time assertion in Google Test
3193 that verifies two types are the same.
3195 ## Writing New Action Templates Quickly ##
3197 Sometimes you want to give an action explicit template parameters that
3198 cannot be inferred from its value parameters. `ACTION_TEMPLATE()`
3199 supports that and can be viewed as an extension to `ACTION()` and
3204 ACTION_TEMPLATE(ActionName,
3205 HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m),
3206 AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; }
3209 defines an action template that takes _m_ explicit template parameters
3210 and _n_ value parameters, where _m_ is between 1 and 10, and _n_ is
3211 between 0 and 10. `name_i` is the name of the i-th template
3212 parameter, and `kind_i` specifies whether it's a `typename`, an
3213 integral constant, or a template. `p_i` is the name of the i-th value
3218 // DuplicateArg<k, T>(output) converts the k-th argument of the mock
3219 // function to type T and copies it to *output.
3220 ACTION_TEMPLATE(DuplicateArg,
3221 // Note the comma between int and k:
3222 HAS_2_TEMPLATE_PARAMS(int, k, typename, T),
3223 AND_1_VALUE_PARAMS(output)) {
3224 *output = T(std::tr1::get<k>(args));
3228 To create an instance of an action template, write:
3230 ActionName<t1, ..., t_m>(v1, ..., v_n)
3232 where the `t`s are the template arguments and the
3233 `v`s are the value arguments. The value argument
3234 types are inferred by the compiler. For example:
3239 EXPECT_CALL(mock, Foo(_, _))
3240 .WillOnce(DuplicateArg<1, unsigned char>(&n));
3243 If you want to explicitly specify the value argument types, you can
3244 provide additional template arguments:
3246 ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n)
3248 where `u_i` is the desired type of `v_i`.
3250 `ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the
3251 number of value parameters, but not on the number of template
3252 parameters. Without the restriction, the meaning of the following is
3256 OverloadedAction<int, bool>(x);
3259 Are we using a single-template-parameter action where `bool` refers to
3260 the type of `x`, or a two-template-parameter action where the compiler
3261 is asked to infer the type of `x`?
3263 ## Using the ACTION Object's Type ##
3265 If you are writing a function that returns an `ACTION` object, you'll
3266 need to know its type. The type depends on the macro used to define
3267 the action and the parameter types. The rule is relatively simple:
3268 | **Given Definition** | **Expression** | **Has Type** |
3269 |:---------------------|:---------------|:-------------|
3270 | `ACTION(Foo)` | `Foo()` | `FooAction` |
3271 | `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` |
3272 | `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` |
3273 | `ACTION_TEMPLATE(Bar, HAS_m_TEMPLATE_PARAMS(...), AND_1_VALUE_PARAMS(p1))` | `Bar<t1, ..., t_m>(int_value)` | `FooActionP<t1, ..., t_m, int>` |
3274 | `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` |
3275 | `ACTION_TEMPLATE(Baz, HAS_m_TEMPLATE_PARAMS(...), AND_2_VALUE_PARAMS(p1, p2))` | `Baz<t1, ..., t_m>(bool_value, int_value)` | `FooActionP2<t1, ..., t_m, bool, int>` |
3278 Note that we have to pick different suffixes (`Action`, `ActionP`,
3279 `ActionP2`, and etc) for actions with different numbers of value
3280 parameters, or the action definitions cannot be overloaded on the
3283 ## Writing New Monomorphic Actions ##
3285 While the `ACTION*` macros are very convenient, sometimes they are
3286 inappropriate. For example, despite the tricks shown in the previous
3287 recipes, they don't let you directly specify the types of the mock
3288 function arguments and the action parameters, which in general leads
3289 to unoptimized compiler error messages that can baffle unfamiliar
3290 users. They also don't allow overloading actions based on parameter
3291 types without jumping through some hoops.
3293 An alternative to the `ACTION*` macros is to implement
3294 `::testing::ActionInterface<F>`, where `F` is the type of the mock
3295 function in which the action will be used. For example:
3298 template <typename F>class ActionInterface {
3300 virtual ~ActionInterface();
3302 // Performs the action. Result is the return type of function type
3303 // F, and ArgumentTuple is the tuple of arguments of F.
3305 // For example, if F is int(bool, const string&), then Result would
3306 // be int, and ArgumentTuple would be tr1::tuple<bool, const string&>.
3307 virtual Result Perform(const ArgumentTuple& args) = 0;
3311 using ::testing::Action;
3312 using ::testing::ActionInterface;
3313 using ::testing::MakeAction;
3315 typedef int IncrementMethod(int*);
3317 class IncrementArgumentAction : public ActionInterface<IncrementMethod> {
3319 virtual int Perform(const tr1::tuple<int*>& args) {
3320 int* p = tr1::get<0>(args); // Grabs the first argument.
3325 Action<IncrementMethod> IncrementArgument() {
3326 return MakeAction(new IncrementArgumentAction);
3330 EXPECT_CALL(foo, Baz(_))
3331 .WillOnce(IncrementArgument());
3334 foo.Baz(&n); // Should return 5 and change n to 6.
3337 ## Writing New Polymorphic Actions ##
3339 The previous recipe showed you how to define your own action. This is
3340 all good, except that you need to know the type of the function in
3341 which the action will be used. Sometimes that can be a problem. For
3342 example, if you want to use the action in functions with _different_
3343 types (e.g. like `Return()` and `SetArgPointee()`).
3345 If an action can be used in several types of mock functions, we say
3346 it's _polymorphic_. The `MakePolymorphicAction()` function template
3347 makes it easy to define such an action:
3352 template <typename Impl>
3353 PolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl);
3355 } // namespace testing
3358 As an example, let's define an action that returns the second argument
3359 in the mock function's argument list. The first step is to define an
3360 implementation class:
3363 class ReturnSecondArgumentAction {
3365 template <typename Result, typename ArgumentTuple>
3366 Result Perform(const ArgumentTuple& args) const {
3367 // To get the i-th (0-based) argument, use tr1::get<i>(args).
3368 return tr1::get<1>(args);
3373 This implementation class does _not_ need to inherit from any
3374 particular class. What matters is that it must have a `Perform()`
3375 method template. This method template takes the mock function's
3376 arguments as a tuple in a **single** argument, and returns the result of
3377 the action. It can be either `const` or not, but must be invokable
3378 with exactly one template argument, which is the result type. In other
3379 words, you must be able to call `Perform<R>(args)` where `R` is the
3380 mock function's return type and `args` is its arguments in a tuple.
3382 Next, we use `MakePolymorphicAction()` to turn an instance of the
3383 implementation class into the polymorphic action we need. It will be
3384 convenient to have a wrapper for this:
3387 using ::testing::MakePolymorphicAction;
3388 using ::testing::PolymorphicAction;
3390 PolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() {
3391 return MakePolymorphicAction(ReturnSecondArgumentAction());
3395 Now, you can use this polymorphic action the same way you use the
3401 class MockFoo : public Foo {
3403 MOCK_METHOD2(DoThis, int(bool flag, int n));
3404 MOCK_METHOD3(DoThat, string(int x, const char* str1, const char* str2));
3409 EXPECT_CALL(foo, DoThis(_, _))
3410 .WillOnce(ReturnSecondArgument());
3411 EXPECT_CALL(foo, DoThat(_, _, _))
3412 .WillOnce(ReturnSecondArgument());
3414 foo.DoThis(true, 5); // Will return 5.
3415 foo.DoThat(1, "Hi", "Bye"); // Will return "Hi".
3418 ## Teaching Google Mock How to Print Your Values ##
3420 When an uninteresting or unexpected call occurs, Google Mock prints the
3421 argument values and the stack trace to help you debug. Assertion
3422 macros like `EXPECT_THAT` and `EXPECT_EQ` also print the values in
3423 question when the assertion fails. Google Mock and Google Test do this using
3424 Google Test's user-extensible value printer.
3426 This printer knows how to print built-in C++ types, native arrays, STL
3427 containers, and any type that supports the `<<` operator. For other
3428 types, it prints the raw bytes in the value and hopes that you the
3429 user can figure it out.
3430 [Google Test's advanced guide](http://code.google.com/p/googletest/wiki/AdvancedGuide#Teaching_Google_Test_How_to_Print_Your_Values)
3431 explains how to extend the printer to do a better job at
3432 printing your particular type than to dump the bytes.