3 You can find recipes for using Google Mock here. If you haven't yet,
4 please read the [ForDummies](V1_6_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 ## Nice Mocks and Strict Mocks ##
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** when using this feature, as the
301 decision you make applies to **all** future changes to the mock
302 class. If an important change is made in the interface you are mocking
303 (and thus in the mock class), it could break your tests (if you use
304 `StrictMock`) or let bugs pass through without a warning (if you use
305 `NiceMock`). Therefore, try to specify the mock's behavior using
306 explicit `EXPECT_CALL` first, and only turn to `NiceMock` or
307 `StrictMock` as the last resort.
309 ## Simplifying the Interface without Breaking Existing Code ##
311 Sometimes a method has a long list of arguments that is mostly
312 uninteresting. For example,
318 virtual void send(LogSeverity severity, const char* full_filename,
319 const char* base_filename, int line,
320 const struct tm* tm_time,
321 const char* message, size_t message_len) = 0;
325 This method's argument list is lengthy and hard to work with (let's
326 say that the `message` argument is not even 0-terminated). If we mock
327 it as is, using the mock will be awkward. If, however, we try to
328 simplify this interface, we'll need to fix all clients depending on
329 it, which is often infeasible.
331 The trick is to re-dispatch the method in the mock class:
334 class ScopedMockLog : public LogSink {
337 virtual void send(LogSeverity severity, const char* full_filename,
338 const char* base_filename, int line, const tm* tm_time,
339 const char* message, size_t message_len) {
340 // We are only interested in the log severity, full file name, and
342 Log(severity, full_filename, std::string(message, message_len));
345 // Implements the mock method:
347 // void Log(LogSeverity severity,
348 // const string& file_path,
349 // const string& message);
350 MOCK_METHOD3(Log, void(LogSeverity severity, const string& file_path,
351 const string& message));
355 By defining a new mock method with a trimmed argument list, we make
356 the mock class much more user-friendly.
358 ## Alternative to Mocking Concrete Classes ##
360 Often you may find yourself using classes that don't implement
361 interfaces. In order to test your code that uses such a class (let's
362 call it `Concrete`), you may be tempted to make the methods of
363 `Concrete` virtual and then mock it.
367 Making a non-virtual function virtual is a big decision. It creates an
368 extension point where subclasses can tweak your class' behavior. This
369 weakens your control on the class because now it's harder to maintain
370 the class' invariants. You should make a function virtual only when
371 there is a valid reason for a subclass to override it.
373 Mocking concrete classes directly is problematic as it creates a tight
374 coupling between the class and the tests - any small change in the
375 class may invalidate your tests and make test maintenance a pain.
377 To avoid such problems, many programmers have been practicing "coding
378 to interfaces": instead of talking to the `Concrete` class, your code
379 would define an interface and talk to it. Then you implement that
380 interface as an adaptor on top of `Concrete`. In tests, you can easily
381 mock that interface to observe how your code is doing.
383 This technique incurs some overhead:
385 * You pay the cost of virtual function calls (usually not a problem).
386 * There is more abstraction for the programmers to learn.
388 However, it can also bring significant benefits in addition to better
391 * `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.
392 * 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.
394 Some people worry that if everyone is practicing this technique, they
395 will end up writing lots of redundant code. This concern is totally
396 understandable. However, there are two reasons why it may not be the
399 * 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.
400 * 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.
402 You need to weigh the pros and cons carefully for your particular
403 problem, but I'd like to assure you that the Java community has been
404 practicing this for a long time and it's a proven effective technique
405 applicable in a wide variety of situations. :-)
407 ## Delegating Calls to a Fake ##
409 Some times you have a non-trivial fake implementation of an
410 interface. For example:
416 virtual char DoThis(int n) = 0;
417 virtual void DoThat(const char* s, int* p) = 0;
420 class FakeFoo : public Foo {
422 virtual char DoThis(int n) {
423 return (n > 0) ? '+' :
427 virtual void DoThat(const char* s, int* p) {
433 Now you want to mock this interface such that you can set expectations
434 on it. However, you also want to use `FakeFoo` for the default
435 behavior, as duplicating it in the mock object is, well, a lot of
438 When you define the mock class using Google Mock, you can have it
439 delegate its default action to a fake class you already have, using
444 using ::testing::Invoke;
446 class MockFoo : public Foo {
448 // Normal mock method definitions using Google Mock.
449 MOCK_METHOD1(DoThis, char(int n));
450 MOCK_METHOD2(DoThat, void(const char* s, int* p));
452 // Delegates the default actions of the methods to a FakeFoo object.
453 // This must be called *before* the custom ON_CALL() statements.
454 void DelegateToFake() {
455 ON_CALL(*this, DoThis(_))
456 .WillByDefault(Invoke(&fake_, &FakeFoo::DoThis));
457 ON_CALL(*this, DoThat(_, _))
458 .WillByDefault(Invoke(&fake_, &FakeFoo::DoThat));
461 FakeFoo fake_; // Keeps an instance of the fake in the mock.
465 With that, you can use `MockFoo` in your tests as usual. Just remember
466 that if you don't explicitly set an action in an `ON_CALL()` or
467 `EXPECT_CALL()`, the fake will be called upon to do it:
474 foo.DelegateToFake(); // Enables the fake for delegation.
476 // Put your ON_CALL(foo, ...)s here, if any.
478 // No action specified, meaning to use the default action.
479 EXPECT_CALL(foo, DoThis(5));
480 EXPECT_CALL(foo, DoThat(_, _));
483 EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked.
484 foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked.
491 * If you want, you can still override the default action by providing your own `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`.
492 * In `DelegateToFake()`, you only need to delegate the methods whose fake implementation you intend to use.
493 * 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.
494 * 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.
496 Regarding the tip on mixing a mock and a fake, here's an example on
497 why it may be a bad sign: Suppose you have a class `System` for
498 low-level system operations. In particular, it does file and I/O
499 operations. And suppose you want to test how your code uses `System`
500 to do I/O, and you just want the file operations to work normally. If
501 you mock out the entire `System` class, you'll have to provide a fake
502 implementation for the file operation part, which suggests that
503 `System` is taking on too many roles.
505 Instead, you can define a `FileOps` interface and an `IOOps` interface
506 and split `System`'s functionalities into the two. Then you can mock
507 `IOOps` without mocking `FileOps`.
509 ## Delegating Calls to a Real Object ##
511 When using testing doubles (mocks, fakes, stubs, and etc), sometimes
512 their behaviors will differ from those of the real objects. This
513 difference could be either intentional (as in simulating an error such
514 that you can test the error handling code) or unintentional. If your
515 mocks have different behaviors than the real objects by mistake, you
516 could end up with code that passes the tests but fails in production.
518 You can use the _delegating-to-real_ technique to ensure that your
519 mock has the same behavior as the real object while retaining the
520 ability to validate calls. This technique is very similar to the
521 delegating-to-fake technique, the difference being that we use a real
522 object instead of a fake. Here's an example:
526 using ::testing::AtLeast;
527 using ::testing::Invoke;
529 class MockFoo : public Foo {
532 // By default, all calls are delegated to the real object.
533 ON_CALL(*this, DoThis())
534 .WillByDefault(Invoke(&real_, &Foo::DoThis));
535 ON_CALL(*this, DoThat(_))
536 .WillByDefault(Invoke(&real_, &Foo::DoThat));
539 MOCK_METHOD0(DoThis, ...);
540 MOCK_METHOD1(DoThat, ...);
549 EXPECT_CALL(mock, DoThis())
551 EXPECT_CALL(mock, DoThat("Hi"))
553 ... use mock in test ...
556 With this, Google Mock will verify that your code made the right calls
557 (with the right arguments, in the right order, called the right number
558 of times, etc), and a real object will answer the calls (so the
559 behavior will be the same as in production). This gives you the best
562 ## Delegating Calls to a Parent Class ##
564 Ideally, you should code to interfaces, whose methods are all pure
565 virtual. In reality, sometimes you do need to mock a virtual method
566 that is not pure (i.e, it already has an implementation). For example:
573 virtual void Pure(int n) = 0;
574 virtual int Concrete(const char* str) { ... }
577 class MockFoo : public Foo {
579 // Mocking a pure method.
580 MOCK_METHOD1(Pure, void(int n));
581 // Mocking a concrete method. Foo::Concrete() is shadowed.
582 MOCK_METHOD1(Concrete, int(const char* str));
586 Sometimes you may want to call `Foo::Concrete()` instead of
587 `MockFoo::Concrete()`. Perhaps you want to do it as part of a stub
588 action, or perhaps your test doesn't need to mock `Concrete()` at all
589 (but it would be oh-so painful to have to define a new mock class
590 whenever you don't need to mock one of its methods).
592 The trick is to leave a back door in your mock class for accessing the
593 real methods in the base class:
596 class MockFoo : public Foo {
598 // Mocking a pure method.
599 MOCK_METHOD1(Pure, void(int n));
600 // Mocking a concrete method. Foo::Concrete() is shadowed.
601 MOCK_METHOD1(Concrete, int(const char* str));
603 // Use this to call Concrete() defined in Foo.
604 int FooConcrete(const char* str) { return Foo::Concrete(str); }
608 Now, you can call `Foo::Concrete()` inside an action by:
612 using ::testing::Invoke;
614 EXPECT_CALL(foo, Concrete(_))
615 .WillOnce(Invoke(&foo, &MockFoo::FooConcrete));
618 or tell the mock object that you don't want to mock `Concrete()`:
621 using ::testing::Invoke;
623 ON_CALL(foo, Concrete(_))
624 .WillByDefault(Invoke(&foo, &MockFoo::FooConcrete));
627 (Why don't we just write `Invoke(&foo, &Foo::Concrete)`? If you do
628 that, `MockFoo::Concrete()` will be called (and cause an infinite
629 recursion) since `Foo::Concrete()` is virtual. That's just how C++
634 ## Matching Argument Values Exactly ##
636 You can specify exactly which arguments a mock method is expecting:
639 using ::testing::Return;
641 EXPECT_CALL(foo, DoThis(5))
642 .WillOnce(Return('a'));
643 EXPECT_CALL(foo, DoThat("Hello", bar));
646 ## Using Simple Matchers ##
648 You can use matchers to match arguments that have a certain property:
652 using ::testing::NotNull;
653 using ::testing::Return;
655 EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5.
656 .WillOnce(Return('a'));
657 EXPECT_CALL(foo, DoThat("Hello", NotNull()));
658 // The second argument must not be NULL.
661 A frequently used matcher is `_`, which matches anything:
665 using ::testing::NotNull;
667 EXPECT_CALL(foo, DoThat(_, NotNull()));
670 ## Combining Matchers ##
672 You can build complex matchers from existing ones using `AllOf()`,
673 `AnyOf()`, and `Not()`:
676 using ::testing::AllOf;
678 using ::testing::HasSubstr;
680 using ::testing::Not;
682 // The argument must be > 5 and != 10.
683 EXPECT_CALL(foo, DoThis(AllOf(Gt(5),
686 // The first argument must not contain sub-string "blah".
687 EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")),
691 ## Casting Matchers ##
693 Google Mock matchers are statically typed, meaning that the compiler
694 can catch your mistake if you use a matcher of the wrong type (for
695 example, if you use `Eq(5)` to match a `string` argument). Good for
698 Sometimes, however, you know what you're doing and want the compiler
699 to give you some slack. One example is that you have a matcher for
700 `long` and the argument you want to match is `int`. While the two
701 types aren't exactly the same, there is nothing really wrong with
702 using a `Matcher<long>` to match an `int` - after all, we can first
703 convert the `int` argument to a `long` before giving it to the
706 To support this need, Google Mock gives you the
707 `SafeMatcherCast<T>(m)` function. It casts a matcher `m` to type
708 `Matcher<T>`. To ensure safety, Google Mock checks that (let `U` be the
711 1. Type `T` can be implicitly cast to type `U`;
712 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
713 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).
715 The code won't compile if any of these conditions isn't met.
720 using ::testing::SafeMatcherCast;
722 // A base class and a child class.
724 class Derived : public Base { ... };
726 class MockFoo : public Foo {
728 MOCK_METHOD1(DoThis, void(Derived* derived));
733 // m is a Matcher<Base*> we got from somewhere.
734 EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m)));
737 If you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar
738 function `MatcherCast<T>(m)`. The difference is that `MatcherCast` works
739 as long as you can `static_cast` type `T` to type `U`.
741 `MatcherCast` essentially lets you bypass C++'s type system
742 (`static_cast` isn't always safe as it could throw away information,
743 for example), so be careful not to misuse/abuse it.
745 ## Selecting Between Overloaded Functions ##
747 If you expect an overloaded function to be called, the compiler may
748 need some help on which overloaded version it is.
750 To disambiguate functions overloaded on the const-ness of this object,
751 use the `Const()` argument wrapper.
754 using ::testing::ReturnRef;
756 class MockFoo : public Foo {
758 MOCK_METHOD0(GetBar, Bar&());
759 MOCK_CONST_METHOD0(GetBar, const Bar&());
765 EXPECT_CALL(foo, GetBar()) // The non-const GetBar().
766 .WillOnce(ReturnRef(bar1));
767 EXPECT_CALL(Const(foo), GetBar()) // The const GetBar().
768 .WillOnce(ReturnRef(bar2));
771 (`Const()` is defined by Google Mock and returns a `const` reference
774 To disambiguate overloaded functions with the same number of arguments
775 but different argument types, you may need to specify the exact type
776 of a matcher, either by wrapping your matcher in `Matcher<type>()`, or
777 using a matcher whose type is fixed (`TypedEq<type>`, `An<type>()`,
783 using ::testing::Matcher;
784 using ::testing::TypedEq;
786 class MockPrinter : public Printer {
788 MOCK_METHOD1(Print, void(int n));
789 MOCK_METHOD1(Print, void(char c));
792 TEST(PrinterTest, Print) {
795 EXPECT_CALL(printer, Print(An<int>())); // void Print(int);
796 EXPECT_CALL(printer, Print(Matcher<int>(Lt(5)))); // void Print(int);
797 EXPECT_CALL(printer, Print(TypedEq<char>('a'))); // void Print(char);
805 ## Performing Different Actions Based on the Arguments ##
807 When a mock method is called, the _last_ matching expectation that's
808 still active will be selected (think "newer overrides older"). So, you
809 can make a method do different things depending on its argument values
815 using ::testing::Return;
818 EXPECT_CALL(foo, DoThis(_))
819 .WillRepeatedly(Return('b'));
821 // The more specific case.
822 EXPECT_CALL(foo, DoThis(Lt(5)))
823 .WillRepeatedly(Return('a'));
826 Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will
827 be returned; otherwise `'b'` will be returned.
829 ## Matching Multiple Arguments as a Whole ##
831 Sometimes it's not enough to match the arguments individually. For
832 example, we may want to say that the first argument must be less than
833 the second argument. The `With()` clause allows us to match
834 all arguments of a mock function as a whole. For example,
841 EXPECT_CALL(foo, InRange(Ne(0), _))
845 says that the first argument of `InRange()` must not be 0, and must be
846 less than the second argument.
848 The expression inside `With()` must be a matcher of type
849 `Matcher<tr1::tuple<A1, ..., An> >`, where `A1`, ..., `An` are the
850 types of the function arguments.
852 You can also write `AllArgs(m)` instead of `m` inside `.With()`. The
853 two forms are equivalent, but `.With(AllArgs(Lt()))` is more readable
856 You can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments
857 (as a tuple) against `m`. For example,
861 using ::testing::AllOf;
862 using ::testing::Args;
865 EXPECT_CALL(foo, Blah(_, _, _))
866 .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt())));
869 says that `Blah()` will be called with arguments `x`, `y`, and `z` where
872 As a convenience and example, Google Mock provides some matchers for
873 2-tuples, including the `Lt()` matcher above. See the [CheatSheet](V1_6_CheatSheet.md) for
876 Note that if you want to pass the arguments to a predicate of your own
877 (e.g. `.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be
878 written to take a `tr1::tuple` as its argument; Google Mock will pass the `n`
879 selected arguments as _one_ single tuple to the predicate.
881 ## Using Matchers as Predicates ##
883 Have you noticed that a matcher is just a fancy predicate that also
884 knows how to describe itself? Many existing algorithms take predicates
885 as arguments (e.g. those defined in STL's `<algorithm>` header), and
886 it would be a shame if Google Mock matchers are not allowed to
889 Luckily, you can use a matcher where a unary predicate functor is
890 expected by wrapping it inside the `Matches()` function. For example,
898 // How many elements in v are >= 10?
899 const int count = count_if(v.begin(), v.end(), Matches(Ge(10)));
902 Since you can build complex matchers from simpler ones easily using
903 Google Mock, this gives you a way to conveniently construct composite
904 predicates (doing the same using STL's `<functional>` header is just
905 painful). For example, here's a predicate that's satisfied by any
906 number that is >= 0, <= 100, and != 50:
909 Matches(AllOf(Ge(0), Le(100), Ne(50)))
912 ## Using Matchers in Google Test Assertions ##
914 Since matchers are basically predicates that also know how to describe
915 themselves, there is a way to take advantage of them in
916 [Google Test](http://code.google.com/p/googletest/) assertions. It's
917 called `ASSERT_THAT` and `EXPECT_THAT`:
920 ASSERT_THAT(value, matcher); // Asserts that value matches matcher.
921 EXPECT_THAT(value, matcher); // The non-fatal version.
924 For example, in a Google Test test you can write:
927 #include "gmock/gmock.h"
929 using ::testing::AllOf;
932 using ::testing::MatchesRegex;
933 using ::testing::StartsWith;
936 EXPECT_THAT(Foo(), StartsWith("Hello"));
937 EXPECT_THAT(Bar(), MatchesRegex("Line \\d+"));
938 ASSERT_THAT(Baz(), AllOf(Ge(5), Le(10)));
941 which (as you can probably guess) executes `Foo()`, `Bar()`, and
942 `Baz()`, and verifies that:
944 * `Foo()` returns a string that starts with `"Hello"`.
945 * `Bar()` returns a string that matches regular expression `"Line \\d+"`.
946 * `Baz()` returns a number in the range [5, 10].
948 The nice thing about these macros is that _they read like
949 English_. They generate informative messages too. For example, if the
950 first `EXPECT_THAT()` above fails, the message will be something like:
955 Expected: starts with "Hello"
958 **Credit:** The idea of `(ASSERT|EXPECT)_THAT` was stolen from the
959 [Hamcrest](http://code.google.com/p/hamcrest/) project, which adds
960 `assertThat()` to JUnit.
962 ## Using Predicates as Matchers ##
964 Google Mock provides a built-in set of matchers. In case you find them
965 lacking, you can use an arbitray unary predicate function or functor
966 as a matcher - as long as the predicate accepts a value of the type
967 you want. You do this by wrapping the predicate inside the `Truly()`
968 function, for example:
971 using ::testing::Truly;
973 int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; }
976 // Bar() must be called with an even number.
977 EXPECT_CALL(foo, Bar(Truly(IsEven)));
980 Note that the predicate function / functor doesn't have to return
981 `bool`. It works as long as the return value can be used as the
982 condition in statement `if (condition) ...`.
984 ## Matching Arguments that Are Not Copyable ##
986 When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, Google Mock saves
987 away a copy of `bar`. When `Foo()` is called later, Google Mock
988 compares the argument to `Foo()` with the saved copy of `bar`. This
989 way, you don't need to worry about `bar` being modified or destroyed
990 after the `EXPECT_CALL()` is executed. The same is true when you use
991 matchers like `Eq(bar)`, `Le(bar)`, and so on.
993 But what if `bar` cannot be copied (i.e. has no copy constructor)? You
994 could define your own matcher function and use it with `Truly()`, as
995 the previous couple of recipes have shown. Or, you may be able to get
996 away from it if you can guarantee that `bar` won't be changed after
997 the `EXPECT_CALL()` is executed. Just tell Google Mock that it should
998 save a reference to `bar`, instead of a copy of it. Here's how:
1001 using ::testing::Eq;
1002 using ::testing::ByRef;
1003 using ::testing::Lt;
1005 // Expects that Foo()'s argument == bar.
1006 EXPECT_CALL(mock_obj, Foo(Eq(ByRef(bar))));
1008 // Expects that Foo()'s argument < bar.
1009 EXPECT_CALL(mock_obj, Foo(Lt(ByRef(bar))));
1012 Remember: if you do this, don't change `bar` after the
1013 `EXPECT_CALL()`, or the result is undefined.
1015 ## Validating a Member of an Object ##
1017 Often a mock function takes a reference to object as an argument. When
1018 matching the argument, you may not want to compare the entire object
1019 against a fixed object, as that may be over-specification. Instead,
1020 you may need to validate a certain member variable or the result of a
1021 certain getter method of the object. You can do this with `Field()`
1022 and `Property()`. More specifically,
1028 is a matcher that matches a `Foo` object whose `bar` member variable
1029 satisfies matcher `m`.
1032 Property(&Foo::baz, m)
1035 is a matcher that matches a `Foo` object whose `baz()` method returns
1036 a value that satisfies matcher `m`.
1040 > | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. |
1041 |:-----------------------------|:-----------------------------------|
1042 > | `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. |
1044 Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no
1045 argument and be declared as `const`.
1047 BTW, `Field()` and `Property()` can also match plain pointers to
1048 objects. For instance,
1051 Field(&Foo::number, Ge(3))
1054 matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`,
1055 the match will always fail regardless of the inner matcher.
1057 What if you want to validate more than one members at the same time?
1058 Remember that there is `AllOf()`.
1060 ## Validating the Value Pointed to by a Pointer Argument ##
1062 C++ functions often take pointers as arguments. You can use matchers
1063 like `NULL`, `NotNull()`, and other comparison matchers to match a
1064 pointer, but what if you want to make sure the value _pointed to_ by
1065 the pointer, instead of the pointer itself, has a certain property?
1066 Well, you can use the `Pointee(m)` matcher.
1068 `Pointee(m)` matches a pointer iff `m` matches the value the pointer
1069 points to. For example:
1072 using ::testing::Ge;
1073 using ::testing::Pointee;
1075 EXPECT_CALL(foo, Bar(Pointee(Ge(3))));
1078 expects `foo.Bar()` to be called with a pointer that points to a value
1079 greater than or equal to 3.
1081 One nice thing about `Pointee()` is that it treats a `NULL` pointer as
1082 a match failure, so you can write `Pointee(m)` instead of
1085 AllOf(NotNull(), Pointee(m))
1088 without worrying that a `NULL` pointer will crash your test.
1090 Also, did we tell you that `Pointee()` works with both raw pointers
1091 **and** smart pointers (`linked_ptr`, `shared_ptr`, `scoped_ptr`, and
1094 What if you have a pointer to pointer? You guessed it - you can use
1095 nested `Pointee()` to probe deeper inside the value. For example,
1096 `Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer
1097 that points to a number less than 3 (what a mouthful...).
1099 ## Testing a Certain Property of an Object ##
1101 Sometimes you want to specify that an object argument has a certain
1102 property, but there is no existing matcher that does this. If you want
1103 good error messages, you should define a matcher. If you want to do it
1104 quick and dirty, you could get away with writing an ordinary function.
1106 Let's say you have a mock function that takes an object of type `Foo`,
1107 which has an `int bar()` method and an `int baz()` method, and you
1108 want to constrain that the argument's `bar()` value plus its `baz()`
1109 value is a given number. Here's how you can define a matcher to do it:
1112 using ::testing::MatcherInterface;
1113 using ::testing::MatchResultListener;
1115 class BarPlusBazEqMatcher : public MatcherInterface<const Foo&> {
1117 explicit BarPlusBazEqMatcher(int expected_sum)
1118 : expected_sum_(expected_sum) {}
1120 virtual bool MatchAndExplain(const Foo& foo,
1121 MatchResultListener* listener) const {
1122 return (foo.bar() + foo.baz()) == expected_sum_;
1125 virtual void DescribeTo(::std::ostream* os) const {
1126 *os << "bar() + baz() equals " << expected_sum_;
1129 virtual void DescribeNegationTo(::std::ostream* os) const {
1130 *os << "bar() + baz() does not equal " << expected_sum_;
1133 const int expected_sum_;
1136 inline Matcher<const Foo&> BarPlusBazEq(int expected_sum) {
1137 return MakeMatcher(new BarPlusBazEqMatcher(expected_sum));
1142 EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...;
1145 ## Matching Containers ##
1147 Sometimes an STL container (e.g. list, vector, map, ...) is passed to
1148 a mock function and you may want to validate it. Since most STL
1149 containers support the `==` operator, you can write
1150 `Eq(expected_container)` or simply `expected_container` to match a
1153 Sometimes, though, you may want to be more flexible (for example, the
1154 first element must be an exact match, but the second element can be
1155 any positive number, and so on). Also, containers used in tests often
1156 have a small number of elements, and having to define the expected
1157 container out-of-line is a bit of a hassle.
1159 You can use the `ElementsAre()` matcher in such cases:
1163 using ::testing::ElementsAre;
1164 using ::testing::Gt;
1167 MOCK_METHOD1(Foo, void(const vector<int>& numbers));
1170 EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5)));
1173 The above matcher says that the container must have 4 elements, which
1174 must be 1, greater than 0, anything, and 5 respectively.
1176 `ElementsAre()` is overloaded to take 0 to 10 arguments. If more are
1177 needed, you can place them in a C-style array and use
1178 `ElementsAreArray()` instead:
1181 using ::testing::ElementsAreArray;
1184 // ElementsAreArray accepts an array of element values.
1185 const int expected_vector1[] = { 1, 5, 2, 4, ... };
1186 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1)));
1188 // Or, an array of element matchers.
1189 Matcher<int> expected_vector2 = { 1, Gt(2), _, 3, ... };
1190 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2)));
1193 In case the array needs to be dynamically created (and therefore the
1194 array size cannot be inferred by the compiler), you can give
1195 `ElementsAreArray()` an additional argument to specify the array size:
1198 using ::testing::ElementsAreArray;
1200 int* const expected_vector3 = new int[count];
1201 ... fill expected_vector3 with values ...
1202 EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count)));
1207 * `ElementAre*()` works with _any_ container that implements the STL iterator concept (i.e. it has a `const_iterator` type and supports `begin()/end()`) and supports `size()`, 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.
1208 * You can use nested `ElementAre*()` to match nested (multi-dimensional) containers.
1209 * If the container is passed by pointer instead of by reference, just write `Pointee(ElementsAre*(...))`.
1210 * The order of elements _matters_ for `ElementsAre*()`. Therefore don't use it with containers whose element order is undefined (e.g. `hash_map`).
1212 ## Sharing Matchers ##
1214 Under the hood, a Google Mock matcher object consists of a pointer to
1215 a ref-counted implementation object. Copying matchers is allowed and
1216 very efficient, as only the pointer is copied. When the last matcher
1217 that references the implementation object dies, the implementation
1218 object will be deleted.
1220 Therefore, if you have some complex matcher that you want to use again
1221 and again, there is no need to build it everytime. Just assign it to a
1222 matcher variable and use that variable repeatedly! For example,
1225 Matcher<int> in_range = AllOf(Gt(5), Le(10));
1226 ... use in_range as a matcher in multiple EXPECT_CALLs ...
1229 # Setting Expectations #
1231 ## Ignoring Uninteresting Calls ##
1233 If you are not interested in how a mock method is called, just don't
1234 say anything about it. In this case, if the method is ever called,
1235 Google Mock will perform its default action to allow the test program
1236 to continue. If you are not happy with the default action taken by
1237 Google Mock, you can override it using `DefaultValue<T>::Set()`
1238 (described later in this document) or `ON_CALL()`.
1240 Please note that once you expressed interest in a particular mock
1241 method (via `EXPECT_CALL()`), all invocations to it must match some
1242 expectation. If this function is called but the arguments don't match
1243 any `EXPECT_CALL()` statement, it will be an error.
1245 ## Disallowing Unexpected Calls ##
1247 If a mock method shouldn't be called at all, explicitly say so:
1252 EXPECT_CALL(foo, Bar(_))
1256 If some calls to the method are allowed, but the rest are not, just
1257 list all the expected calls:
1260 using ::testing::AnyNumber;
1261 using ::testing::Gt;
1263 EXPECT_CALL(foo, Bar(5));
1264 EXPECT_CALL(foo, Bar(Gt(10)))
1265 .Times(AnyNumber());
1268 A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()`
1269 statements will be an error.
1271 ## Expecting Ordered Calls ##
1273 Although an `EXPECT_CALL()` statement defined earlier takes precedence
1274 when Google Mock tries to match a function call with an expectation,
1275 by default calls don't have to happen in the order `EXPECT_CALL()`
1276 statements are written. For example, if the arguments match the
1277 matchers in the third `EXPECT_CALL()`, but not those in the first two,
1278 then the third expectation will be used.
1280 If you would rather have all calls occur in the order of the
1281 expectations, put the `EXPECT_CALL()` statements in a block where you
1282 define a variable of type `InSequence`:
1286 using ::testing::InSequence;
1291 EXPECT_CALL(foo, DoThis(5));
1292 EXPECT_CALL(bar, DoThat(_))
1294 EXPECT_CALL(foo, DoThis(6));
1298 In this example, we expect a call to `foo.DoThis(5)`, followed by two
1299 calls to `bar.DoThat()` where the argument can be anything, which are
1300 in turn followed by a call to `foo.DoThis(6)`. If a call occurred
1301 out-of-order, Google Mock will report an error.
1303 ## Expecting Partially Ordered Calls ##
1305 Sometimes requiring everything to occur in a predetermined order can
1306 lead to brittle tests. For example, we may care about `A` occurring
1307 before both `B` and `C`, but aren't interested in the relative order
1308 of `B` and `C`. In this case, the test should reflect our real intent,
1309 instead of being overly constraining.
1311 Google Mock allows you to impose an arbitrary DAG (directed acyclic
1312 graph) on the calls. One way to express the DAG is to use the
1313 [After](http://code.google.com/p/googlemock/wiki/V1_6_CheatSheet#The_After_Clause) clause of `EXPECT_CALL`.
1315 Another way is via the `InSequence()` clause (not the same as the
1316 `InSequence` class), which we borrowed from jMock 2. It's less
1317 flexible than `After()`, but more convenient when you have long chains
1318 of sequential calls, as it doesn't require you to come up with
1319 different names for the expectations in the chains. Here's how it
1322 If we view `EXPECT_CALL()` statements as nodes in a graph, and add an
1323 edge from node A to node B wherever A must occur before B, we can get
1324 a DAG. We use the term "sequence" to mean a directed path in this
1325 DAG. Now, if we decompose the DAG into sequences, we just need to know
1326 which sequences each `EXPECT_CALL()` belongs to in order to be able to
1327 reconstruct the orginal DAG.
1329 So, to specify the partial order on the expectations we need to do two
1330 things: first to define some `Sequence` objects, and then for each
1331 `EXPECT_CALL()` say which `Sequence` objects it is part
1332 of. Expectations in the same sequence must occur in the order they are
1333 written. For example,
1336 using ::testing::Sequence;
1340 EXPECT_CALL(foo, A())
1341 .InSequence(s1, s2);
1342 EXPECT_CALL(bar, B())
1344 EXPECT_CALL(bar, C())
1346 EXPECT_CALL(foo, D())
1350 specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A ->
1361 This means that A must occur before B and C, and C must occur before
1362 D. There's no restriction about the order other than these.
1364 ## Controlling When an Expectation Retires ##
1366 When a mock method is called, Google Mock only consider expectations
1367 that are still active. An expectation is active when created, and
1368 becomes inactive (aka _retires_) when a call that has to occur later
1369 has occurred. For example, in
1373 using ::testing::Sequence;
1377 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1
1379 .InSequence(s1, s2);
1380 EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2
1382 EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3
1386 as soon as either #2 or #3 is matched, #1 will retire. If a warning
1387 `"File too large."` is logged after this, it will be an error.
1389 Note that an expectation doesn't retire automatically when it's
1390 saturated. For example,
1395 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1396 EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2
1399 says that there will be exactly one warning with the message `"File
1400 too large."`. If the second warning contains this message too, #2 will
1401 match again and result in an upper-bound-violated error.
1403 If this is not what you want, you can ask an expectation to retire as
1404 soon as it becomes saturated:
1409 EXPECT_CALL(log, Log(WARNING, _, _)); // #1
1410 EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2
1411 .RetiresOnSaturation();
1414 Here #2 can be used only once, so if you have two warnings with the
1415 message `"File too large."`, the first will match #2 and the second
1416 will match #1 - there will be no error.
1420 ## Returning References from Mock Methods ##
1422 If a mock function's return type is a reference, you need to use
1423 `ReturnRef()` instead of `Return()` to return a result:
1426 using ::testing::ReturnRef;
1428 class MockFoo : public Foo {
1430 MOCK_METHOD0(GetBar, Bar&());
1436 EXPECT_CALL(foo, GetBar())
1437 .WillOnce(ReturnRef(bar));
1440 ## Returning Live Values from Mock Methods ##
1442 The `Return(x)` action saves a copy of `x` when the action is
1443 _created_, and always returns the same value whenever it's
1444 executed. Sometimes you may want to instead return the _live_ value of
1445 `x` (i.e. its value at the time when the action is _executed_.).
1447 If the mock function's return type is a reference, you can do it using
1448 `ReturnRef(x)`, as shown in the previous recipe ("Returning References
1449 from Mock Methods"). However, Google Mock doesn't let you use
1450 `ReturnRef()` in a mock function whose return type is not a reference,
1451 as doing that usually indicates a user error. So, what shall you do?
1453 You may be tempted to try `ByRef()`:
1456 using testing::ByRef;
1457 using testing::Return;
1459 class MockFoo : public Foo {
1461 MOCK_METHOD0(GetValue, int());
1466 EXPECT_CALL(foo, GetValue())
1467 .WillRepeatedly(Return(ByRef(x)));
1469 EXPECT_EQ(42, foo.GetValue());
1472 Unfortunately, it doesn't work here. The above code will fail with error:
1475 Value of: foo.GetValue()
1480 The reason is that `Return(value)` converts `value` to the actual
1481 return type of the mock function at the time when the action is
1482 _created_, not when it is _executed_. (This behavior was chosen for
1483 the action to be safe when `value` is a proxy object that references
1484 some temporary objects.) As a result, `ByRef(x)` is converted to an
1485 `int` value (instead of a `const int&`) when the expectation is set,
1486 and `Return(ByRef(x))` will always return 0.
1488 `ReturnPointee(pointer)` was provided to solve this problem
1489 specifically. It returns the value pointed to by `pointer` at the time
1490 the action is _executed_:
1493 using testing::ReturnPointee;
1497 EXPECT_CALL(foo, GetValue())
1498 .WillRepeatedly(ReturnPointee(&x)); // Note the & here.
1500 EXPECT_EQ(42, foo.GetValue()); // This will succeed now.
1503 ## Combining Actions ##
1505 Want to do more than one thing when a function is called? That's
1506 fine. `DoAll()` allow you to do sequence of actions every time. Only
1507 the return value of the last action in the sequence will be used.
1510 using ::testing::DoAll;
1512 class MockFoo : public Foo {
1514 MOCK_METHOD1(Bar, bool(int n));
1518 EXPECT_CALL(foo, Bar(_))
1519 .WillOnce(DoAll(action_1,
1525 ## Mocking Side Effects ##
1527 Sometimes a method exhibits its effect not via returning a value but
1528 via side effects. For example, it may change some global state or
1529 modify an output argument. To mock side effects, in general you can
1530 define your own action by implementing `::testing::ActionInterface`.
1532 If all you need to do is to change an output argument, the built-in
1533 `SetArgPointee()` action is convenient:
1536 using ::testing::SetArgPointee;
1538 class MockMutator : public Mutator {
1540 MOCK_METHOD2(Mutate, void(bool mutate, int* value));
1545 MockMutator mutator;
1546 EXPECT_CALL(mutator, Mutate(true, _))
1547 .WillOnce(SetArgPointee<1>(5));
1550 In this example, when `mutator.Mutate()` is called, we will assign 5
1551 to the `int` variable pointed to by argument #1
1554 `SetArgPointee()` conveniently makes an internal copy of the
1555 value you pass to it, removing the need to keep the value in scope and
1556 alive. The implication however is that the value must have a copy
1557 constructor and assignment operator.
1559 If the mock method also needs to return a value as well, you can chain
1560 `SetArgPointee()` with `Return()` using `DoAll()`:
1564 using ::testing::Return;
1565 using ::testing::SetArgPointee;
1567 class MockMutator : public Mutator {
1570 MOCK_METHOD1(MutateInt, bool(int* value));
1574 MockMutator mutator;
1575 EXPECT_CALL(mutator, MutateInt(_))
1576 .WillOnce(DoAll(SetArgPointee<0>(5),
1580 If the output argument is an array, use the
1581 `SetArrayArgument<N>(first, last)` action instead. It copies the
1582 elements in source range `[first, last)` to the array pointed to by
1583 the `N`-th (0-based) argument:
1586 using ::testing::NotNull;
1587 using ::testing::SetArrayArgument;
1589 class MockArrayMutator : public ArrayMutator {
1591 MOCK_METHOD2(Mutate, void(int* values, int num_values));
1596 MockArrayMutator mutator;
1597 int values[5] = { 1, 2, 3, 4, 5 };
1598 EXPECT_CALL(mutator, Mutate(NotNull(), 5))
1599 .WillOnce(SetArrayArgument<0>(values, values + 5));
1602 This also works when the argument is an output iterator:
1606 using ::testing::SeArrayArgument;
1608 class MockRolodex : public Rolodex {
1610 MOCK_METHOD1(GetNames, void(std::back_insert_iterator<vector<string> >));
1615 MockRolodex rolodex;
1616 vector<string> names;
1617 names.push_back("George");
1618 names.push_back("John");
1619 names.push_back("Thomas");
1620 EXPECT_CALL(rolodex, GetNames(_))
1621 .WillOnce(SetArrayArgument<0>(names.begin(), names.end()));
1624 ## Changing a Mock Object's Behavior Based on the State ##
1626 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:
1629 using ::testing::InSequence;
1630 using ::testing::Return;
1635 EXPECT_CALL(my_mock, IsDirty())
1636 .WillRepeatedly(Return(true));
1637 EXPECT_CALL(my_mock, Flush());
1638 EXPECT_CALL(my_mock, IsDirty())
1639 .WillRepeatedly(Return(false));
1641 my_mock.FlushIfDirty();
1644 This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called and return `false` afterwards.
1646 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:
1650 using ::testing::SaveArg;
1651 using ::testing::Return;
1653 ACTION_P(ReturnPointee, p) { return *p; }
1655 int previous_value = 0;
1656 EXPECT_CALL(my_mock, GetPrevValue())
1657 .WillRepeatedly(ReturnPointee(&previous_value));
1658 EXPECT_CALL(my_mock, UpdateValue(_))
1659 .WillRepeatedly(SaveArg<0>(&previous_value));
1660 my_mock.DoSomethingToUpdateValue();
1663 Here `my_mock.GetPrevValue()` will always return the argument of the last `UpdateValue()` call.
1665 ## Setting the Default Value for a Return Type ##
1667 If a mock method's return type is a built-in C++ type or pointer, by
1668 default it will return 0 when invoked. You only need to specify an
1669 action if this default value doesn't work for you.
1671 Sometimes, you may want to change this default value, or you may want
1672 to specify a default value for types Google Mock doesn't know
1673 about. You can do this using the `::testing::DefaultValue` class
1677 class MockFoo : public Foo {
1679 MOCK_METHOD0(CalculateBar, Bar());
1684 // Sets the default return value for type Bar.
1685 DefaultValue<Bar>::Set(default_bar);
1689 // We don't need to specify an action here, as the default
1690 // return value works for us.
1691 EXPECT_CALL(foo, CalculateBar());
1693 foo.CalculateBar(); // This should return default_bar.
1695 // Unsets the default return value.
1696 DefaultValue<Bar>::Clear();
1699 Please note that changing the default value for a type can make you
1700 tests hard to understand. We recommend you to use this feature
1701 judiciously. For example, you may want to make sure the `Set()` and
1702 `Clear()` calls are right next to the code that uses your mock.
1704 ## Setting the Default Actions for a Mock Method ##
1706 You've learned how to change the default value of a given
1707 type. However, this may be too coarse for your purpose: perhaps you
1708 have two mock methods with the same return type and you want them to
1709 have different behaviors. The `ON_CALL()` macro allows you to
1710 customize your mock's behavior at the method level:
1714 using ::testing::AnyNumber;
1715 using ::testing::Gt;
1716 using ::testing::Return;
1718 ON_CALL(foo, Sign(_))
1719 .WillByDefault(Return(-1));
1720 ON_CALL(foo, Sign(0))
1721 .WillByDefault(Return(0));
1722 ON_CALL(foo, Sign(Gt(0)))
1723 .WillByDefault(Return(1));
1725 EXPECT_CALL(foo, Sign(_))
1726 .Times(AnyNumber());
1728 foo.Sign(5); // This should return 1.
1729 foo.Sign(-9); // This should return -1.
1730 foo.Sign(0); // This should return 0.
1733 As you may have guessed, when there are more than one `ON_CALL()`
1734 statements, the news order take precedence over the older ones. In
1735 other words, the **last** one that matches the function arguments will
1736 be used. This matching order allows you to set up the common behavior
1737 in a mock object's constructor or the test fixture's set-up phase and
1738 specialize the mock's behavior later.
1740 ## Using Functions/Methods/Functors as Actions ##
1742 If the built-in actions don't suit you, you can easily use an existing
1743 function, method, or functor as an action:
1747 using ::testing::Invoke;
1749 class MockFoo : public Foo {
1751 MOCK_METHOD2(Sum, int(int x, int y));
1752 MOCK_METHOD1(ComplexJob, bool(int x));
1755 int CalculateSum(int x, int y) { return x + y; }
1759 bool ComplexJob(int x);
1765 EXPECT_CALL(foo, Sum(_, _))
1766 .WillOnce(Invoke(CalculateSum));
1767 EXPECT_CALL(foo, ComplexJob(_))
1768 .WillOnce(Invoke(&helper, &Helper::ComplexJob));
1770 foo.Sum(5, 6); // Invokes CalculateSum(5, 6).
1771 foo.ComplexJob(10); // Invokes helper.ComplexJob(10);
1774 The only requirement is that the type of the function, etc must be
1775 _compatible_ with the signature of the mock function, meaning that the
1776 latter's arguments can be implicitly converted to the corresponding
1777 arguments of the former, and the former's return type can be
1778 implicitly converted to that of the latter. So, you can invoke
1779 something whose type is _not_ exactly the same as the mock function,
1780 as long as it's safe to do so - nice, huh?
1782 ## Invoking a Function/Method/Functor Without Arguments ##
1784 `Invoke()` is very useful for doing actions that are more complex. It
1785 passes the mock function's arguments to the function or functor being
1786 invoked such that the callee has the full context of the call to work
1787 with. If the invoked function is not interested in some or all of the
1788 arguments, it can simply ignore them.
1790 Yet, a common pattern is that a test author wants to invoke a function
1791 without the arguments of the mock function. `Invoke()` allows her to
1792 do that using a wrapper function that throws away the arguments before
1793 invoking an underlining nullary function. Needless to say, this can be
1794 tedious and obscures the intent of the test.
1796 `InvokeWithoutArgs()` solves this problem. It's like `Invoke()` except
1797 that it doesn't pass the mock function's arguments to the
1798 callee. Here's an example:
1802 using ::testing::InvokeWithoutArgs;
1804 class MockFoo : public Foo {
1806 MOCK_METHOD1(ComplexJob, bool(int n));
1813 EXPECT_CALL(foo, ComplexJob(_))
1814 .WillOnce(InvokeWithoutArgs(Job1));
1816 foo.ComplexJob(10); // Invokes Job1().
1819 ## Invoking an Argument of the Mock Function ##
1821 Sometimes a mock function will receive a function pointer or a functor
1822 (in other words, a "callable") as an argument, e.g.
1825 class MockFoo : public Foo {
1827 MOCK_METHOD2(DoThis, bool(int n, bool (*fp)(int)));
1831 and you may want to invoke this callable argument:
1837 EXPECT_CALL(foo, DoThis(_, _))
1839 // Will execute (*fp)(5), where fp is the
1840 // second argument DoThis() receives.
1843 Arghh, you need to refer to a mock function argument but C++ has no
1844 lambda (yet), so you have to define your own action. :-( Or do you
1847 Well, Google Mock has an action to solve _exactly_ this problem:
1850 InvokeArgument<N>(arg_1, arg_2, ..., arg_m)
1853 will invoke the `N`-th (0-based) argument the mock function receives,
1854 with `arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is
1855 a function pointer or a functor, Google Mock handles them both.
1857 With that, you could write:
1861 using ::testing::InvokeArgument;
1863 EXPECT_CALL(foo, DoThis(_, _))
1864 .WillOnce(InvokeArgument<1>(5));
1865 // Will execute (*fp)(5), where fp is the
1866 // second argument DoThis() receives.
1869 What if the callable takes an argument by reference? No problem - just
1870 wrap it inside `ByRef()`:
1874 MOCK_METHOD1(Bar, bool(bool (*fp)(int, const Helper&)));
1877 using ::testing::ByRef;
1878 using ::testing::InvokeArgument;
1884 EXPECT_CALL(foo, Bar(_))
1885 .WillOnce(InvokeArgument<0>(5, ByRef(helper)));
1886 // ByRef(helper) guarantees that a reference to helper, not a copy of it,
1887 // will be passed to the callable.
1890 What if the callable takes an argument by reference and we do **not**
1891 wrap the argument in `ByRef()`? Then `InvokeArgument()` will _make a
1892 copy_ of the argument, and pass a _reference to the copy_, instead of
1893 a reference to the original value, to the callable. This is especially
1894 handy when the argument is a temporary value:
1898 MOCK_METHOD1(DoThat, bool(bool (*f)(const double& x, const string& s)));
1901 using ::testing::InvokeArgument;
1906 EXPECT_CALL(foo, DoThat(_))
1907 .WillOnce(InvokeArgument<0>(5.0, string("Hi")));
1908 // Will execute (*f)(5.0, string("Hi")), where f is the function pointer
1909 // DoThat() receives. Note that the values 5.0 and string("Hi") are
1910 // temporary and dead once the EXPECT_CALL() statement finishes. Yet
1911 // it's fine to perform this action later, since a copy of the values
1912 // are kept inside the InvokeArgument action.
1915 ## Ignoring an Action's Result ##
1917 Sometimes you have an action that returns _something_, but you need an
1918 action that returns `void` (perhaps you want to use it in a mock
1919 function that returns `void`, or perhaps it needs to be used in
1920 `DoAll()` and it's not the last in the list). `IgnoreResult()` lets
1921 you do that. For example:
1925 using ::testing::Invoke;
1926 using ::testing::Return;
1928 int Process(const MyData& data);
1929 string DoSomething();
1931 class MockFoo : public Foo {
1933 MOCK_METHOD1(Abc, void(const MyData& data));
1934 MOCK_METHOD0(Xyz, bool());
1939 EXPECT_CALL(foo, Abc(_))
1940 // .WillOnce(Invoke(Process));
1941 // The above line won't compile as Process() returns int but Abc() needs
1943 .WillOnce(IgnoreResult(Invoke(Process)));
1945 EXPECT_CALL(foo, Xyz())
1946 .WillOnce(DoAll(IgnoreResult(Invoke(DoSomething)),
1947 // Ignores the string DoSomething() returns.
1951 Note that you **cannot** use `IgnoreResult()` on an action that already
1952 returns `void`. Doing so will lead to ugly compiler errors.
1954 ## Selecting an Action's Arguments ##
1956 Say you have a mock function `Foo()` that takes seven arguments, and
1957 you have a custom action that you want to invoke when `Foo()` is
1958 called. Trouble is, the custom action only wants three arguments:
1962 using ::testing::Invoke;
1964 MOCK_METHOD7(Foo, bool(bool visible, const string& name, int x, int y,
1965 const map<pair<int, int>, double>& weight,
1966 double min_weight, double max_wight));
1969 bool IsVisibleInQuadrant1(bool visible, int x, int y) {
1970 return visible && x >= 0 && y >= 0;
1974 EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _))
1975 .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-(
1978 To please the compiler God, you can to define an "adaptor" that has
1979 the same signature as `Foo()` and calls the custom action with the
1984 using ::testing::Invoke;
1986 bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y,
1987 const map<pair<int, int>, double>& weight,
1988 double min_weight, double max_wight) {
1989 return IsVisibleInQuadrant1(visible, x, y);
1993 EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _))
1994 .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works.
1997 But isn't this awkward?
1999 Google Mock provides a generic _action adaptor_, so you can spend your
2000 time minding more important business than writing your own
2001 adaptors. Here's the syntax:
2004 WithArgs<N1, N2, ..., Nk>(action)
2007 creates an action that passes the arguments of the mock function at
2008 the given indices (0-based) to the inner `action` and performs
2009 it. Using `WithArgs`, our original example can be written as:
2013 using ::testing::Invoke;
2014 using ::testing::WithArgs;
2016 EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _))
2017 .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1)));
2018 // No need to define your own adaptor.
2021 For better readability, Google Mock also gives you:
2023 * `WithoutArgs(action)` when the inner `action` takes _no_ argument, and
2024 * `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes _one_ argument.
2026 As you may have realized, `InvokeWithoutArgs(...)` is just syntactic
2027 sugar for `WithoutArgs(Inovke(...))`.
2031 * The inner action used in `WithArgs` and friends does not have to be `Invoke()` -- it can be anything.
2032 * You can repeat an argument in the argument list if necessary, e.g. `WithArgs<2, 3, 3, 5>(...)`.
2033 * You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`.
2034 * 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.
2036 ## Ignoring Arguments in Action Functions ##
2038 The selecting-an-action's-arguments recipe showed us one way to make a
2039 mock function and an action with incompatible argument lists fit
2040 together. The downside is that wrapping the action in
2041 `WithArgs<...>()` can get tedious for people writing the tests.
2043 If you are defining a function, method, or functor to be used with
2044 `Invoke*()`, and you are not interested in some of its arguments, an
2045 alternative to `WithArgs` is to declare the uninteresting arguments as
2046 `Unused`. This makes the definition less cluttered and less fragile in
2047 case the types of the uninteresting arguments change. It could also
2048 increase the chance the action function can be reused. For example,
2052 MOCK_METHOD3(Foo, double(const string& label, double x, double y));
2053 MOCK_METHOD3(Bar, double(int index, double x, double y));
2060 using ::testing::Invoke;
2062 double DistanceToOriginWithLabel(const string& label, double x, double y) {
2063 return sqrt(x*x + y*y);
2066 double DistanceToOriginWithIndex(int index, double x, double y) {
2067 return sqrt(x*x + y*y);
2071 EXEPCT_CALL(mock, Foo("abc", _, _))
2072 .WillOnce(Invoke(DistanceToOriginWithLabel));
2073 EXEPCT_CALL(mock, Bar(5, _, _))
2074 .WillOnce(Invoke(DistanceToOriginWithIndex));
2081 using ::testing::Invoke;
2082 using ::testing::Unused;
2084 double DistanceToOrigin(Unused, double x, double y) {
2085 return sqrt(x*x + y*y);
2089 EXEPCT_CALL(mock, Foo("abc", _, _))
2090 .WillOnce(Invoke(DistanceToOrigin));
2091 EXEPCT_CALL(mock, Bar(5, _, _))
2092 .WillOnce(Invoke(DistanceToOrigin));
2095 ## Sharing Actions ##
2097 Just like matchers, a Google Mock action object consists of a pointer
2098 to a ref-counted implementation object. Therefore copying actions is
2099 also allowed and very efficient. When the last action that references
2100 the implementation object dies, the implementation object will be
2103 If you have some complex action that you want to use again and again,
2104 you may not have to build it from scratch everytime. If the action
2105 doesn't have an internal state (i.e. if it always does the same thing
2106 no matter how many times it has been called), you can assign it to an
2107 action variable and use that variable repeatedly. For example:
2110 Action<bool(int*)> set_flag = DoAll(SetArgPointee<0>(5),
2112 ... use set_flag in .WillOnce() and .WillRepeatedly() ...
2115 However, if the action has its own state, you may be surprised if you
2116 share the action object. Suppose you have an action factory
2117 `IncrementCounter(init)` which creates an action that increments and
2118 returns a counter whose initial value is `init`, using two actions
2119 created from the same expression and using a shared action will
2120 exihibit different behaviors. Example:
2123 EXPECT_CALL(foo, DoThis())
2124 .WillRepeatedly(IncrementCounter(0));
2125 EXPECT_CALL(foo, DoThat())
2126 .WillRepeatedly(IncrementCounter(0));
2127 foo.DoThis(); // Returns 1.
2128 foo.DoThis(); // Returns 2.
2129 foo.DoThat(); // Returns 1 - Blah() uses a different
2130 // counter than Bar()'s.
2136 Action<int()> increment = IncrementCounter(0);
2138 EXPECT_CALL(foo, DoThis())
2139 .WillRepeatedly(increment);
2140 EXPECT_CALL(foo, DoThat())
2141 .WillRepeatedly(increment);
2142 foo.DoThis(); // Returns 1.
2143 foo.DoThis(); // Returns 2.
2144 foo.DoThat(); // Returns 3 - the counter is shared.
2147 # Misc Recipes on Using Google Mock #
2149 ## Making the Compilation Faster ##
2151 Believe it or not, the _vast majority_ of the time spent on compiling
2152 a mock class is in generating its constructor and destructor, as they
2153 perform non-trivial tasks (e.g. verification of the
2154 expectations). What's more, mock methods with different signatures
2155 have different types and thus their constructors/destructors need to
2156 be generated by the compiler separately. As a result, if you mock many
2157 different types of methods, compiling your mock class can get really
2160 If you are experiencing slow compilation, you can move the definition
2161 of your mock class' constructor and destructor out of the class body
2162 and into a `.cpp` file. This way, even if you `#include` your mock
2163 class in N files, the compiler only needs to generate its constructor
2164 and destructor once, resulting in a much faster compilation.
2166 Let's illustrate the idea using an example. Here's the definition of a
2167 mock class before applying this recipe:
2172 class MockFoo : public Foo {
2174 // Since we don't declare the constructor or the destructor,
2175 // the compiler will generate them in every translation unit
2176 // where this mock class is used.
2178 MOCK_METHOD0(DoThis, int());
2179 MOCK_METHOD1(DoThat, bool(const char* str));
2180 ... more mock methods ...
2184 After the change, it would look like:
2189 class MockFoo : public Foo {
2191 // The constructor and destructor are declared, but not defined, here.
2195 MOCK_METHOD0(DoThis, int());
2196 MOCK_METHOD1(DoThat, bool(const char* str));
2197 ... more mock methods ...
2202 // File mock_foo.cpp.
2203 #include "path/to/mock_foo.h"
2205 // The definitions may appear trivial, but the functions actually do a
2206 // lot of things through the constructors/destructors of the member
2207 // variables used to implement the mock methods.
2208 MockFoo::MockFoo() {}
2209 MockFoo::~MockFoo() {}
2212 ## Forcing a Verification ##
2214 When it's being destoyed, your friendly mock object will automatically
2215 verify that all expectations on it have been satisfied, and will
2216 generate [Google Test](http://code.google.com/p/googletest/) failures
2217 if not. This is convenient as it leaves you with one less thing to
2218 worry about. That is, unless you are not sure if your mock object will
2221 How could it be that your mock object won't eventually be destroyed?
2222 Well, it might be created on the heap and owned by the code you are
2223 testing. Suppose there's a bug in that code and it doesn't delete the
2224 mock object properly - you could end up with a passing test when
2225 there's actually a bug.
2227 Using a heap checker is a good idea and can alleviate the concern, but
2228 its implementation may not be 100% reliable. So, sometimes you do want
2229 to _force_ Google Mock to verify a mock object before it is
2230 (hopefully) destructed. You can do this with
2231 `Mock::VerifyAndClearExpectations(&mock_object)`:
2234 TEST(MyServerTest, ProcessesRequest) {
2235 using ::testing::Mock;
2237 MockFoo* const foo = new MockFoo;
2238 EXPECT_CALL(*foo, ...)...;
2239 // ... other expectations ...
2241 // server now owns foo.
2242 MyServer server(foo);
2243 server.ProcessRequest(...);
2245 // In case that server's destructor will forget to delete foo,
2246 // this will verify the expectations anyway.
2247 Mock::VerifyAndClearExpectations(foo);
2248 } // server is destroyed when it goes out of scope here.
2251 **Tip:** The `Mock::VerifyAndClearExpectations()` function returns a
2252 `bool` to indicate whether the verification was successful (`true` for
2253 yes), so you can wrap that function call inside a `ASSERT_TRUE()` if
2254 there is no point going further when the verification has failed.
2256 ## Using Check Points ##
2258 Sometimes you may want to "reset" a mock object at various check
2259 points in your test: at each check point, you verify that all existing
2260 expectations on the mock object have been satisfied, and then you set
2261 some new expectations on it as if it's newly created. This allows you
2262 to work with a mock object in "phases" whose sizes are each
2265 One such scenario is that in your test's `SetUp()` function, you may
2266 want to put the object you are testing into a certain state, with the
2267 help from a mock object. Once in the desired state, you want to clear
2268 all expectations on the mock, such that in the `TEST_F` body you can
2269 set fresh expectations on it.
2271 As you may have figured out, the `Mock::VerifyAndClearExpectations()`
2272 function we saw in the previous recipe can help you here. Or, if you
2273 are using `ON_CALL()` to set default actions on the mock object and
2274 want to clear the default actions as well, use
2275 `Mock::VerifyAndClear(&mock_object)` instead. This function does what
2276 `Mock::VerifyAndClearExpectations(&mock_object)` does and returns the
2277 same `bool`, **plus** it clears the `ON_CALL()` statements on
2280 Another trick you can use to achieve the same effect is to put the
2281 expectations in sequences and insert calls to a dummy "check-point"
2282 function at specific places. Then you can verify that the mock
2283 function calls do happen at the right time. For example, if you are
2292 and want to verify that `Foo(1)` and `Foo(3)` both invoke
2293 `mock.Bar("a")`, but `Foo(2)` doesn't invoke anything. You can write:
2296 using ::testing::MockFunction;
2298 TEST(FooTest, InvokesBarCorrectly) {
2300 // Class MockFunction<F> has exactly one mock method. It is named
2301 // Call() and has type F.
2302 MockFunction<void(string check_point_name)> check;
2306 EXPECT_CALL(mock, Bar("a"));
2307 EXPECT_CALL(check, Call("1"));
2308 EXPECT_CALL(check, Call("2"));
2309 EXPECT_CALL(mock, Bar("a"));
2319 The expectation spec says that the first `Bar("a")` must happen before
2320 check point "1", the second `Bar("a")` must happen after check point "2",
2321 and nothing should happen between the two check points. The explicit
2322 check points make it easy to tell which `Bar("a")` is called by which
2325 ## Mocking Destructors ##
2327 Sometimes you want to make sure a mock object is destructed at the
2328 right time, e.g. after `bar->A()` is called but before `bar->B()` is
2329 called. We already know that you can specify constraints on the order
2330 of mock function calls, so all we need to do is to mock the destructor
2331 of the mock function.
2333 This sounds simple, except for one problem: a destructor is a special
2334 function with special syntax and special semantics, and the
2335 `MOCK_METHOD0` macro doesn't work for it:
2338 MOCK_METHOD0(~MockFoo, void()); // Won't compile!
2341 The good news is that you can use a simple pattern to achieve the same
2342 effect. First, add a mock function `Die()` to your mock class and call
2343 it in the destructor, like this:
2346 class MockFoo : public Foo {
2348 // Add the following two lines to the mock class.
2349 MOCK_METHOD0(Die, void());
2350 virtual ~MockFoo() { Die(); }
2354 (If the name `Die()` clashes with an existing symbol, choose another
2355 name.) Now, we have translated the problem of testing when a `MockFoo`
2356 object dies to testing when its `Die()` method is called:
2359 MockFoo* foo = new MockFoo;
2360 MockBar* bar = new MockBar;
2365 // Expects *foo to die after bar->A() and before bar->B().
2366 EXPECT_CALL(*bar, A());
2367 EXPECT_CALL(*foo, Die());
2368 EXPECT_CALL(*bar, B());
2374 ## Using Google Mock and Threads ##
2376 **IMPORTANT NOTE:** What we describe in this recipe is **ONLY** true on
2377 platforms where Google Mock is thread-safe. Currently these are only
2378 platforms that support the pthreads library (this includes Linux and Mac).
2379 To make it thread-safe on other platforms we only need to implement
2380 some synchronization operations in `"gtest/internal/gtest-port.h"`.
2382 In a **unit** test, it's best if you could isolate and test a piece of
2383 code in a single-threaded context. That avoids race conditions and
2384 dead locks, and makes debugging your test much easier.
2386 Yet many programs are multi-threaded, and sometimes to test something
2387 we need to pound on it from more than one thread. Google Mock works
2388 for this purpose too.
2390 Remember the steps for using a mock:
2392 1. Create a mock object `foo`.
2393 1. Set its default actions and expectations using `ON_CALL()` and `EXPECT_CALL()`.
2394 1. The code under test calls methods of `foo`.
2395 1. Optionally, verify and reset the mock.
2396 1. Destroy the mock yourself, or let the code under test destroy it. The destructor will automatically verify it.
2398 If you follow the following simple rules, your mocks and threads can
2399 live happily togeter:
2401 * Execute your _test code_ (as opposed to the code being tested) in _one_ thread. This makes your test easy to follow.
2402 * Obviously, you can do step #1 without locking.
2403 * When doing step #2 and #5, make sure no other thread is accessing `foo`. Obvious too, huh?
2404 * #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.
2406 If you violate the rules (for example, if you set expectations on a
2407 mock while another thread is calling its methods), you get undefined
2408 behavior. That's not fun, so don't do it.
2410 Google Mock guarantees that the action for a mock function is done in
2411 the same thread that called the mock function. For example, in
2414 EXPECT_CALL(mock, Foo(1))
2416 EXPECT_CALL(mock, Foo(2))
2420 if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2,
2421 Google Mock will execute `action1` in thread 1 and `action2` in thread
2424 Google Mock does _not_ impose a sequence on actions performed in
2425 different threads (doing so may create deadlocks as the actions may
2426 need to cooperate). This means that the execution of `action1` and
2427 `action2` in the above example _may_ interleave. If this is a problem,
2428 you should add proper synchronization logic to `action1` and `action2`
2429 to make the test thread-safe.
2432 Also, remember that `DefaultValue<T>` is a global resource that
2433 potentially affects _all_ living mock objects in your
2434 program. Naturally, you won't want to mess with it from multiple
2435 threads or when there still are mocks in action.
2437 ## Controlling How Much Information Google Mock Prints ##
2439 When Google Mock sees something that has the potential of being an
2440 error (e.g. a mock function with no expectation is called, a.k.a. an
2441 uninteresting call, which is allowed but perhaps you forgot to
2442 explicitly ban the call), it prints some warning messages, including
2443 the arguments of the function and the return value. Hopefully this
2444 will remind you to take a look and see if there is indeed a problem.
2446 Sometimes you are confident that your tests are correct and may not
2447 appreciate such friendly messages. Some other times, you are debugging
2448 your tests or learning about the behavior of the code you are testing,
2449 and wish you could observe every mock call that happens (including
2450 argument values and the return value). Clearly, one size doesn't fit
2453 You can control how much Google Mock tells you using the
2454 `--gmock_verbose=LEVEL` command-line flag, where `LEVEL` is a string
2455 with three possible values:
2457 * `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.
2458 * `warning`: Google Mock will print both warnings and errors (less verbose). This is the default.
2459 * `error`: Google Mock will print errors only (least verbose).
2461 Alternatively, you can adjust the value of that flag from within your
2465 ::testing::FLAGS_gmock_verbose = "error";
2468 Now, judiciously use the right flag to enable Google Mock serve you better!
2470 ## Running Tests in Emacs ##
2472 If you build and run your tests in Emacs, the source file locations of
2473 Google Mock and [Google Test](http://code.google.com/p/googletest/)
2474 errors will be highlighted. Just press `<Enter>` on one of them and
2475 you'll be taken to the offending line. Or, you can just type `C-x ``
2476 to jump to the next error.
2478 To make it even easier, you can add the following lines to your
2482 (global-set-key "\M-m" 'compile) ; m is for make
2483 (global-set-key [M-down] 'next-error)
2484 (global-set-key [M-up] '(lambda () (interactive) (next-error -1)))
2487 Then you can type `M-m` to start a build, or `M-up`/`M-down` to move
2488 back and forth between errors.
2490 ## Fusing Google Mock Source Files ##
2492 Google Mock's implementation consists of dozens of files (excluding
2493 its own tests). Sometimes you may want them to be packaged up in
2494 fewer files instead, such that you can easily copy them to a new
2495 machine and start hacking there. For this we provide an experimental
2496 Python script `fuse_gmock_files.py` in the `scripts/` directory
2497 (starting with release 1.2.0). Assuming you have Python 2.4 or above
2498 installed on your machine, just go to that directory and run
2500 python fuse_gmock_files.py OUTPUT_DIR
2503 and you should see an `OUTPUT_DIR` directory being created with files
2504 `gtest/gtest.h`, `gmock/gmock.h`, and `gmock-gtest-all.cc` in it.
2505 These three files contain everything you need to use Google Mock (and
2506 Google Test). Just copy them to anywhere you want and you are ready
2507 to write tests and use mocks. You can use the
2508 [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
2511 # Extending Google Mock #
2513 ## Writing New Matchers Quickly ##
2515 The `MATCHER*` family of macros can be used to define custom matchers
2519 MATCHER(name, description_string_expression) { statements; }
2522 will define a matcher with the given name that executes the
2523 statements, which must return a `bool` to indicate if the match
2524 succeeds. Inside the statements, you can refer to the value being
2525 matched by `arg`, and refer to its type by `arg_type`.
2527 The description string is a `string`-typed expression that documents
2528 what the matcher does, and is used to generate the failure message
2529 when the match fails. It can (and should) reference the special
2530 `bool` variable `negation`, and should evaluate to the description of
2531 the matcher when `negation` is `false`, or that of the matcher's
2532 negation when `negation` is `true`.
2534 For convenience, we allow the description string to be empty (`""`),
2535 in which case Google Mock will use the sequence of words in the
2536 matcher name as the description.
2540 MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; }
2544 // Expects mock_foo.Bar(n) to be called where n is divisible by 7.
2545 EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7()));
2549 using ::testing::Not;
2551 EXPECT_THAT(some_expression, IsDivisibleBy7());
2552 EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7()));
2554 If the above assertions fail, they will print something like:
2556 Value of: some_expression
2557 Expected: is divisible by 7
2560 Value of: some_other_expression
2561 Expected: not (is divisible by 7)
2564 where the descriptions `"is divisible by 7"` and `"not (is divisible
2565 by 7)"` are automatically calculated from the matcher name
2568 As you may have noticed, the auto-generated descriptions (especially
2569 those for the negation) may not be so great. You can always override
2570 them with a string expression of your own:
2572 MATCHER(IsDivisibleBy7, std::string(negation ? "isn't" : "is") +
2573 " divisible by 7") {
2574 return (arg % 7) == 0;
2578 Optionally, you can stream additional information to a hidden argument
2579 named `result_listener` to explain the match result. For example, a
2580 better definition of `IsDivisibleBy7` is:
2582 MATCHER(IsDivisibleBy7, "") {
2586 *result_listener << "the remainder is " << (arg % 7);
2591 With this definition, the above assertion will give a better message:
2593 Value of: some_expression
2594 Expected: is divisible by 7
2595 Actual: 27 (the remainder is 6)
2598 You should let `MatchAndExplain()` print _any additional information_
2599 that can help a user understand the match result. Note that it should
2600 explain why the match succeeds in case of a success (unless it's
2601 obvious) - this is useful when the matcher is used inside
2602 `Not()`. There is no need to print the argument value itself, as
2603 Google Mock already prints it for you.
2607 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.
2608 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.
2610 ## Writing New Parameterized Matchers Quickly ##
2612 Sometimes you'll want to define a matcher that has parameters. For that you
2615 MATCHER_P(name, param_name, description_string) { statements; }
2617 where the description string can be either `""` or a string expression
2618 that references `negation` and `param_name`.
2622 MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; }
2624 will allow you to write:
2626 EXPECT_THAT(Blah("a"), HasAbsoluteValue(n));
2628 which may lead to this message (assuming `n` is 10):
2631 Expected: has absolute value 10
2635 Note that both the matcher description and its parameter are
2636 printed, making the message human-friendly.
2638 In the matcher definition body, you can write `foo_type` to
2639 reference the type of a parameter named `foo`. For example, in the
2640 body of `MATCHER_P(HasAbsoluteValue, value)` above, you can write
2641 `value_type` to refer to the type of `value`.
2643 Google Mock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to
2644 `MATCHER_P10` to support multi-parameter matchers:
2646 MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; }
2649 Please note that the custom description string is for a particular
2650 **instance** of the matcher, where the parameters have been bound to
2651 actual values. Therefore usually you'll want the parameter values to
2652 be part of the description. Google Mock lets you do that by
2653 referencing the matcher parameters in the description string
2658 using ::testing::PrintToString;
2659 MATCHER_P2(InClosedRange, low, hi,
2660 std::string(negation ? "isn't" : "is") + " in range [" +
2661 PrintToString(low) + ", " + PrintToString(hi) + "]") {
2662 return low <= arg && arg <= hi;
2665 EXPECT_THAT(3, InClosedRange(4, 6));
2667 would generate a failure that contains the message:
2669 Expected: is in range [4, 6]
2672 If you specify `""` as the description, the failure message will
2673 contain the sequence of words in the matcher name followed by the
2674 parameter values printed as a tuple. For example,
2676 MATCHER_P2(InClosedRange, low, hi, "") { ... }
2678 EXPECT_THAT(3, InClosedRange(4, 6));
2680 would generate a failure that contains the text:
2682 Expected: in closed range (4, 6)
2685 For the purpose of typing, you can view
2687 MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... }
2691 template <typename p1_type, ..., typename pk_type>
2692 FooMatcherPk<p1_type, ..., pk_type>
2693 Foo(p1_type p1, ..., pk_type pk) { ... }
2696 When you write `Foo(v1, ..., vk)`, the compiler infers the types of
2697 the parameters `v1`, ..., and `vk` for you. If you are not happy with
2698 the result of the type inference, you can specify the types by
2699 explicitly instantiating the template, as in `Foo<long, bool>(5, false)`.
2700 As said earlier, you don't get to (or need to) specify
2701 `arg_type` as that's determined by the context in which the matcher
2704 You can assign the result of expression `Foo(p1, ..., pk)` to a
2705 variable of type `FooMatcherPk<p1_type, ..., pk_type>`. This can be
2706 useful when composing matchers. Matchers that don't have a parameter
2707 or have only one parameter have special types: you can assign `Foo()`
2708 to a `FooMatcher`-typed variable, and assign `Foo(p)` to a
2709 `FooMatcherP<p_type>`-typed variable.
2711 While you can instantiate a matcher template with reference types,
2712 passing the parameters by pointer usually makes your code more
2713 readable. If, however, you still want to pass a parameter by
2714 reference, be aware that in the failure message generated by the
2715 matcher you will see the value of the referenced object but not its
2718 You can overload matchers with different numbers of parameters:
2720 MATCHER_P(Blah, a, description_string_1) { ... }
2721 MATCHER_P2(Blah, a, b, description_string_2) { ... }
2724 While it's tempting to always use the `MATCHER*` macros when defining
2725 a new matcher, you should also consider implementing
2726 `MatcherInterface` or using `MakePolymorphicMatcher()` instead (see
2727 the recipes that follow), especially if you need to use the matcher a
2728 lot. While these approaches require more work, they give you more
2729 control on the types of the value being matched and the matcher
2730 parameters, which in general leads to better compiler error messages
2731 that pay off in the long run. They also allow overloading matchers
2732 based on parameter types (as opposed to just based on the number of
2735 ## Writing New Monomorphic Matchers ##
2737 A matcher of argument type `T` implements
2738 `::testing::MatcherInterface<T>` and does two things: it tests whether a
2739 value of type `T` matches the matcher, and can describe what kind of
2740 values it matches. The latter ability is used for generating readable
2741 error messages when expectations are violated.
2743 The interface looks like this:
2746 class MatchResultListener {
2749 // Streams x to the underlying ostream; does nothing if the ostream
2751 template <typename T>
2752 MatchResultListener& operator<<(const T& x);
2754 // Returns the underlying ostream.
2755 ::std::ostream* stream();
2758 template <typename T>
2759 class MatcherInterface {
2761 virtual ~MatcherInterface();
2763 // Returns true iff the matcher matches x; also explains the match
2764 // result to 'listener'.
2765 virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0;
2767 // Describes this matcher to an ostream.
2768 virtual void DescribeTo(::std::ostream* os) const = 0;
2770 // Describes the negation of this matcher to an ostream.
2771 virtual void DescribeNegationTo(::std::ostream* os) const;
2775 If you need a custom matcher but `Truly()` is not a good option (for
2776 example, you may not be happy with the way `Truly(predicate)`
2777 describes itself, or you may want your matcher to be polymorphic as
2778 `Eq(value)` is), you can define a matcher to do whatever you want in
2779 two steps: first implement the matcher interface, and then define a
2780 factory function to create a matcher instance. The second step is not
2781 strictly needed but it makes the syntax of using the matcher nicer.
2783 For example, you can define a matcher to test whether an `int` is
2784 divisible by 7 and then use it like this:
2786 using ::testing::MakeMatcher;
2787 using ::testing::Matcher;
2788 using ::testing::MatcherInterface;
2789 using ::testing::MatchResultListener;
2791 class DivisibleBy7Matcher : public MatcherInterface<int> {
2793 virtual bool MatchAndExplain(int n, MatchResultListener* listener) const {
2794 return (n % 7) == 0;
2797 virtual void DescribeTo(::std::ostream* os) const {
2798 *os << "is divisible by 7";
2801 virtual void DescribeNegationTo(::std::ostream* os) const {
2802 *os << "is not divisible by 7";
2806 inline Matcher<int> DivisibleBy7() {
2807 return MakeMatcher(new DivisibleBy7Matcher);
2811 EXPECT_CALL(foo, Bar(DivisibleBy7()));
2814 You may improve the matcher message by streaming additional
2815 information to the `listener` argument in `MatchAndExplain()`:
2818 class DivisibleBy7Matcher : public MatcherInterface<int> {
2820 virtual bool MatchAndExplain(int n,
2821 MatchResultListener* listener) const {
2822 const int remainder = n % 7;
2823 if (remainder != 0) {
2824 *listener << "the remainder is " << remainder;
2826 return remainder == 0;
2832 Then, `EXPECT_THAT(x, DivisibleBy7());` may general a message like this:
2835 Expected: is divisible by 7
2836 Actual: 23 (the remainder is 2)
2839 ## Writing New Polymorphic Matchers ##
2841 You've learned how to write your own matchers in the previous
2842 recipe. Just one problem: a matcher created using `MakeMatcher()` only
2843 works for one particular type of arguments. If you want a
2844 _polymorphic_ matcher that works with arguments of several types (for
2845 instance, `Eq(x)` can be used to match a `value` as long as `value` ==
2846 `x` compiles -- `value` and `x` don't have to share the same type),
2847 you can learn the trick from `"gmock/gmock-matchers.h"` but it's a bit
2850 Fortunately, most of the time you can define a polymorphic matcher
2851 easily with the help of `MakePolymorphicMatcher()`. Here's how you can
2852 define `NotNull()` as an example:
2855 using ::testing::MakePolymorphicMatcher;
2856 using ::testing::MatchResultListener;
2857 using ::testing::NotNull;
2858 using ::testing::PolymorphicMatcher;
2860 class NotNullMatcher {
2862 // To implement a polymorphic matcher, first define a COPYABLE class
2863 // that has three members MatchAndExplain(), DescribeTo(), and
2864 // DescribeNegationTo(), like the following.
2866 // In this example, we want to use NotNull() with any pointer, so
2867 // MatchAndExplain() accepts a pointer of any type as its first argument.
2868 // In general, you can define MatchAndExplain() as an ordinary method or
2869 // a method template, or even overload it.
2870 template <typename T>
2871 bool MatchAndExplain(T* p,
2872 MatchResultListener* /* listener */) const {
2876 // Describes the property of a value matching this matcher.
2877 void DescribeTo(::std::ostream* os) const { *os << "is not NULL"; }
2879 // Describes the property of a value NOT matching this matcher.
2880 void DescribeNegationTo(::std::ostream* os) const { *os << "is NULL"; }
2883 // To construct a polymorphic matcher, pass an instance of the class
2884 // to MakePolymorphicMatcher(). Note the return type.
2885 inline PolymorphicMatcher<NotNullMatcher> NotNull() {
2886 return MakePolymorphicMatcher(NotNullMatcher());
2890 EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer.
2893 **Note:** Your polymorphic matcher class does **not** need to inherit from
2894 `MatcherInterface` or any other class, and its methods do **not** need
2897 Like in a monomorphic matcher, you may explain the match result by
2898 streaming additional information to the `listener` argument in
2899 `MatchAndExplain()`.
2901 ## Writing New Cardinalities ##
2903 A cardinality is used in `Times()` to tell Google Mock how many times
2904 you expect a call to occur. It doesn't have to be exact. For example,
2905 you can say `AtLeast(5)` or `Between(2, 4)`.
2907 If the built-in set of cardinalities doesn't suit you, you are free to
2908 define your own by implementing the following interface (in namespace
2912 class CardinalityInterface {
2914 virtual ~CardinalityInterface();
2916 // Returns true iff call_count calls will satisfy this cardinality.
2917 virtual bool IsSatisfiedByCallCount(int call_count) const = 0;
2919 // Returns true iff call_count calls will saturate this cardinality.
2920 virtual bool IsSaturatedByCallCount(int call_count) const = 0;
2922 // Describes self to an ostream.
2923 virtual void DescribeTo(::std::ostream* os) const = 0;
2927 For example, to specify that a call must occur even number of times,
2931 using ::testing::Cardinality;
2932 using ::testing::CardinalityInterface;
2933 using ::testing::MakeCardinality;
2935 class EvenNumberCardinality : public CardinalityInterface {
2937 virtual bool IsSatisfiedByCallCount(int call_count) const {
2938 return (call_count % 2) == 0;
2941 virtual bool IsSaturatedByCallCount(int call_count) const {
2945 virtual void DescribeTo(::std::ostream* os) const {
2946 *os << "called even number of times";
2950 Cardinality EvenNumber() {
2951 return MakeCardinality(new EvenNumberCardinality);
2955 EXPECT_CALL(foo, Bar(3))
2956 .Times(EvenNumber());
2959 ## Writing New Actions Quickly ##
2961 If the built-in actions don't work for you, and you find it
2962 inconvenient to use `Invoke()`, you can use a macro from the `ACTION*`
2963 family to quickly define a new action that can be used in your code as
2964 if it's a built-in action.
2968 ACTION(name) { statements; }
2970 in a namespace scope (i.e. not inside a class or function), you will
2971 define an action with the given name that executes the statements.
2972 The value returned by `statements` will be used as the return value of
2973 the action. Inside the statements, you can refer to the K-th
2974 (0-based) argument of the mock function as `argK`. For example:
2976 ACTION(IncrementArg1) { return ++(*arg1); }
2980 ... WillOnce(IncrementArg1());
2983 Note that you don't need to specify the types of the mock function
2984 arguments. Rest assured that your code is type-safe though:
2985 you'll get a compiler error if `*arg1` doesn't support the `++`
2986 operator, or if the type of `++(*arg1)` isn't compatible with the mock
2987 function's return type.
2998 defines an action `Foo()` that invokes argument #2 (a function pointer)
2999 with 5, calls function `Blah()`, sets the value pointed to by argument
3000 #1 to 0, and returns argument #0.
3002 For more convenience and flexibility, you can also use the following
3003 pre-defined symbols in the body of `ACTION`:
3005 | `argK_type` | The type of the K-th (0-based) argument of the mock function |
3006 |:------------|:-------------------------------------------------------------|
3007 | `args` | All arguments of the mock function as a tuple |
3008 | `args_type` | The type of all arguments of the mock function as a tuple |
3009 | `return_type` | The return type of the mock function |
3010 | `function_type` | The type of the mock function |
3012 For example, when using an `ACTION` as a stub action for mock function:
3014 int DoSomething(bool flag, int* ptr);
3017 | **Pre-defined Symbol** | **Is Bound To** |
3018 |:-----------------------|:----------------|
3019 | `arg0` | the value of `flag` |
3020 | `arg0_type` | the type `bool` |
3021 | `arg1` | the value of `ptr` |
3022 | `arg1_type` | the type `int*` |
3023 | `args` | the tuple `(flag, ptr)` |
3024 | `args_type` | the type `std::tr1::tuple<bool, int*>` |
3025 | `return_type` | the type `int` |
3026 | `function_type` | the type `int(bool, int*)` |
3028 ## Writing New Parameterized Actions Quickly ##
3030 Sometimes you'll want to parameterize an action you define. For that
3031 we have another macro
3033 ACTION_P(name, param) { statements; }
3038 ACTION_P(Add, n) { return arg0 + n; }
3040 will allow you to write
3042 // Returns argument #0 + 5.
3043 ... WillOnce(Add(5));
3046 For convenience, we use the term _arguments_ for the values used to
3047 invoke the mock function, and the term _parameters_ for the values
3048 used to instantiate an action.
3050 Note that you don't need to provide the type of the parameter either.
3051 Suppose the parameter is named `param`, you can also use the
3052 Google-Mock-defined symbol `param_type` to refer to the type of the
3053 parameter as inferred by the compiler. For example, in the body of
3054 `ACTION_P(Add, n)` above, you can write `n_type` for the type of `n`.
3056 Google Mock also provides `ACTION_P2`, `ACTION_P3`, and etc to support
3057 multi-parameter actions. For example,
3059 ACTION_P2(ReturnDistanceTo, x, y) {
3060 double dx = arg0 - x;
3061 double dy = arg1 - y;
3062 return sqrt(dx*dx + dy*dy);
3067 ... WillOnce(ReturnDistanceTo(5.0, 26.5));
3070 You can view `ACTION` as a degenerated parameterized action where the
3071 number of parameters is 0.
3073 You can also easily define actions overloaded on the number of parameters:
3075 ACTION_P(Plus, a) { ... }
3076 ACTION_P2(Plus, a, b) { ... }
3079 ## Restricting the Type of an Argument or Parameter in an ACTION ##
3081 For maximum brevity and reusability, the `ACTION*` macros don't ask
3082 you to provide the types of the mock function arguments and the action
3083 parameters. Instead, we let the compiler infer the types for us.
3085 Sometimes, however, we may want to be more explicit about the types.
3086 There are several tricks to do that. For example:
3089 // Makes sure arg0 can be converted to int.
3091 ... use n instead of arg0 here ...
3094 ACTION_P(Bar, param) {
3095 // Makes sure the type of arg1 is const char*.
3096 ::testing::StaticAssertTypeEq<const char*, arg1_type>();
3098 // Makes sure param can be converted to bool.
3102 where `StaticAssertTypeEq` is a compile-time assertion in Google Test
3103 that verifies two types are the same.
3105 ## Writing New Action Templates Quickly ##
3107 Sometimes you want to give an action explicit template parameters that
3108 cannot be inferred from its value parameters. `ACTION_TEMPLATE()`
3109 supports that and can be viewed as an extension to `ACTION()` and
3114 ACTION_TEMPLATE(ActionName,
3115 HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m),
3116 AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; }
3119 defines an action template that takes _m_ explicit template parameters
3120 and _n_ value parameters, where _m_ is between 1 and 10, and _n_ is
3121 between 0 and 10. `name_i` is the name of the i-th template
3122 parameter, and `kind_i` specifies whether it's a `typename`, an
3123 integral constant, or a template. `p_i` is the name of the i-th value
3128 // DuplicateArg<k, T>(output) converts the k-th argument of the mock
3129 // function to type T and copies it to *output.
3130 ACTION_TEMPLATE(DuplicateArg,
3131 // Note the comma between int and k:
3132 HAS_2_TEMPLATE_PARAMS(int, k, typename, T),
3133 AND_1_VALUE_PARAMS(output)) {
3134 *output = T(std::tr1::get<k>(args));
3138 To create an instance of an action template, write:
3140 ActionName<t1, ..., t_m>(v1, ..., v_n)
3142 where the `t`s are the template arguments and the
3143 `v`s are the value arguments. The value argument
3144 types are inferred by the compiler. For example:
3149 EXPECT_CALL(mock, Foo(_, _))
3150 .WillOnce(DuplicateArg<1, unsigned char>(&n));
3153 If you want to explicitly specify the value argument types, you can
3154 provide additional template arguments:
3156 ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n)
3158 where `u_i` is the desired type of `v_i`.
3160 `ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the
3161 number of value parameters, but not on the number of template
3162 parameters. Without the restriction, the meaning of the following is
3166 OverloadedAction<int, bool>(x);
3169 Are we using a single-template-parameter action where `bool` refers to
3170 the type of `x`, or a two-template-parameter action where the compiler
3171 is asked to infer the type of `x`?
3173 ## Using the ACTION Object's Type ##
3175 If you are writing a function that returns an `ACTION` object, you'll
3176 need to know its type. The type depends on the macro used to define
3177 the action and the parameter types. The rule is relatively simple:
3178 | **Given Definition** | **Expression** | **Has Type** |
3179 |:---------------------|:---------------|:-------------|
3180 | `ACTION(Foo)` | `Foo()` | `FooAction` |
3181 | `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` |
3182 | `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` |
3183 | `ACTION_TEMPLATE(Bar, HAS_m_TEMPLATE_PARAMS(...), AND_1_VALUE_PARAMS(p1))` | `Bar<t1, ..., t_m>(int_value)` | `FooActionP<t1, ..., t_m, int>` |
3184 | `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` |
3185 | `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>` |
3188 Note that we have to pick different suffixes (`Action`, `ActionP`,
3189 `ActionP2`, and etc) for actions with different numbers of value
3190 parameters, or the action definitions cannot be overloaded on the
3193 ## Writing New Monomorphic Actions ##
3195 While the `ACTION*` macros are very convenient, sometimes they are
3196 inappropriate. For example, despite the tricks shown in the previous
3197 recipes, they don't let you directly specify the types of the mock
3198 function arguments and the action parameters, which in general leads
3199 to unoptimized compiler error messages that can baffle unfamiliar
3200 users. They also don't allow overloading actions based on parameter
3201 types without jumping through some hoops.
3203 An alternative to the `ACTION*` macros is to implement
3204 `::testing::ActionInterface<F>`, where `F` is the type of the mock
3205 function in which the action will be used. For example:
3208 template <typename F>class ActionInterface {
3210 virtual ~ActionInterface();
3212 // Performs the action. Result is the return type of function type
3213 // F, and ArgumentTuple is the tuple of arguments of F.
3215 // For example, if F is int(bool, const string&), then Result would
3216 // be int, and ArgumentTuple would be tr1::tuple<bool, const string&>.
3217 virtual Result Perform(const ArgumentTuple& args) = 0;
3221 using ::testing::Action;
3222 using ::testing::ActionInterface;
3223 using ::testing::MakeAction;
3225 typedef int IncrementMethod(int*);
3227 class IncrementArgumentAction : public ActionInterface<IncrementMethod> {
3229 virtual int Perform(const tr1::tuple<int*>& args) {
3230 int* p = tr1::get<0>(args); // Grabs the first argument.
3235 Action<IncrementMethod> IncrementArgument() {
3236 return MakeAction(new IncrementArgumentAction);
3240 EXPECT_CALL(foo, Baz(_))
3241 .WillOnce(IncrementArgument());
3244 foo.Baz(&n); // Should return 5 and change n to 6.
3247 ## Writing New Polymorphic Actions ##
3249 The previous recipe showed you how to define your own action. This is
3250 all good, except that you need to know the type of the function in
3251 which the action will be used. Sometimes that can be a problem. For
3252 example, if you want to use the action in functions with _different_
3253 types (e.g. like `Return()` and `SetArgPointee()`).
3255 If an action can be used in several types of mock functions, we say
3256 it's _polymorphic_. The `MakePolymorphicAction()` function template
3257 makes it easy to define such an action:
3262 template <typename Impl>
3263 PolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl);
3265 } // namespace testing
3268 As an example, let's define an action that returns the second argument
3269 in the mock function's argument list. The first step is to define an
3270 implementation class:
3273 class ReturnSecondArgumentAction {
3275 template <typename Result, typename ArgumentTuple>
3276 Result Perform(const ArgumentTuple& args) const {
3277 // To get the i-th (0-based) argument, use tr1::get<i>(args).
3278 return tr1::get<1>(args);
3283 This implementation class does _not_ need to inherit from any
3284 particular class. What matters is that it must have a `Perform()`
3285 method template. This method template takes the mock function's
3286 arguments as a tuple in a **single** argument, and returns the result of
3287 the action. It can be either `const` or not, but must be invokable
3288 with exactly one template argument, which is the result type. In other
3289 words, you must be able to call `Perform<R>(args)` where `R` is the
3290 mock function's return type and `args` is its arguments in a tuple.
3292 Next, we use `MakePolymorphicAction()` to turn an instance of the
3293 implementation class into the polymorphic action we need. It will be
3294 convenient to have a wrapper for this:
3297 using ::testing::MakePolymorphicAction;
3298 using ::testing::PolymorphicAction;
3300 PolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() {
3301 return MakePolymorphicAction(ReturnSecondArgumentAction());
3305 Now, you can use this polymorphic action the same way you use the
3311 class MockFoo : public Foo {
3313 MOCK_METHOD2(DoThis, int(bool flag, int n));
3314 MOCK_METHOD3(DoThat, string(int x, const char* str1, const char* str2));
3319 EXPECT_CALL(foo, DoThis(_, _))
3320 .WillOnce(ReturnSecondArgument());
3321 EXPECT_CALL(foo, DoThat(_, _, _))
3322 .WillOnce(ReturnSecondArgument());
3324 foo.DoThis(true, 5); // Will return 5.
3325 foo.DoThat(1, "Hi", "Bye"); // Will return "Hi".
3328 ## Teaching Google Mock How to Print Your Values ##
3330 When an uninteresting or unexpected call occurs, Google Mock prints the
3331 argument values and the stack trace to help you debug. Assertion
3332 macros like `EXPECT_THAT` and `EXPECT_EQ` also print the values in
3333 question when the assertion fails. Google Mock and Google Test do this using
3334 Google Test's user-extensible value printer.
3336 This printer knows how to print built-in C++ types, native arrays, STL
3337 containers, and any type that supports the `<<` operator. For other
3338 types, it prints the raw bytes in the value and hopes that you the
3339 user can figure it out.
3340 [Google Test's advanced guide](http://code.google.com/p/googletest/wiki/V1_6_AdvancedGuide#Teaching_Google_Test_How_to_Print_Your_Values)
3341 explains how to extend the printer to do a better job at
3342 printing your particular type than to dump the bytes.