113481Sgiacomo.travaglini@arm.com 213481Sgiacomo.travaglini@arm.com 313481Sgiacomo.travaglini@arm.comYou can find recipes for using Google Mock here. If you haven't yet, 413481Sgiacomo.travaglini@arm.complease read the [ForDummies](V1_7_ForDummies.md) document first to make sure you understand 513481Sgiacomo.travaglini@arm.comthe basics. 613481Sgiacomo.travaglini@arm.com 713481Sgiacomo.travaglini@arm.com**Note:** Google Mock lives in the `testing` name space. For 813481Sgiacomo.travaglini@arm.comreadability, it is recommended to write `using ::testing::Foo;` once in 913481Sgiacomo.travaglini@arm.comyour file before using the name `Foo` defined by Google Mock. We omit 1013481Sgiacomo.travaglini@arm.comsuch `using` statements in this page for brevity, but you should do it 1113481Sgiacomo.travaglini@arm.comin your own code. 1213481Sgiacomo.travaglini@arm.com 1313481Sgiacomo.travaglini@arm.com# Creating Mock Classes # 1413481Sgiacomo.travaglini@arm.com 1513481Sgiacomo.travaglini@arm.com## Mocking Private or Protected Methods ## 1613481Sgiacomo.travaglini@arm.com 1713481Sgiacomo.travaglini@arm.comYou must always put a mock method definition (`MOCK_METHOD*`) in a 1813481Sgiacomo.travaglini@arm.com`public:` section of the mock class, regardless of the method being 1913481Sgiacomo.travaglini@arm.commocked being `public`, `protected`, or `private` in the base class. 2013481Sgiacomo.travaglini@arm.comThis allows `ON_CALL` and `EXPECT_CALL` to reference the mock function 2113481Sgiacomo.travaglini@arm.comfrom outside of the mock class. (Yes, C++ allows a subclass to change 2213481Sgiacomo.travaglini@arm.comthe access level of a virtual function in the base class.) Example: 2313481Sgiacomo.travaglini@arm.com 2413481Sgiacomo.travaglini@arm.com``` 2513481Sgiacomo.travaglini@arm.comclass Foo { 2613481Sgiacomo.travaglini@arm.com public: 2713481Sgiacomo.travaglini@arm.com ... 2813481Sgiacomo.travaglini@arm.com virtual bool Transform(Gadget* g) = 0; 2913481Sgiacomo.travaglini@arm.com 3013481Sgiacomo.travaglini@arm.com protected: 3113481Sgiacomo.travaglini@arm.com virtual void Resume(); 3213481Sgiacomo.travaglini@arm.com 3313481Sgiacomo.travaglini@arm.com private: 3413481Sgiacomo.travaglini@arm.com virtual int GetTimeOut(); 3513481Sgiacomo.travaglini@arm.com}; 3613481Sgiacomo.travaglini@arm.com 3713481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 3813481Sgiacomo.travaglini@arm.com public: 3913481Sgiacomo.travaglini@arm.com ... 4013481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Transform, bool(Gadget* g)); 4113481Sgiacomo.travaglini@arm.com 4213481Sgiacomo.travaglini@arm.com // The following must be in the public section, even though the 4313481Sgiacomo.travaglini@arm.com // methods are protected or private in the base class. 4413481Sgiacomo.travaglini@arm.com MOCK_METHOD0(Resume, void()); 4513481Sgiacomo.travaglini@arm.com MOCK_METHOD0(GetTimeOut, int()); 4613481Sgiacomo.travaglini@arm.com}; 4713481Sgiacomo.travaglini@arm.com``` 4813481Sgiacomo.travaglini@arm.com 4913481Sgiacomo.travaglini@arm.com## Mocking Overloaded Methods ## 5013481Sgiacomo.travaglini@arm.com 5113481Sgiacomo.travaglini@arm.comYou can mock overloaded functions as usual. No special attention is required: 5213481Sgiacomo.travaglini@arm.com 5313481Sgiacomo.travaglini@arm.com``` 5413481Sgiacomo.travaglini@arm.comclass Foo { 5513481Sgiacomo.travaglini@arm.com ... 5613481Sgiacomo.travaglini@arm.com 5713481Sgiacomo.travaglini@arm.com // Must be virtual as we'll inherit from Foo. 5813481Sgiacomo.travaglini@arm.com virtual ~Foo(); 5913481Sgiacomo.travaglini@arm.com 6013481Sgiacomo.travaglini@arm.com // Overloaded on the types and/or numbers of arguments. 6113481Sgiacomo.travaglini@arm.com virtual int Add(Element x); 6213481Sgiacomo.travaglini@arm.com virtual int Add(int times, Element x); 6313481Sgiacomo.travaglini@arm.com 6413481Sgiacomo.travaglini@arm.com // Overloaded on the const-ness of this object. 6513481Sgiacomo.travaglini@arm.com virtual Bar& GetBar(); 6613481Sgiacomo.travaglini@arm.com virtual const Bar& GetBar() const; 6713481Sgiacomo.travaglini@arm.com}; 6813481Sgiacomo.travaglini@arm.com 6913481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 7013481Sgiacomo.travaglini@arm.com ... 7113481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Add, int(Element x)); 7213481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Add, int(int times, Element x); 7313481Sgiacomo.travaglini@arm.com 7413481Sgiacomo.travaglini@arm.com MOCK_METHOD0(GetBar, Bar&()); 7513481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD0(GetBar, const Bar&()); 7613481Sgiacomo.travaglini@arm.com}; 7713481Sgiacomo.travaglini@arm.com``` 7813481Sgiacomo.travaglini@arm.com 7913481Sgiacomo.travaglini@arm.com**Note:** if you don't mock all versions of the overloaded method, the 8013481Sgiacomo.travaglini@arm.comcompiler will give you a warning about some methods in the base class 8113481Sgiacomo.travaglini@arm.combeing hidden. To fix that, use `using` to bring them in scope: 8213481Sgiacomo.travaglini@arm.com 8313481Sgiacomo.travaglini@arm.com``` 8413481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 8513481Sgiacomo.travaglini@arm.com ... 8613481Sgiacomo.travaglini@arm.com using Foo::Add; 8713481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Add, int(Element x)); 8813481Sgiacomo.travaglini@arm.com // We don't want to mock int Add(int times, Element x); 8913481Sgiacomo.travaglini@arm.com ... 9013481Sgiacomo.travaglini@arm.com}; 9113481Sgiacomo.travaglini@arm.com``` 9213481Sgiacomo.travaglini@arm.com 9313481Sgiacomo.travaglini@arm.com## Mocking Class Templates ## 9413481Sgiacomo.travaglini@arm.com 9513481Sgiacomo.travaglini@arm.comTo mock a class template, append `_T` to the `MOCK_*` macros: 9613481Sgiacomo.travaglini@arm.com 9713481Sgiacomo.travaglini@arm.com``` 9813481Sgiacomo.travaglini@arm.comtemplate <typename Elem> 9913481Sgiacomo.travaglini@arm.comclass StackInterface { 10013481Sgiacomo.travaglini@arm.com ... 10113481Sgiacomo.travaglini@arm.com // Must be virtual as we'll inherit from StackInterface. 10213481Sgiacomo.travaglini@arm.com virtual ~StackInterface(); 10313481Sgiacomo.travaglini@arm.com 10413481Sgiacomo.travaglini@arm.com virtual int GetSize() const = 0; 10513481Sgiacomo.travaglini@arm.com virtual void Push(const Elem& x) = 0; 10613481Sgiacomo.travaglini@arm.com}; 10713481Sgiacomo.travaglini@arm.com 10813481Sgiacomo.travaglini@arm.comtemplate <typename Elem> 10913481Sgiacomo.travaglini@arm.comclass MockStack : public StackInterface<Elem> { 11013481Sgiacomo.travaglini@arm.com ... 11113481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD0_T(GetSize, int()); 11213481Sgiacomo.travaglini@arm.com MOCK_METHOD1_T(Push, void(const Elem& x)); 11313481Sgiacomo.travaglini@arm.com}; 11413481Sgiacomo.travaglini@arm.com``` 11513481Sgiacomo.travaglini@arm.com 11613481Sgiacomo.travaglini@arm.com## Mocking Nonvirtual Methods ## 11713481Sgiacomo.travaglini@arm.com 11813481Sgiacomo.travaglini@arm.comGoogle Mock can mock non-virtual functions to be used in what we call _hi-perf 11913481Sgiacomo.travaglini@arm.comdependency injection_. 12013481Sgiacomo.travaglini@arm.com 12113481Sgiacomo.travaglini@arm.comIn this case, instead of sharing a common base class with the real 12213481Sgiacomo.travaglini@arm.comclass, your mock class will be _unrelated_ to the real class, but 12313481Sgiacomo.travaglini@arm.comcontain methods with the same signatures. The syntax for mocking 12413481Sgiacomo.travaglini@arm.comnon-virtual methods is the _same_ as mocking virtual methods: 12513481Sgiacomo.travaglini@arm.com 12613481Sgiacomo.travaglini@arm.com``` 12713481Sgiacomo.travaglini@arm.com// A simple packet stream class. None of its members is virtual. 12813481Sgiacomo.travaglini@arm.comclass ConcretePacketStream { 12913481Sgiacomo.travaglini@arm.com public: 13013481Sgiacomo.travaglini@arm.com void AppendPacket(Packet* new_packet); 13113481Sgiacomo.travaglini@arm.com const Packet* GetPacket(size_t packet_number) const; 13213481Sgiacomo.travaglini@arm.com size_t NumberOfPackets() const; 13313481Sgiacomo.travaglini@arm.com ... 13413481Sgiacomo.travaglini@arm.com}; 13513481Sgiacomo.travaglini@arm.com 13613481Sgiacomo.travaglini@arm.com// A mock packet stream class. It inherits from no other, but defines 13713481Sgiacomo.travaglini@arm.com// GetPacket() and NumberOfPackets(). 13813481Sgiacomo.travaglini@arm.comclass MockPacketStream { 13913481Sgiacomo.travaglini@arm.com public: 14013481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD1(GetPacket, const Packet*(size_t packet_number)); 14113481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD0(NumberOfPackets, size_t()); 14213481Sgiacomo.travaglini@arm.com ... 14313481Sgiacomo.travaglini@arm.com}; 14413481Sgiacomo.travaglini@arm.com``` 14513481Sgiacomo.travaglini@arm.com 14613481Sgiacomo.travaglini@arm.comNote that the mock class doesn't define `AppendPacket()`, unlike the 14713481Sgiacomo.travaglini@arm.comreal class. That's fine as long as the test doesn't need to call it. 14813481Sgiacomo.travaglini@arm.com 14913481Sgiacomo.travaglini@arm.comNext, you need a way to say that you want to use 15013481Sgiacomo.travaglini@arm.com`ConcretePacketStream` in production code, and use `MockPacketStream` 15113481Sgiacomo.travaglini@arm.comin tests. Since the functions are not virtual and the two classes are 15213481Sgiacomo.travaglini@arm.comunrelated, you must specify your choice at _compile time_ (as opposed 15313481Sgiacomo.travaglini@arm.comto run time). 15413481Sgiacomo.travaglini@arm.com 15513481Sgiacomo.travaglini@arm.comOne way to do it is to templatize your code that needs to use a packet 15613481Sgiacomo.travaglini@arm.comstream. More specifically, you will give your code a template type 15713481Sgiacomo.travaglini@arm.comargument for the type of the packet stream. In production, you will 15813481Sgiacomo.travaglini@arm.cominstantiate your template with `ConcretePacketStream` as the type 15913481Sgiacomo.travaglini@arm.comargument. In tests, you will instantiate the same template with 16013481Sgiacomo.travaglini@arm.com`MockPacketStream`. For example, you may write: 16113481Sgiacomo.travaglini@arm.com 16213481Sgiacomo.travaglini@arm.com``` 16313481Sgiacomo.travaglini@arm.comtemplate <class PacketStream> 16413481Sgiacomo.travaglini@arm.comvoid CreateConnection(PacketStream* stream) { ... } 16513481Sgiacomo.travaglini@arm.com 16613481Sgiacomo.travaglini@arm.comtemplate <class PacketStream> 16713481Sgiacomo.travaglini@arm.comclass PacketReader { 16813481Sgiacomo.travaglini@arm.com public: 16913481Sgiacomo.travaglini@arm.com void ReadPackets(PacketStream* stream, size_t packet_num); 17013481Sgiacomo.travaglini@arm.com}; 17113481Sgiacomo.travaglini@arm.com``` 17213481Sgiacomo.travaglini@arm.com 17313481Sgiacomo.travaglini@arm.comThen you can use `CreateConnection<ConcretePacketStream>()` and 17413481Sgiacomo.travaglini@arm.com`PacketReader<ConcretePacketStream>` in production code, and use 17513481Sgiacomo.travaglini@arm.com`CreateConnection<MockPacketStream>()` and 17613481Sgiacomo.travaglini@arm.com`PacketReader<MockPacketStream>` in tests. 17713481Sgiacomo.travaglini@arm.com 17813481Sgiacomo.travaglini@arm.com``` 17913481Sgiacomo.travaglini@arm.com MockPacketStream mock_stream; 18013481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_stream, ...)...; 18113481Sgiacomo.travaglini@arm.com .. set more expectations on mock_stream ... 18213481Sgiacomo.travaglini@arm.com PacketReader<MockPacketStream> reader(&mock_stream); 18313481Sgiacomo.travaglini@arm.com ... exercise reader ... 18413481Sgiacomo.travaglini@arm.com``` 18513481Sgiacomo.travaglini@arm.com 18613481Sgiacomo.travaglini@arm.com## Mocking Free Functions ## 18713481Sgiacomo.travaglini@arm.com 18813481Sgiacomo.travaglini@arm.comIt's possible to use Google Mock to mock a free function (i.e. a 18913481Sgiacomo.travaglini@arm.comC-style function or a static method). You just need to rewrite your 19013481Sgiacomo.travaglini@arm.comcode to use an interface (abstract class). 19113481Sgiacomo.travaglini@arm.com 19213481Sgiacomo.travaglini@arm.comInstead of calling a free function (say, `OpenFile`) directly, 19313481Sgiacomo.travaglini@arm.comintroduce an interface for it and have a concrete subclass that calls 19413481Sgiacomo.travaglini@arm.comthe free function: 19513481Sgiacomo.travaglini@arm.com 19613481Sgiacomo.travaglini@arm.com``` 19713481Sgiacomo.travaglini@arm.comclass FileInterface { 19813481Sgiacomo.travaglini@arm.com public: 19913481Sgiacomo.travaglini@arm.com ... 20013481Sgiacomo.travaglini@arm.com virtual bool Open(const char* path, const char* mode) = 0; 20113481Sgiacomo.travaglini@arm.com}; 20213481Sgiacomo.travaglini@arm.com 20313481Sgiacomo.travaglini@arm.comclass File : public FileInterface { 20413481Sgiacomo.travaglini@arm.com public: 20513481Sgiacomo.travaglini@arm.com ... 20613481Sgiacomo.travaglini@arm.com virtual bool Open(const char* path, const char* mode) { 20713481Sgiacomo.travaglini@arm.com return OpenFile(path, mode); 20813481Sgiacomo.travaglini@arm.com } 20913481Sgiacomo.travaglini@arm.com}; 21013481Sgiacomo.travaglini@arm.com``` 21113481Sgiacomo.travaglini@arm.com 21213481Sgiacomo.travaglini@arm.comYour code should talk to `FileInterface` to open a file. Now it's 21313481Sgiacomo.travaglini@arm.comeasy to mock out the function. 21413481Sgiacomo.travaglini@arm.com 21513481Sgiacomo.travaglini@arm.comThis may seem much hassle, but in practice you often have multiple 21613481Sgiacomo.travaglini@arm.comrelated functions that you can put in the same interface, so the 21713481Sgiacomo.travaglini@arm.comper-function syntactic overhead will be much lower. 21813481Sgiacomo.travaglini@arm.com 21913481Sgiacomo.travaglini@arm.comIf you are concerned about the performance overhead incurred by 22013481Sgiacomo.travaglini@arm.comvirtual functions, and profiling confirms your concern, you can 22113481Sgiacomo.travaglini@arm.comcombine this with the recipe for [mocking non-virtual methods](#Mocking_Nonvirtual_Methods.md). 22213481Sgiacomo.travaglini@arm.com 22313481Sgiacomo.travaglini@arm.com## The Nice, the Strict, and the Naggy ## 22413481Sgiacomo.travaglini@arm.com 22513481Sgiacomo.travaglini@arm.comIf a mock method has no `EXPECT_CALL` spec but is called, Google Mock 22613481Sgiacomo.travaglini@arm.comwill print a warning about the "uninteresting call". The rationale is: 22713481Sgiacomo.travaglini@arm.com 22813481Sgiacomo.travaglini@arm.com * 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. 22913481Sgiacomo.travaglini@arm.com * 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. 23013481Sgiacomo.travaglini@arm.com 23113481Sgiacomo.travaglini@arm.comHowever, sometimes you may want to suppress all "uninteresting call" 23213481Sgiacomo.travaglini@arm.comwarnings, while sometimes you may want the opposite, i.e. to treat all 23313481Sgiacomo.travaglini@arm.comof them as errors. Google Mock lets you make the decision on a 23413481Sgiacomo.travaglini@arm.comper-mock-object basis. 23513481Sgiacomo.travaglini@arm.com 23613481Sgiacomo.travaglini@arm.comSuppose your test uses a mock class `MockFoo`: 23713481Sgiacomo.travaglini@arm.com 23813481Sgiacomo.travaglini@arm.com``` 23913481Sgiacomo.travaglini@arm.comTEST(...) { 24013481Sgiacomo.travaglini@arm.com MockFoo mock_foo; 24113481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_foo, DoThis()); 24213481Sgiacomo.travaglini@arm.com ... code that uses mock_foo ... 24313481Sgiacomo.travaglini@arm.com} 24413481Sgiacomo.travaglini@arm.com``` 24513481Sgiacomo.travaglini@arm.com 24613481Sgiacomo.travaglini@arm.comIf a method of `mock_foo` other than `DoThis()` is called, it will be 24713481Sgiacomo.travaglini@arm.comreported by Google Mock as a warning. However, if you rewrite your 24813481Sgiacomo.travaglini@arm.comtest to use `NiceMock<MockFoo>` instead, the warning will be gone, 24913481Sgiacomo.travaglini@arm.comresulting in a cleaner test output: 25013481Sgiacomo.travaglini@arm.com 25113481Sgiacomo.travaglini@arm.com``` 25213481Sgiacomo.travaglini@arm.comusing ::testing::NiceMock; 25313481Sgiacomo.travaglini@arm.com 25413481Sgiacomo.travaglini@arm.comTEST(...) { 25513481Sgiacomo.travaglini@arm.com NiceMock<MockFoo> mock_foo; 25613481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_foo, DoThis()); 25713481Sgiacomo.travaglini@arm.com ... code that uses mock_foo ... 25813481Sgiacomo.travaglini@arm.com} 25913481Sgiacomo.travaglini@arm.com``` 26013481Sgiacomo.travaglini@arm.com 26113481Sgiacomo.travaglini@arm.com`NiceMock<MockFoo>` is a subclass of `MockFoo`, so it can be used 26213481Sgiacomo.travaglini@arm.comwherever `MockFoo` is accepted. 26313481Sgiacomo.travaglini@arm.com 26413481Sgiacomo.travaglini@arm.comIt also works if `MockFoo`'s constructor takes some arguments, as 26513481Sgiacomo.travaglini@arm.com`NiceMock<MockFoo>` "inherits" `MockFoo`'s constructors: 26613481Sgiacomo.travaglini@arm.com 26713481Sgiacomo.travaglini@arm.com``` 26813481Sgiacomo.travaglini@arm.comusing ::testing::NiceMock; 26913481Sgiacomo.travaglini@arm.com 27013481Sgiacomo.travaglini@arm.comTEST(...) { 27113481Sgiacomo.travaglini@arm.com NiceMock<MockFoo> mock_foo(5, "hi"); // Calls MockFoo(5, "hi"). 27213481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_foo, DoThis()); 27313481Sgiacomo.travaglini@arm.com ... code that uses mock_foo ... 27413481Sgiacomo.travaglini@arm.com} 27513481Sgiacomo.travaglini@arm.com``` 27613481Sgiacomo.travaglini@arm.com 27713481Sgiacomo.travaglini@arm.comThe usage of `StrictMock` is similar, except that it makes all 27813481Sgiacomo.travaglini@arm.comuninteresting calls failures: 27913481Sgiacomo.travaglini@arm.com 28013481Sgiacomo.travaglini@arm.com``` 28113481Sgiacomo.travaglini@arm.comusing ::testing::StrictMock; 28213481Sgiacomo.travaglini@arm.com 28313481Sgiacomo.travaglini@arm.comTEST(...) { 28413481Sgiacomo.travaglini@arm.com StrictMock<MockFoo> mock_foo; 28513481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_foo, DoThis()); 28613481Sgiacomo.travaglini@arm.com ... code that uses mock_foo ... 28713481Sgiacomo.travaglini@arm.com 28813481Sgiacomo.travaglini@arm.com // The test will fail if a method of mock_foo other than DoThis() 28913481Sgiacomo.travaglini@arm.com // is called. 29013481Sgiacomo.travaglini@arm.com} 29113481Sgiacomo.travaglini@arm.com``` 29213481Sgiacomo.travaglini@arm.com 29313481Sgiacomo.travaglini@arm.comThere are some caveats though (I don't like them just as much as the 29413481Sgiacomo.travaglini@arm.comnext guy, but sadly they are side effects of C++'s limitations): 29513481Sgiacomo.travaglini@arm.com 29613481Sgiacomo.travaglini@arm.com 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. 29713481Sgiacomo.travaglini@arm.com 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). 29813481Sgiacomo.travaglini@arm.com 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.) 29913481Sgiacomo.travaglini@arm.com 30013481Sgiacomo.travaglini@arm.comFinally, you should be **very cautious** about when to use naggy or strict mocks, as they tend to make tests more brittle and harder to maintain. When you refactor your code without changing its externally visible behavior, ideally you should't need to update any tests. If your code interacts with a naggy mock, however, you may start to get spammed with warnings as the result of your change. Worse, if your code interacts with a strict mock, your tests may start to fail and you'll be forced to fix them. Our general recommendation is to use nice mocks (not yet the default) most of the time, use naggy mocks (the current default) when developing or debugging tests, and use strict mocks only as the last resort. 30113481Sgiacomo.travaglini@arm.com 30213481Sgiacomo.travaglini@arm.com## Simplifying the Interface without Breaking Existing Code ## 30313481Sgiacomo.travaglini@arm.com 30413481Sgiacomo.travaglini@arm.comSometimes a method has a long list of arguments that is mostly 30513481Sgiacomo.travaglini@arm.comuninteresting. For example, 30613481Sgiacomo.travaglini@arm.com 30713481Sgiacomo.travaglini@arm.com``` 30813481Sgiacomo.travaglini@arm.comclass LogSink { 30913481Sgiacomo.travaglini@arm.com public: 31013481Sgiacomo.travaglini@arm.com ... 31113481Sgiacomo.travaglini@arm.com virtual void send(LogSeverity severity, const char* full_filename, 31213481Sgiacomo.travaglini@arm.com const char* base_filename, int line, 31313481Sgiacomo.travaglini@arm.com const struct tm* tm_time, 31413481Sgiacomo.travaglini@arm.com const char* message, size_t message_len) = 0; 31513481Sgiacomo.travaglini@arm.com}; 31613481Sgiacomo.travaglini@arm.com``` 31713481Sgiacomo.travaglini@arm.com 31813481Sgiacomo.travaglini@arm.comThis method's argument list is lengthy and hard to work with (let's 31913481Sgiacomo.travaglini@arm.comsay that the `message` argument is not even 0-terminated). If we mock 32013481Sgiacomo.travaglini@arm.comit as is, using the mock will be awkward. If, however, we try to 32113481Sgiacomo.travaglini@arm.comsimplify this interface, we'll need to fix all clients depending on 32213481Sgiacomo.travaglini@arm.comit, which is often infeasible. 32313481Sgiacomo.travaglini@arm.com 32413481Sgiacomo.travaglini@arm.comThe trick is to re-dispatch the method in the mock class: 32513481Sgiacomo.travaglini@arm.com 32613481Sgiacomo.travaglini@arm.com``` 32713481Sgiacomo.travaglini@arm.comclass ScopedMockLog : public LogSink { 32813481Sgiacomo.travaglini@arm.com public: 32913481Sgiacomo.travaglini@arm.com ... 33013481Sgiacomo.travaglini@arm.com virtual void send(LogSeverity severity, const char* full_filename, 33113481Sgiacomo.travaglini@arm.com const char* base_filename, int line, const tm* tm_time, 33213481Sgiacomo.travaglini@arm.com const char* message, size_t message_len) { 33313481Sgiacomo.travaglini@arm.com // We are only interested in the log severity, full file name, and 33413481Sgiacomo.travaglini@arm.com // log message. 33513481Sgiacomo.travaglini@arm.com Log(severity, full_filename, std::string(message, message_len)); 33613481Sgiacomo.travaglini@arm.com } 33713481Sgiacomo.travaglini@arm.com 33813481Sgiacomo.travaglini@arm.com // Implements the mock method: 33913481Sgiacomo.travaglini@arm.com // 34013481Sgiacomo.travaglini@arm.com // void Log(LogSeverity severity, 34113481Sgiacomo.travaglini@arm.com // const string& file_path, 34213481Sgiacomo.travaglini@arm.com // const string& message); 34313481Sgiacomo.travaglini@arm.com MOCK_METHOD3(Log, void(LogSeverity severity, const string& file_path, 34413481Sgiacomo.travaglini@arm.com const string& message)); 34513481Sgiacomo.travaglini@arm.com}; 34613481Sgiacomo.travaglini@arm.com``` 34713481Sgiacomo.travaglini@arm.com 34813481Sgiacomo.travaglini@arm.comBy defining a new mock method with a trimmed argument list, we make 34913481Sgiacomo.travaglini@arm.comthe mock class much more user-friendly. 35013481Sgiacomo.travaglini@arm.com 35113481Sgiacomo.travaglini@arm.com## Alternative to Mocking Concrete Classes ## 35213481Sgiacomo.travaglini@arm.com 35313481Sgiacomo.travaglini@arm.comOften you may find yourself using classes that don't implement 35413481Sgiacomo.travaglini@arm.cominterfaces. In order to test your code that uses such a class (let's 35513481Sgiacomo.travaglini@arm.comcall it `Concrete`), you may be tempted to make the methods of 35613481Sgiacomo.travaglini@arm.com`Concrete` virtual and then mock it. 35713481Sgiacomo.travaglini@arm.com 35813481Sgiacomo.travaglini@arm.comTry not to do that. 35913481Sgiacomo.travaglini@arm.com 36013481Sgiacomo.travaglini@arm.comMaking a non-virtual function virtual is a big decision. It creates an 36113481Sgiacomo.travaglini@arm.comextension point where subclasses can tweak your class' behavior. This 36213481Sgiacomo.travaglini@arm.comweakens your control on the class because now it's harder to maintain 36313481Sgiacomo.travaglini@arm.comthe class' invariants. You should make a function virtual only when 36413481Sgiacomo.travaglini@arm.comthere is a valid reason for a subclass to override it. 36513481Sgiacomo.travaglini@arm.com 36613481Sgiacomo.travaglini@arm.comMocking concrete classes directly is problematic as it creates a tight 36713481Sgiacomo.travaglini@arm.comcoupling between the class and the tests - any small change in the 36813481Sgiacomo.travaglini@arm.comclass may invalidate your tests and make test maintenance a pain. 36913481Sgiacomo.travaglini@arm.com 37013481Sgiacomo.travaglini@arm.comTo avoid such problems, many programmers have been practicing "coding 37113481Sgiacomo.travaglini@arm.comto interfaces": instead of talking to the `Concrete` class, your code 37213481Sgiacomo.travaglini@arm.comwould define an interface and talk to it. Then you implement that 37313481Sgiacomo.travaglini@arm.cominterface as an adaptor on top of `Concrete`. In tests, you can easily 37413481Sgiacomo.travaglini@arm.commock that interface to observe how your code is doing. 37513481Sgiacomo.travaglini@arm.com 37613481Sgiacomo.travaglini@arm.comThis technique incurs some overhead: 37713481Sgiacomo.travaglini@arm.com 37813481Sgiacomo.travaglini@arm.com * You pay the cost of virtual function calls (usually not a problem). 37913481Sgiacomo.travaglini@arm.com * There is more abstraction for the programmers to learn. 38013481Sgiacomo.travaglini@arm.com 38113481Sgiacomo.travaglini@arm.comHowever, it can also bring significant benefits in addition to better 38213481Sgiacomo.travaglini@arm.comtestability: 38313481Sgiacomo.travaglini@arm.com 38413481Sgiacomo.travaglini@arm.com * `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. 38513481Sgiacomo.travaglini@arm.com * 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. 38613481Sgiacomo.travaglini@arm.com 38713481Sgiacomo.travaglini@arm.comSome people worry that if everyone is practicing this technique, they 38813481Sgiacomo.travaglini@arm.comwill end up writing lots of redundant code. This concern is totally 38913481Sgiacomo.travaglini@arm.comunderstandable. However, there are two reasons why it may not be the 39013481Sgiacomo.travaglini@arm.comcase: 39113481Sgiacomo.travaglini@arm.com 39213481Sgiacomo.travaglini@arm.com * 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. 39313481Sgiacomo.travaglini@arm.com * 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. 39413481Sgiacomo.travaglini@arm.com 39513481Sgiacomo.travaglini@arm.comYou need to weigh the pros and cons carefully for your particular 39613481Sgiacomo.travaglini@arm.comproblem, but I'd like to assure you that the Java community has been 39713481Sgiacomo.travaglini@arm.compracticing this for a long time and it's a proven effective technique 39813481Sgiacomo.travaglini@arm.comapplicable in a wide variety of situations. :-) 39913481Sgiacomo.travaglini@arm.com 40013481Sgiacomo.travaglini@arm.com## Delegating Calls to a Fake ## 40113481Sgiacomo.travaglini@arm.com 40213481Sgiacomo.travaglini@arm.comSome times you have a non-trivial fake implementation of an 40313481Sgiacomo.travaglini@arm.cominterface. For example: 40413481Sgiacomo.travaglini@arm.com 40513481Sgiacomo.travaglini@arm.com``` 40613481Sgiacomo.travaglini@arm.comclass Foo { 40713481Sgiacomo.travaglini@arm.com public: 40813481Sgiacomo.travaglini@arm.com virtual ~Foo() {} 40913481Sgiacomo.travaglini@arm.com virtual char DoThis(int n) = 0; 41013481Sgiacomo.travaglini@arm.com virtual void DoThat(const char* s, int* p) = 0; 41113481Sgiacomo.travaglini@arm.com}; 41213481Sgiacomo.travaglini@arm.com 41313481Sgiacomo.travaglini@arm.comclass FakeFoo : public Foo { 41413481Sgiacomo.travaglini@arm.com public: 41513481Sgiacomo.travaglini@arm.com virtual char DoThis(int n) { 41613481Sgiacomo.travaglini@arm.com return (n > 0) ? '+' : 41713481Sgiacomo.travaglini@arm.com (n < 0) ? '-' : '0'; 41813481Sgiacomo.travaglini@arm.com } 41913481Sgiacomo.travaglini@arm.com 42013481Sgiacomo.travaglini@arm.com virtual void DoThat(const char* s, int* p) { 42113481Sgiacomo.travaglini@arm.com *p = strlen(s); 42213481Sgiacomo.travaglini@arm.com } 42313481Sgiacomo.travaglini@arm.com}; 42413481Sgiacomo.travaglini@arm.com``` 42513481Sgiacomo.travaglini@arm.com 42613481Sgiacomo.travaglini@arm.comNow you want to mock this interface such that you can set expectations 42713481Sgiacomo.travaglini@arm.comon it. However, you also want to use `FakeFoo` for the default 42813481Sgiacomo.travaglini@arm.combehavior, as duplicating it in the mock object is, well, a lot of 42913481Sgiacomo.travaglini@arm.comwork. 43013481Sgiacomo.travaglini@arm.com 43113481Sgiacomo.travaglini@arm.comWhen you define the mock class using Google Mock, you can have it 43213481Sgiacomo.travaglini@arm.comdelegate its default action to a fake class you already have, using 43313481Sgiacomo.travaglini@arm.comthis pattern: 43413481Sgiacomo.travaglini@arm.com 43513481Sgiacomo.travaglini@arm.com``` 43613481Sgiacomo.travaglini@arm.comusing ::testing::_; 43713481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 43813481Sgiacomo.travaglini@arm.com 43913481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 44013481Sgiacomo.travaglini@arm.com public: 44113481Sgiacomo.travaglini@arm.com // Normal mock method definitions using Google Mock. 44213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(DoThis, char(int n)); 44313481Sgiacomo.travaglini@arm.com MOCK_METHOD2(DoThat, void(const char* s, int* p)); 44413481Sgiacomo.travaglini@arm.com 44513481Sgiacomo.travaglini@arm.com // Delegates the default actions of the methods to a FakeFoo object. 44613481Sgiacomo.travaglini@arm.com // This must be called *before* the custom ON_CALL() statements. 44713481Sgiacomo.travaglini@arm.com void DelegateToFake() { 44813481Sgiacomo.travaglini@arm.com ON_CALL(*this, DoThis(_)) 44913481Sgiacomo.travaglini@arm.com .WillByDefault(Invoke(&fake_, &FakeFoo::DoThis)); 45013481Sgiacomo.travaglini@arm.com ON_CALL(*this, DoThat(_, _)) 45113481Sgiacomo.travaglini@arm.com .WillByDefault(Invoke(&fake_, &FakeFoo::DoThat)); 45213481Sgiacomo.travaglini@arm.com } 45313481Sgiacomo.travaglini@arm.com private: 45413481Sgiacomo.travaglini@arm.com FakeFoo fake_; // Keeps an instance of the fake in the mock. 45513481Sgiacomo.travaglini@arm.com}; 45613481Sgiacomo.travaglini@arm.com``` 45713481Sgiacomo.travaglini@arm.com 45813481Sgiacomo.travaglini@arm.comWith that, you can use `MockFoo` in your tests as usual. Just remember 45913481Sgiacomo.travaglini@arm.comthat if you don't explicitly set an action in an `ON_CALL()` or 46013481Sgiacomo.travaglini@arm.com`EXPECT_CALL()`, the fake will be called upon to do it: 46113481Sgiacomo.travaglini@arm.com 46213481Sgiacomo.travaglini@arm.com``` 46313481Sgiacomo.travaglini@arm.comusing ::testing::_; 46413481Sgiacomo.travaglini@arm.com 46513481Sgiacomo.travaglini@arm.comTEST(AbcTest, Xyz) { 46613481Sgiacomo.travaglini@arm.com MockFoo foo; 46713481Sgiacomo.travaglini@arm.com foo.DelegateToFake(); // Enables the fake for delegation. 46813481Sgiacomo.travaglini@arm.com 46913481Sgiacomo.travaglini@arm.com // Put your ON_CALL(foo, ...)s here, if any. 47013481Sgiacomo.travaglini@arm.com 47113481Sgiacomo.travaglini@arm.com // No action specified, meaning to use the default action. 47213481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(5)); 47313481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat(_, _)); 47413481Sgiacomo.travaglini@arm.com 47513481Sgiacomo.travaglini@arm.com int n = 0; 47613481Sgiacomo.travaglini@arm.com EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked. 47713481Sgiacomo.travaglini@arm.com foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked. 47813481Sgiacomo.travaglini@arm.com EXPECT_EQ(2, n); 47913481Sgiacomo.travaglini@arm.com} 48013481Sgiacomo.travaglini@arm.com``` 48113481Sgiacomo.travaglini@arm.com 48213481Sgiacomo.travaglini@arm.com**Some tips:** 48313481Sgiacomo.travaglini@arm.com 48413481Sgiacomo.travaglini@arm.com * If you want, you can still override the default action by providing your own `ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`. 48513481Sgiacomo.travaglini@arm.com * In `DelegateToFake()`, you only need to delegate the methods whose fake implementation you intend to use. 48613481Sgiacomo.travaglini@arm.com * The general technique discussed here works for overloaded methods, but you'll need to tell the compiler which version you mean. To disambiguate a mock function (the one you specify inside the parentheses of `ON_CALL()`), see the "Selecting Between Overloaded Functions" section on this page; to disambiguate a fake function (the one you place inside `Invoke()`), use a `static_cast` to specify the function's type. For instance, if class `Foo` has methods `char DoThis(int n)` and `bool DoThis(double x) const`, and you want to invoke the latter, you need to write `Invoke(&fake_, static_cast<bool (FakeFoo::*)(double) const>(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)` (The strange-looking thing inside the angled brackets of `static_cast` is the type of a function pointer to the second `DoThis()` method.). 48713481Sgiacomo.travaglini@arm.com * 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. 48813481Sgiacomo.travaglini@arm.com 48913481Sgiacomo.travaglini@arm.comRegarding the tip on mixing a mock and a fake, here's an example on 49013481Sgiacomo.travaglini@arm.comwhy it may be a bad sign: Suppose you have a class `System` for 49113481Sgiacomo.travaglini@arm.comlow-level system operations. In particular, it does file and I/O 49213481Sgiacomo.travaglini@arm.comoperations. And suppose you want to test how your code uses `System` 49313481Sgiacomo.travaglini@arm.comto do I/O, and you just want the file operations to work normally. If 49413481Sgiacomo.travaglini@arm.comyou mock out the entire `System` class, you'll have to provide a fake 49513481Sgiacomo.travaglini@arm.comimplementation for the file operation part, which suggests that 49613481Sgiacomo.travaglini@arm.com`System` is taking on too many roles. 49713481Sgiacomo.travaglini@arm.com 49813481Sgiacomo.travaglini@arm.comInstead, you can define a `FileOps` interface and an `IOOps` interface 49913481Sgiacomo.travaglini@arm.comand split `System`'s functionalities into the two. Then you can mock 50013481Sgiacomo.travaglini@arm.com`IOOps` without mocking `FileOps`. 50113481Sgiacomo.travaglini@arm.com 50213481Sgiacomo.travaglini@arm.com## Delegating Calls to a Real Object ## 50313481Sgiacomo.travaglini@arm.com 50413481Sgiacomo.travaglini@arm.comWhen using testing doubles (mocks, fakes, stubs, and etc), sometimes 50513481Sgiacomo.travaglini@arm.comtheir behaviors will differ from those of the real objects. This 50613481Sgiacomo.travaglini@arm.comdifference could be either intentional (as in simulating an error such 50713481Sgiacomo.travaglini@arm.comthat you can test the error handling code) or unintentional. If your 50813481Sgiacomo.travaglini@arm.commocks have different behaviors than the real objects by mistake, you 50913481Sgiacomo.travaglini@arm.comcould end up with code that passes the tests but fails in production. 51013481Sgiacomo.travaglini@arm.com 51113481Sgiacomo.travaglini@arm.comYou can use the _delegating-to-real_ technique to ensure that your 51213481Sgiacomo.travaglini@arm.commock has the same behavior as the real object while retaining the 51313481Sgiacomo.travaglini@arm.comability to validate calls. This technique is very similar to the 51413481Sgiacomo.travaglini@arm.comdelegating-to-fake technique, the difference being that we use a real 51513481Sgiacomo.travaglini@arm.comobject instead of a fake. Here's an example: 51613481Sgiacomo.travaglini@arm.com 51713481Sgiacomo.travaglini@arm.com``` 51813481Sgiacomo.travaglini@arm.comusing ::testing::_; 51913481Sgiacomo.travaglini@arm.comusing ::testing::AtLeast; 52013481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 52113481Sgiacomo.travaglini@arm.com 52213481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 52313481Sgiacomo.travaglini@arm.com public: 52413481Sgiacomo.travaglini@arm.com MockFoo() { 52513481Sgiacomo.travaglini@arm.com // By default, all calls are delegated to the real object. 52613481Sgiacomo.travaglini@arm.com ON_CALL(*this, DoThis()) 52713481Sgiacomo.travaglini@arm.com .WillByDefault(Invoke(&real_, &Foo::DoThis)); 52813481Sgiacomo.travaglini@arm.com ON_CALL(*this, DoThat(_)) 52913481Sgiacomo.travaglini@arm.com .WillByDefault(Invoke(&real_, &Foo::DoThat)); 53013481Sgiacomo.travaglini@arm.com ... 53113481Sgiacomo.travaglini@arm.com } 53213481Sgiacomo.travaglini@arm.com MOCK_METHOD0(DoThis, ...); 53313481Sgiacomo.travaglini@arm.com MOCK_METHOD1(DoThat, ...); 53413481Sgiacomo.travaglini@arm.com ... 53513481Sgiacomo.travaglini@arm.com private: 53613481Sgiacomo.travaglini@arm.com Foo real_; 53713481Sgiacomo.travaglini@arm.com}; 53813481Sgiacomo.travaglini@arm.com... 53913481Sgiacomo.travaglini@arm.com 54013481Sgiacomo.travaglini@arm.com MockFoo mock; 54113481Sgiacomo.travaglini@arm.com 54213481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, DoThis()) 54313481Sgiacomo.travaglini@arm.com .Times(3); 54413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, DoThat("Hi")) 54513481Sgiacomo.travaglini@arm.com .Times(AtLeast(1)); 54613481Sgiacomo.travaglini@arm.com ... use mock in test ... 54713481Sgiacomo.travaglini@arm.com``` 54813481Sgiacomo.travaglini@arm.com 54913481Sgiacomo.travaglini@arm.comWith this, Google Mock will verify that your code made the right calls 55013481Sgiacomo.travaglini@arm.com(with the right arguments, in the right order, called the right number 55113481Sgiacomo.travaglini@arm.comof times, etc), and a real object will answer the calls (so the 55213481Sgiacomo.travaglini@arm.combehavior will be the same as in production). This gives you the best 55313481Sgiacomo.travaglini@arm.comof both worlds. 55413481Sgiacomo.travaglini@arm.com 55513481Sgiacomo.travaglini@arm.com## Delegating Calls to a Parent Class ## 55613481Sgiacomo.travaglini@arm.com 55713481Sgiacomo.travaglini@arm.comIdeally, you should code to interfaces, whose methods are all pure 55813481Sgiacomo.travaglini@arm.comvirtual. In reality, sometimes you do need to mock a virtual method 55913481Sgiacomo.travaglini@arm.comthat is not pure (i.e, it already has an implementation). For example: 56013481Sgiacomo.travaglini@arm.com 56113481Sgiacomo.travaglini@arm.com``` 56213481Sgiacomo.travaglini@arm.comclass Foo { 56313481Sgiacomo.travaglini@arm.com public: 56413481Sgiacomo.travaglini@arm.com virtual ~Foo(); 56513481Sgiacomo.travaglini@arm.com 56613481Sgiacomo.travaglini@arm.com virtual void Pure(int n) = 0; 56713481Sgiacomo.travaglini@arm.com virtual int Concrete(const char* str) { ... } 56813481Sgiacomo.travaglini@arm.com}; 56913481Sgiacomo.travaglini@arm.com 57013481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 57113481Sgiacomo.travaglini@arm.com public: 57213481Sgiacomo.travaglini@arm.com // Mocking a pure method. 57313481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Pure, void(int n)); 57413481Sgiacomo.travaglini@arm.com // Mocking a concrete method. Foo::Concrete() is shadowed. 57513481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Concrete, int(const char* str)); 57613481Sgiacomo.travaglini@arm.com}; 57713481Sgiacomo.travaglini@arm.com``` 57813481Sgiacomo.travaglini@arm.com 57913481Sgiacomo.travaglini@arm.comSometimes you may want to call `Foo::Concrete()` instead of 58013481Sgiacomo.travaglini@arm.com`MockFoo::Concrete()`. Perhaps you want to do it as part of a stub 58113481Sgiacomo.travaglini@arm.comaction, or perhaps your test doesn't need to mock `Concrete()` at all 58213481Sgiacomo.travaglini@arm.com(but it would be oh-so painful to have to define a new mock class 58313481Sgiacomo.travaglini@arm.comwhenever you don't need to mock one of its methods). 58413481Sgiacomo.travaglini@arm.com 58513481Sgiacomo.travaglini@arm.comThe trick is to leave a back door in your mock class for accessing the 58613481Sgiacomo.travaglini@arm.comreal methods in the base class: 58713481Sgiacomo.travaglini@arm.com 58813481Sgiacomo.travaglini@arm.com``` 58913481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 59013481Sgiacomo.travaglini@arm.com public: 59113481Sgiacomo.travaglini@arm.com // Mocking a pure method. 59213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Pure, void(int n)); 59313481Sgiacomo.travaglini@arm.com // Mocking a concrete method. Foo::Concrete() is shadowed. 59413481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Concrete, int(const char* str)); 59513481Sgiacomo.travaglini@arm.com 59613481Sgiacomo.travaglini@arm.com // Use this to call Concrete() defined in Foo. 59713481Sgiacomo.travaglini@arm.com int FooConcrete(const char* str) { return Foo::Concrete(str); } 59813481Sgiacomo.travaglini@arm.com}; 59913481Sgiacomo.travaglini@arm.com``` 60013481Sgiacomo.travaglini@arm.com 60113481Sgiacomo.travaglini@arm.comNow, you can call `Foo::Concrete()` inside an action by: 60213481Sgiacomo.travaglini@arm.com 60313481Sgiacomo.travaglini@arm.com``` 60413481Sgiacomo.travaglini@arm.comusing ::testing::_; 60513481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 60613481Sgiacomo.travaglini@arm.com... 60713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Concrete(_)) 60813481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(&foo, &MockFoo::FooConcrete)); 60913481Sgiacomo.travaglini@arm.com``` 61013481Sgiacomo.travaglini@arm.com 61113481Sgiacomo.travaglini@arm.comor tell the mock object that you don't want to mock `Concrete()`: 61213481Sgiacomo.travaglini@arm.com 61313481Sgiacomo.travaglini@arm.com``` 61413481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 61513481Sgiacomo.travaglini@arm.com... 61613481Sgiacomo.travaglini@arm.com ON_CALL(foo, Concrete(_)) 61713481Sgiacomo.travaglini@arm.com .WillByDefault(Invoke(&foo, &MockFoo::FooConcrete)); 61813481Sgiacomo.travaglini@arm.com``` 61913481Sgiacomo.travaglini@arm.com 62013481Sgiacomo.travaglini@arm.com(Why don't we just write `Invoke(&foo, &Foo::Concrete)`? If you do 62113481Sgiacomo.travaglini@arm.comthat, `MockFoo::Concrete()` will be called (and cause an infinite 62213481Sgiacomo.travaglini@arm.comrecursion) since `Foo::Concrete()` is virtual. That's just how C++ 62313481Sgiacomo.travaglini@arm.comworks.) 62413481Sgiacomo.travaglini@arm.com 62513481Sgiacomo.travaglini@arm.com# Using Matchers # 62613481Sgiacomo.travaglini@arm.com 62713481Sgiacomo.travaglini@arm.com## Matching Argument Values Exactly ## 62813481Sgiacomo.travaglini@arm.com 62913481Sgiacomo.travaglini@arm.comYou can specify exactly which arguments a mock method is expecting: 63013481Sgiacomo.travaglini@arm.com 63113481Sgiacomo.travaglini@arm.com``` 63213481Sgiacomo.travaglini@arm.comusing ::testing::Return; 63313481Sgiacomo.travaglini@arm.com... 63413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(5)) 63513481Sgiacomo.travaglini@arm.com .WillOnce(Return('a')); 63613481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat("Hello", bar)); 63713481Sgiacomo.travaglini@arm.com``` 63813481Sgiacomo.travaglini@arm.com 63913481Sgiacomo.travaglini@arm.com## Using Simple Matchers ## 64013481Sgiacomo.travaglini@arm.com 64113481Sgiacomo.travaglini@arm.comYou can use matchers to match arguments that have a certain property: 64213481Sgiacomo.travaglini@arm.com 64313481Sgiacomo.travaglini@arm.com``` 64413481Sgiacomo.travaglini@arm.comusing ::testing::Ge; 64513481Sgiacomo.travaglini@arm.comusing ::testing::NotNull; 64613481Sgiacomo.travaglini@arm.comusing ::testing::Return; 64713481Sgiacomo.travaglini@arm.com... 64813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5. 64913481Sgiacomo.travaglini@arm.com .WillOnce(Return('a')); 65013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat("Hello", NotNull())); 65113481Sgiacomo.travaglini@arm.com // The second argument must not be NULL. 65213481Sgiacomo.travaglini@arm.com``` 65313481Sgiacomo.travaglini@arm.com 65413481Sgiacomo.travaglini@arm.comA frequently used matcher is `_`, which matches anything: 65513481Sgiacomo.travaglini@arm.com 65613481Sgiacomo.travaglini@arm.com``` 65713481Sgiacomo.travaglini@arm.comusing ::testing::_; 65813481Sgiacomo.travaglini@arm.comusing ::testing::NotNull; 65913481Sgiacomo.travaglini@arm.com... 66013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat(_, NotNull())); 66113481Sgiacomo.travaglini@arm.com``` 66213481Sgiacomo.travaglini@arm.com 66313481Sgiacomo.travaglini@arm.com## Combining Matchers ## 66413481Sgiacomo.travaglini@arm.com 66513481Sgiacomo.travaglini@arm.comYou can build complex matchers from existing ones using `AllOf()`, 66613481Sgiacomo.travaglini@arm.com`AnyOf()`, and `Not()`: 66713481Sgiacomo.travaglini@arm.com 66813481Sgiacomo.travaglini@arm.com``` 66913481Sgiacomo.travaglini@arm.comusing ::testing::AllOf; 67013481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 67113481Sgiacomo.travaglini@arm.comusing ::testing::HasSubstr; 67213481Sgiacomo.travaglini@arm.comusing ::testing::Ne; 67313481Sgiacomo.travaglini@arm.comusing ::testing::Not; 67413481Sgiacomo.travaglini@arm.com... 67513481Sgiacomo.travaglini@arm.com // The argument must be > 5 and != 10. 67613481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(AllOf(Gt(5), 67713481Sgiacomo.travaglini@arm.com Ne(10)))); 67813481Sgiacomo.travaglini@arm.com 67913481Sgiacomo.travaglini@arm.com // The first argument must not contain sub-string "blah". 68013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")), 68113481Sgiacomo.travaglini@arm.com NULL)); 68213481Sgiacomo.travaglini@arm.com``` 68313481Sgiacomo.travaglini@arm.com 68413481Sgiacomo.travaglini@arm.com## Casting Matchers ## 68513481Sgiacomo.travaglini@arm.com 68613481Sgiacomo.travaglini@arm.comGoogle Mock matchers are statically typed, meaning that the compiler 68713481Sgiacomo.travaglini@arm.comcan catch your mistake if you use a matcher of the wrong type (for 68813481Sgiacomo.travaglini@arm.comexample, if you use `Eq(5)` to match a `string` argument). Good for 68913481Sgiacomo.travaglini@arm.comyou! 69013481Sgiacomo.travaglini@arm.com 69113481Sgiacomo.travaglini@arm.comSometimes, however, you know what you're doing and want the compiler 69213481Sgiacomo.travaglini@arm.comto give you some slack. One example is that you have a matcher for 69313481Sgiacomo.travaglini@arm.com`long` and the argument you want to match is `int`. While the two 69413481Sgiacomo.travaglini@arm.comtypes aren't exactly the same, there is nothing really wrong with 69513481Sgiacomo.travaglini@arm.comusing a `Matcher<long>` to match an `int` - after all, we can first 69613481Sgiacomo.travaglini@arm.comconvert the `int` argument to a `long` before giving it to the 69713481Sgiacomo.travaglini@arm.commatcher. 69813481Sgiacomo.travaglini@arm.com 69913481Sgiacomo.travaglini@arm.comTo support this need, Google Mock gives you the 70013481Sgiacomo.travaglini@arm.com`SafeMatcherCast<T>(m)` function. It casts a matcher `m` to type 70113481Sgiacomo.travaglini@arm.com`Matcher<T>`. To ensure safety, Google Mock checks that (let `U` be the 70213481Sgiacomo.travaglini@arm.comtype `m` accepts): 70313481Sgiacomo.travaglini@arm.com 70413481Sgiacomo.travaglini@arm.com 1. Type `T` can be implicitly cast to type `U`; 70513481Sgiacomo.travaglini@arm.com 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 70613481Sgiacomo.travaglini@arm.com 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). 70713481Sgiacomo.travaglini@arm.com 70813481Sgiacomo.travaglini@arm.comThe code won't compile if any of these conditions isn't met. 70913481Sgiacomo.travaglini@arm.com 71013481Sgiacomo.travaglini@arm.comHere's one example: 71113481Sgiacomo.travaglini@arm.com 71213481Sgiacomo.travaglini@arm.com``` 71313481Sgiacomo.travaglini@arm.comusing ::testing::SafeMatcherCast; 71413481Sgiacomo.travaglini@arm.com 71513481Sgiacomo.travaglini@arm.com// A base class and a child class. 71613481Sgiacomo.travaglini@arm.comclass Base { ... }; 71713481Sgiacomo.travaglini@arm.comclass Derived : public Base { ... }; 71813481Sgiacomo.travaglini@arm.com 71913481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 72013481Sgiacomo.travaglini@arm.com public: 72113481Sgiacomo.travaglini@arm.com MOCK_METHOD1(DoThis, void(Derived* derived)); 72213481Sgiacomo.travaglini@arm.com}; 72313481Sgiacomo.travaglini@arm.com... 72413481Sgiacomo.travaglini@arm.com 72513481Sgiacomo.travaglini@arm.com MockFoo foo; 72613481Sgiacomo.travaglini@arm.com // m is a Matcher<Base*> we got from somewhere. 72713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m))); 72813481Sgiacomo.travaglini@arm.com``` 72913481Sgiacomo.travaglini@arm.com 73013481Sgiacomo.travaglini@arm.comIf you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar 73113481Sgiacomo.travaglini@arm.comfunction `MatcherCast<T>(m)`. The difference is that `MatcherCast` works 73213481Sgiacomo.travaglini@arm.comas long as you can `static_cast` type `T` to type `U`. 73313481Sgiacomo.travaglini@arm.com 73413481Sgiacomo.travaglini@arm.com`MatcherCast` essentially lets you bypass C++'s type system 73513481Sgiacomo.travaglini@arm.com(`static_cast` isn't always safe as it could throw away information, 73613481Sgiacomo.travaglini@arm.comfor example), so be careful not to misuse/abuse it. 73713481Sgiacomo.travaglini@arm.com 73813481Sgiacomo.travaglini@arm.com## Selecting Between Overloaded Functions ## 73913481Sgiacomo.travaglini@arm.com 74013481Sgiacomo.travaglini@arm.comIf you expect an overloaded function to be called, the compiler may 74113481Sgiacomo.travaglini@arm.comneed some help on which overloaded version it is. 74213481Sgiacomo.travaglini@arm.com 74313481Sgiacomo.travaglini@arm.comTo disambiguate functions overloaded on the const-ness of this object, 74413481Sgiacomo.travaglini@arm.comuse the `Const()` argument wrapper. 74513481Sgiacomo.travaglini@arm.com 74613481Sgiacomo.travaglini@arm.com``` 74713481Sgiacomo.travaglini@arm.comusing ::testing::ReturnRef; 74813481Sgiacomo.travaglini@arm.com 74913481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 75013481Sgiacomo.travaglini@arm.com ... 75113481Sgiacomo.travaglini@arm.com MOCK_METHOD0(GetBar, Bar&()); 75213481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD0(GetBar, const Bar&()); 75313481Sgiacomo.travaglini@arm.com}; 75413481Sgiacomo.travaglini@arm.com... 75513481Sgiacomo.travaglini@arm.com 75613481Sgiacomo.travaglini@arm.com MockFoo foo; 75713481Sgiacomo.travaglini@arm.com Bar bar1, bar2; 75813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, GetBar()) // The non-const GetBar(). 75913481Sgiacomo.travaglini@arm.com .WillOnce(ReturnRef(bar1)); 76013481Sgiacomo.travaglini@arm.com EXPECT_CALL(Const(foo), GetBar()) // The const GetBar(). 76113481Sgiacomo.travaglini@arm.com .WillOnce(ReturnRef(bar2)); 76213481Sgiacomo.travaglini@arm.com``` 76313481Sgiacomo.travaglini@arm.com 76413481Sgiacomo.travaglini@arm.com(`Const()` is defined by Google Mock and returns a `const` reference 76513481Sgiacomo.travaglini@arm.comto its argument.) 76613481Sgiacomo.travaglini@arm.com 76713481Sgiacomo.travaglini@arm.comTo disambiguate overloaded functions with the same number of arguments 76813481Sgiacomo.travaglini@arm.combut different argument types, you may need to specify the exact type 76913481Sgiacomo.travaglini@arm.comof a matcher, either by wrapping your matcher in `Matcher<type>()`, or 77013481Sgiacomo.travaglini@arm.comusing a matcher whose type is fixed (`TypedEq<type>`, `An<type>()`, 77113481Sgiacomo.travaglini@arm.cometc): 77213481Sgiacomo.travaglini@arm.com 77313481Sgiacomo.travaglini@arm.com``` 77413481Sgiacomo.travaglini@arm.comusing ::testing::An; 77513481Sgiacomo.travaglini@arm.comusing ::testing::Lt; 77613481Sgiacomo.travaglini@arm.comusing ::testing::Matcher; 77713481Sgiacomo.travaglini@arm.comusing ::testing::TypedEq; 77813481Sgiacomo.travaglini@arm.com 77913481Sgiacomo.travaglini@arm.comclass MockPrinter : public Printer { 78013481Sgiacomo.travaglini@arm.com public: 78113481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Print, void(int n)); 78213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Print, void(char c)); 78313481Sgiacomo.travaglini@arm.com}; 78413481Sgiacomo.travaglini@arm.com 78513481Sgiacomo.travaglini@arm.comTEST(PrinterTest, Print) { 78613481Sgiacomo.travaglini@arm.com MockPrinter printer; 78713481Sgiacomo.travaglini@arm.com 78813481Sgiacomo.travaglini@arm.com EXPECT_CALL(printer, Print(An<int>())); // void Print(int); 78913481Sgiacomo.travaglini@arm.com EXPECT_CALL(printer, Print(Matcher<int>(Lt(5)))); // void Print(int); 79013481Sgiacomo.travaglini@arm.com EXPECT_CALL(printer, Print(TypedEq<char>('a'))); // void Print(char); 79113481Sgiacomo.travaglini@arm.com 79213481Sgiacomo.travaglini@arm.com printer.Print(3); 79313481Sgiacomo.travaglini@arm.com printer.Print(6); 79413481Sgiacomo.travaglini@arm.com printer.Print('a'); 79513481Sgiacomo.travaglini@arm.com} 79613481Sgiacomo.travaglini@arm.com``` 79713481Sgiacomo.travaglini@arm.com 79813481Sgiacomo.travaglini@arm.com## Performing Different Actions Based on the Arguments ## 79913481Sgiacomo.travaglini@arm.com 80013481Sgiacomo.travaglini@arm.comWhen a mock method is called, the _last_ matching expectation that's 80113481Sgiacomo.travaglini@arm.comstill active will be selected (think "newer overrides older"). So, you 80213481Sgiacomo.travaglini@arm.comcan make a method do different things depending on its argument values 80313481Sgiacomo.travaglini@arm.comlike this: 80413481Sgiacomo.travaglini@arm.com 80513481Sgiacomo.travaglini@arm.com``` 80613481Sgiacomo.travaglini@arm.comusing ::testing::_; 80713481Sgiacomo.travaglini@arm.comusing ::testing::Lt; 80813481Sgiacomo.travaglini@arm.comusing ::testing::Return; 80913481Sgiacomo.travaglini@arm.com... 81013481Sgiacomo.travaglini@arm.com // The default case. 81113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(_)) 81213481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return('b')); 81313481Sgiacomo.travaglini@arm.com 81413481Sgiacomo.travaglini@arm.com // The more specific case. 81513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(Lt(5))) 81613481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return('a')); 81713481Sgiacomo.travaglini@arm.com``` 81813481Sgiacomo.travaglini@arm.com 81913481Sgiacomo.travaglini@arm.comNow, if `foo.DoThis()` is called with a value less than 5, `'a'` will 82013481Sgiacomo.travaglini@arm.combe returned; otherwise `'b'` will be returned. 82113481Sgiacomo.travaglini@arm.com 82213481Sgiacomo.travaglini@arm.com## Matching Multiple Arguments as a Whole ## 82313481Sgiacomo.travaglini@arm.com 82413481Sgiacomo.travaglini@arm.comSometimes it's not enough to match the arguments individually. For 82513481Sgiacomo.travaglini@arm.comexample, we may want to say that the first argument must be less than 82613481Sgiacomo.travaglini@arm.comthe second argument. The `With()` clause allows us to match 82713481Sgiacomo.travaglini@arm.comall arguments of a mock function as a whole. For example, 82813481Sgiacomo.travaglini@arm.com 82913481Sgiacomo.travaglini@arm.com``` 83013481Sgiacomo.travaglini@arm.comusing ::testing::_; 83113481Sgiacomo.travaglini@arm.comusing ::testing::Lt; 83213481Sgiacomo.travaglini@arm.comusing ::testing::Ne; 83313481Sgiacomo.travaglini@arm.com... 83413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, InRange(Ne(0), _)) 83513481Sgiacomo.travaglini@arm.com .With(Lt()); 83613481Sgiacomo.travaglini@arm.com``` 83713481Sgiacomo.travaglini@arm.com 83813481Sgiacomo.travaglini@arm.comsays that the first argument of `InRange()` must not be 0, and must be 83913481Sgiacomo.travaglini@arm.comless than the second argument. 84013481Sgiacomo.travaglini@arm.com 84113481Sgiacomo.travaglini@arm.comThe expression inside `With()` must be a matcher of type 84213481Sgiacomo.travaglini@arm.com`Matcher<tr1::tuple<A1, ..., An> >`, where `A1`, ..., `An` are the 84313481Sgiacomo.travaglini@arm.comtypes of the function arguments. 84413481Sgiacomo.travaglini@arm.com 84513481Sgiacomo.travaglini@arm.comYou can also write `AllArgs(m)` instead of `m` inside `.With()`. The 84613481Sgiacomo.travaglini@arm.comtwo forms are equivalent, but `.With(AllArgs(Lt()))` is more readable 84713481Sgiacomo.travaglini@arm.comthan `.With(Lt())`. 84813481Sgiacomo.travaglini@arm.com 84913481Sgiacomo.travaglini@arm.comYou can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments 85013481Sgiacomo.travaglini@arm.com(as a tuple) against `m`. For example, 85113481Sgiacomo.travaglini@arm.com 85213481Sgiacomo.travaglini@arm.com``` 85313481Sgiacomo.travaglini@arm.comusing ::testing::_; 85413481Sgiacomo.travaglini@arm.comusing ::testing::AllOf; 85513481Sgiacomo.travaglini@arm.comusing ::testing::Args; 85613481Sgiacomo.travaglini@arm.comusing ::testing::Lt; 85713481Sgiacomo.travaglini@arm.com... 85813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Blah(_, _, _)) 85913481Sgiacomo.travaglini@arm.com .With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt()))); 86013481Sgiacomo.travaglini@arm.com``` 86113481Sgiacomo.travaglini@arm.com 86213481Sgiacomo.travaglini@arm.comsays that `Blah()` will be called with arguments `x`, `y`, and `z` where 86313481Sgiacomo.travaglini@arm.com`x < y < z`. 86413481Sgiacomo.travaglini@arm.com 86513481Sgiacomo.travaglini@arm.comAs a convenience and example, Google Mock provides some matchers for 86613481Sgiacomo.travaglini@arm.com2-tuples, including the `Lt()` matcher above. See the [CheatSheet](V1_7_CheatSheet.md) for 86713481Sgiacomo.travaglini@arm.comthe complete list. 86813481Sgiacomo.travaglini@arm.com 86913481Sgiacomo.travaglini@arm.comNote that if you want to pass the arguments to a predicate of your own 87013481Sgiacomo.travaglini@arm.com(e.g. `.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be 87113481Sgiacomo.travaglini@arm.comwritten to take a `tr1::tuple` as its argument; Google Mock will pass the `n` 87213481Sgiacomo.travaglini@arm.comselected arguments as _one_ single tuple to the predicate. 87313481Sgiacomo.travaglini@arm.com 87413481Sgiacomo.travaglini@arm.com## Using Matchers as Predicates ## 87513481Sgiacomo.travaglini@arm.com 87613481Sgiacomo.travaglini@arm.comHave you noticed that a matcher is just a fancy predicate that also 87713481Sgiacomo.travaglini@arm.comknows how to describe itself? Many existing algorithms take predicates 87813481Sgiacomo.travaglini@arm.comas arguments (e.g. those defined in STL's `<algorithm>` header), and 87913481Sgiacomo.travaglini@arm.comit would be a shame if Google Mock matchers are not allowed to 88013481Sgiacomo.travaglini@arm.comparticipate. 88113481Sgiacomo.travaglini@arm.com 88213481Sgiacomo.travaglini@arm.comLuckily, you can use a matcher where a unary predicate functor is 88313481Sgiacomo.travaglini@arm.comexpected by wrapping it inside the `Matches()` function. For example, 88413481Sgiacomo.travaglini@arm.com 88513481Sgiacomo.travaglini@arm.com``` 88613481Sgiacomo.travaglini@arm.com#include <algorithm> 88713481Sgiacomo.travaglini@arm.com#include <vector> 88813481Sgiacomo.travaglini@arm.com 88913481Sgiacomo.travaglini@arm.comstd::vector<int> v; 89013481Sgiacomo.travaglini@arm.com... 89113481Sgiacomo.travaglini@arm.com// How many elements in v are >= 10? 89213481Sgiacomo.travaglini@arm.comconst int count = count_if(v.begin(), v.end(), Matches(Ge(10))); 89313481Sgiacomo.travaglini@arm.com``` 89413481Sgiacomo.travaglini@arm.com 89513481Sgiacomo.travaglini@arm.comSince you can build complex matchers from simpler ones easily using 89613481Sgiacomo.travaglini@arm.comGoogle Mock, this gives you a way to conveniently construct composite 89713481Sgiacomo.travaglini@arm.compredicates (doing the same using STL's `<functional>` header is just 89813481Sgiacomo.travaglini@arm.compainful). For example, here's a predicate that's satisfied by any 89913481Sgiacomo.travaglini@arm.comnumber that is >= 0, <= 100, and != 50: 90013481Sgiacomo.travaglini@arm.com 90113481Sgiacomo.travaglini@arm.com``` 90213481Sgiacomo.travaglini@arm.comMatches(AllOf(Ge(0), Le(100), Ne(50))) 90313481Sgiacomo.travaglini@arm.com``` 90413481Sgiacomo.travaglini@arm.com 90513481Sgiacomo.travaglini@arm.com## Using Matchers in Google Test Assertions ## 90613481Sgiacomo.travaglini@arm.com 90713481Sgiacomo.travaglini@arm.comSince matchers are basically predicates that also know how to describe 90813481Sgiacomo.travaglini@arm.comthemselves, there is a way to take advantage of them in 90913481Sgiacomo.travaglini@arm.com[Google Test](http://code.google.com/p/googletest/) assertions. It's 91013481Sgiacomo.travaglini@arm.comcalled `ASSERT_THAT` and `EXPECT_THAT`: 91113481Sgiacomo.travaglini@arm.com 91213481Sgiacomo.travaglini@arm.com``` 91313481Sgiacomo.travaglini@arm.com ASSERT_THAT(value, matcher); // Asserts that value matches matcher. 91413481Sgiacomo.travaglini@arm.com EXPECT_THAT(value, matcher); // The non-fatal version. 91513481Sgiacomo.travaglini@arm.com``` 91613481Sgiacomo.travaglini@arm.com 91713481Sgiacomo.travaglini@arm.comFor example, in a Google Test test you can write: 91813481Sgiacomo.travaglini@arm.com 91913481Sgiacomo.travaglini@arm.com``` 92013481Sgiacomo.travaglini@arm.com#include "gmock/gmock.h" 92113481Sgiacomo.travaglini@arm.com 92213481Sgiacomo.travaglini@arm.comusing ::testing::AllOf; 92313481Sgiacomo.travaglini@arm.comusing ::testing::Ge; 92413481Sgiacomo.travaglini@arm.comusing ::testing::Le; 92513481Sgiacomo.travaglini@arm.comusing ::testing::MatchesRegex; 92613481Sgiacomo.travaglini@arm.comusing ::testing::StartsWith; 92713481Sgiacomo.travaglini@arm.com... 92813481Sgiacomo.travaglini@arm.com 92913481Sgiacomo.travaglini@arm.com EXPECT_THAT(Foo(), StartsWith("Hello")); 93013481Sgiacomo.travaglini@arm.com EXPECT_THAT(Bar(), MatchesRegex("Line \\d+")); 93113481Sgiacomo.travaglini@arm.com ASSERT_THAT(Baz(), AllOf(Ge(5), Le(10))); 93213481Sgiacomo.travaglini@arm.com``` 93313481Sgiacomo.travaglini@arm.com 93413481Sgiacomo.travaglini@arm.comwhich (as you can probably guess) executes `Foo()`, `Bar()`, and 93513481Sgiacomo.travaglini@arm.com`Baz()`, and verifies that: 93613481Sgiacomo.travaglini@arm.com 93713481Sgiacomo.travaglini@arm.com * `Foo()` returns a string that starts with `"Hello"`. 93813481Sgiacomo.travaglini@arm.com * `Bar()` returns a string that matches regular expression `"Line \\d+"`. 93913481Sgiacomo.travaglini@arm.com * `Baz()` returns a number in the range [5, 10]. 94013481Sgiacomo.travaglini@arm.com 94113481Sgiacomo.travaglini@arm.comThe nice thing about these macros is that _they read like 94213481Sgiacomo.travaglini@arm.comEnglish_. They generate informative messages too. For example, if the 94313481Sgiacomo.travaglini@arm.comfirst `EXPECT_THAT()` above fails, the message will be something like: 94413481Sgiacomo.travaglini@arm.com 94513481Sgiacomo.travaglini@arm.com``` 94613481Sgiacomo.travaglini@arm.comValue of: Foo() 94713481Sgiacomo.travaglini@arm.com Actual: "Hi, world!" 94813481Sgiacomo.travaglini@arm.comExpected: starts with "Hello" 94913481Sgiacomo.travaglini@arm.com``` 95013481Sgiacomo.travaglini@arm.com 95113481Sgiacomo.travaglini@arm.com**Credit:** The idea of `(ASSERT|EXPECT)_THAT` was stolen from the 95213481Sgiacomo.travaglini@arm.com[Hamcrest](http://code.google.com/p/hamcrest/) project, which adds 95313481Sgiacomo.travaglini@arm.com`assertThat()` to JUnit. 95413481Sgiacomo.travaglini@arm.com 95513481Sgiacomo.travaglini@arm.com## Using Predicates as Matchers ## 95613481Sgiacomo.travaglini@arm.com 95713481Sgiacomo.travaglini@arm.comGoogle Mock provides a built-in set of matchers. In case you find them 95813481Sgiacomo.travaglini@arm.comlacking, you can use an arbitray unary predicate function or functor 95913481Sgiacomo.travaglini@arm.comas a matcher - as long as the predicate accepts a value of the type 96013481Sgiacomo.travaglini@arm.comyou want. You do this by wrapping the predicate inside the `Truly()` 96113481Sgiacomo.travaglini@arm.comfunction, for example: 96213481Sgiacomo.travaglini@arm.com 96313481Sgiacomo.travaglini@arm.com``` 96413481Sgiacomo.travaglini@arm.comusing ::testing::Truly; 96513481Sgiacomo.travaglini@arm.com 96613481Sgiacomo.travaglini@arm.comint IsEven(int n) { return (n % 2) == 0 ? 1 : 0; } 96713481Sgiacomo.travaglini@arm.com... 96813481Sgiacomo.travaglini@arm.com 96913481Sgiacomo.travaglini@arm.com // Bar() must be called with an even number. 97013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(Truly(IsEven))); 97113481Sgiacomo.travaglini@arm.com``` 97213481Sgiacomo.travaglini@arm.com 97313481Sgiacomo.travaglini@arm.comNote that the predicate function / functor doesn't have to return 97413481Sgiacomo.travaglini@arm.com`bool`. It works as long as the return value can be used as the 97513481Sgiacomo.travaglini@arm.comcondition in statement `if (condition) ...`. 97613481Sgiacomo.travaglini@arm.com 97713481Sgiacomo.travaglini@arm.com## Matching Arguments that Are Not Copyable ## 97813481Sgiacomo.travaglini@arm.com 97913481Sgiacomo.travaglini@arm.comWhen you do an `EXPECT_CALL(mock_obj, Foo(bar))`, Google Mock saves 98013481Sgiacomo.travaglini@arm.comaway a copy of `bar`. When `Foo()` is called later, Google Mock 98113481Sgiacomo.travaglini@arm.comcompares the argument to `Foo()` with the saved copy of `bar`. This 98213481Sgiacomo.travaglini@arm.comway, you don't need to worry about `bar` being modified or destroyed 98313481Sgiacomo.travaglini@arm.comafter the `EXPECT_CALL()` is executed. The same is true when you use 98413481Sgiacomo.travaglini@arm.commatchers like `Eq(bar)`, `Le(bar)`, and so on. 98513481Sgiacomo.travaglini@arm.com 98613481Sgiacomo.travaglini@arm.comBut what if `bar` cannot be copied (i.e. has no copy constructor)? You 98713481Sgiacomo.travaglini@arm.comcould define your own matcher function and use it with `Truly()`, as 98813481Sgiacomo.travaglini@arm.comthe previous couple of recipes have shown. Or, you may be able to get 98913481Sgiacomo.travaglini@arm.comaway from it if you can guarantee that `bar` won't be changed after 99013481Sgiacomo.travaglini@arm.comthe `EXPECT_CALL()` is executed. Just tell Google Mock that it should 99113481Sgiacomo.travaglini@arm.comsave a reference to `bar`, instead of a copy of it. Here's how: 99213481Sgiacomo.travaglini@arm.com 99313481Sgiacomo.travaglini@arm.com``` 99413481Sgiacomo.travaglini@arm.comusing ::testing::Eq; 99513481Sgiacomo.travaglini@arm.comusing ::testing::ByRef; 99613481Sgiacomo.travaglini@arm.comusing ::testing::Lt; 99713481Sgiacomo.travaglini@arm.com... 99813481Sgiacomo.travaglini@arm.com // Expects that Foo()'s argument == bar. 99913481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_obj, Foo(Eq(ByRef(bar)))); 100013481Sgiacomo.travaglini@arm.com 100113481Sgiacomo.travaglini@arm.com // Expects that Foo()'s argument < bar. 100213481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_obj, Foo(Lt(ByRef(bar)))); 100313481Sgiacomo.travaglini@arm.com``` 100413481Sgiacomo.travaglini@arm.com 100513481Sgiacomo.travaglini@arm.comRemember: if you do this, don't change `bar` after the 100613481Sgiacomo.travaglini@arm.com`EXPECT_CALL()`, or the result is undefined. 100713481Sgiacomo.travaglini@arm.com 100813481Sgiacomo.travaglini@arm.com## Validating a Member of an Object ## 100913481Sgiacomo.travaglini@arm.com 101013481Sgiacomo.travaglini@arm.comOften a mock function takes a reference to object as an argument. When 101113481Sgiacomo.travaglini@arm.commatching the argument, you may not want to compare the entire object 101213481Sgiacomo.travaglini@arm.comagainst a fixed object, as that may be over-specification. Instead, 101313481Sgiacomo.travaglini@arm.comyou may need to validate a certain member variable or the result of a 101413481Sgiacomo.travaglini@arm.comcertain getter method of the object. You can do this with `Field()` 101513481Sgiacomo.travaglini@arm.comand `Property()`. More specifically, 101613481Sgiacomo.travaglini@arm.com 101713481Sgiacomo.travaglini@arm.com``` 101813481Sgiacomo.travaglini@arm.comField(&Foo::bar, m) 101913481Sgiacomo.travaglini@arm.com``` 102013481Sgiacomo.travaglini@arm.com 102113481Sgiacomo.travaglini@arm.comis a matcher that matches a `Foo` object whose `bar` member variable 102213481Sgiacomo.travaglini@arm.comsatisfies matcher `m`. 102313481Sgiacomo.travaglini@arm.com 102413481Sgiacomo.travaglini@arm.com``` 102513481Sgiacomo.travaglini@arm.comProperty(&Foo::baz, m) 102613481Sgiacomo.travaglini@arm.com``` 102713481Sgiacomo.travaglini@arm.com 102813481Sgiacomo.travaglini@arm.comis a matcher that matches a `Foo` object whose `baz()` method returns 102913481Sgiacomo.travaglini@arm.coma value that satisfies matcher `m`. 103013481Sgiacomo.travaglini@arm.com 103113481Sgiacomo.travaglini@arm.comFor example: 103213481Sgiacomo.travaglini@arm.com 103313481Sgiacomo.travaglini@arm.com> | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. | 103413481Sgiacomo.travaglini@arm.com|:-----------------------------|:-----------------------------------| 103513481Sgiacomo.travaglini@arm.com> | `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. | 103613481Sgiacomo.travaglini@arm.com 103713481Sgiacomo.travaglini@arm.comNote that in `Property(&Foo::baz, ...)`, method `baz()` must take no 103813481Sgiacomo.travaglini@arm.comargument and be declared as `const`. 103913481Sgiacomo.travaglini@arm.com 104013481Sgiacomo.travaglini@arm.comBTW, `Field()` and `Property()` can also match plain pointers to 104113481Sgiacomo.travaglini@arm.comobjects. For instance, 104213481Sgiacomo.travaglini@arm.com 104313481Sgiacomo.travaglini@arm.com``` 104413481Sgiacomo.travaglini@arm.comField(&Foo::number, Ge(3)) 104513481Sgiacomo.travaglini@arm.com``` 104613481Sgiacomo.travaglini@arm.com 104713481Sgiacomo.travaglini@arm.commatches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, 104813481Sgiacomo.travaglini@arm.comthe match will always fail regardless of the inner matcher. 104913481Sgiacomo.travaglini@arm.com 105013481Sgiacomo.travaglini@arm.comWhat if you want to validate more than one members at the same time? 105113481Sgiacomo.travaglini@arm.comRemember that there is `AllOf()`. 105213481Sgiacomo.travaglini@arm.com 105313481Sgiacomo.travaglini@arm.com## Validating the Value Pointed to by a Pointer Argument ## 105413481Sgiacomo.travaglini@arm.com 105513481Sgiacomo.travaglini@arm.comC++ functions often take pointers as arguments. You can use matchers 105613481Sgiacomo.travaglini@arm.comlike `IsNull()`, `NotNull()`, and other comparison matchers to match a 105713481Sgiacomo.travaglini@arm.compointer, but what if you want to make sure the value _pointed to_ by 105813481Sgiacomo.travaglini@arm.comthe pointer, instead of the pointer itself, has a certain property? 105913481Sgiacomo.travaglini@arm.comWell, you can use the `Pointee(m)` matcher. 106013481Sgiacomo.travaglini@arm.com 106113481Sgiacomo.travaglini@arm.com`Pointee(m)` matches a pointer iff `m` matches the value the pointer 106213481Sgiacomo.travaglini@arm.compoints to. For example: 106313481Sgiacomo.travaglini@arm.com 106413481Sgiacomo.travaglini@arm.com``` 106513481Sgiacomo.travaglini@arm.comusing ::testing::Ge; 106613481Sgiacomo.travaglini@arm.comusing ::testing::Pointee; 106713481Sgiacomo.travaglini@arm.com... 106813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(Pointee(Ge(3)))); 106913481Sgiacomo.travaglini@arm.com``` 107013481Sgiacomo.travaglini@arm.com 107113481Sgiacomo.travaglini@arm.comexpects `foo.Bar()` to be called with a pointer that points to a value 107213481Sgiacomo.travaglini@arm.comgreater than or equal to 3. 107313481Sgiacomo.travaglini@arm.com 107413481Sgiacomo.travaglini@arm.comOne nice thing about `Pointee()` is that it treats a `NULL` pointer as 107513481Sgiacomo.travaglini@arm.coma match failure, so you can write `Pointee(m)` instead of 107613481Sgiacomo.travaglini@arm.com 107713481Sgiacomo.travaglini@arm.com``` 107813481Sgiacomo.travaglini@arm.com AllOf(NotNull(), Pointee(m)) 107913481Sgiacomo.travaglini@arm.com``` 108013481Sgiacomo.travaglini@arm.com 108113481Sgiacomo.travaglini@arm.comwithout worrying that a `NULL` pointer will crash your test. 108213481Sgiacomo.travaglini@arm.com 108313481Sgiacomo.travaglini@arm.comAlso, did we tell you that `Pointee()` works with both raw pointers 108413481Sgiacomo.travaglini@arm.com**and** smart pointers (`linked_ptr`, `shared_ptr`, `scoped_ptr`, and 108513481Sgiacomo.travaglini@arm.cometc)? 108613481Sgiacomo.travaglini@arm.com 108713481Sgiacomo.travaglini@arm.comWhat if you have a pointer to pointer? You guessed it - you can use 108813481Sgiacomo.travaglini@arm.comnested `Pointee()` to probe deeper inside the value. For example, 108913481Sgiacomo.travaglini@arm.com`Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer 109013481Sgiacomo.travaglini@arm.comthat points to a number less than 3 (what a mouthful...). 109113481Sgiacomo.travaglini@arm.com 109213481Sgiacomo.travaglini@arm.com## Testing a Certain Property of an Object ## 109313481Sgiacomo.travaglini@arm.com 109413481Sgiacomo.travaglini@arm.comSometimes you want to specify that an object argument has a certain 109513481Sgiacomo.travaglini@arm.comproperty, but there is no existing matcher that does this. If you want 109613481Sgiacomo.travaglini@arm.comgood error messages, you should define a matcher. If you want to do it 109713481Sgiacomo.travaglini@arm.comquick and dirty, you could get away with writing an ordinary function. 109813481Sgiacomo.travaglini@arm.com 109913481Sgiacomo.travaglini@arm.comLet's say you have a mock function that takes an object of type `Foo`, 110013481Sgiacomo.travaglini@arm.comwhich has an `int bar()` method and an `int baz()` method, and you 110113481Sgiacomo.travaglini@arm.comwant to constrain that the argument's `bar()` value plus its `baz()` 110213481Sgiacomo.travaglini@arm.comvalue is a given number. Here's how you can define a matcher to do it: 110313481Sgiacomo.travaglini@arm.com 110413481Sgiacomo.travaglini@arm.com``` 110513481Sgiacomo.travaglini@arm.comusing ::testing::MatcherInterface; 110613481Sgiacomo.travaglini@arm.comusing ::testing::MatchResultListener; 110713481Sgiacomo.travaglini@arm.com 110813481Sgiacomo.travaglini@arm.comclass BarPlusBazEqMatcher : public MatcherInterface<const Foo&> { 110913481Sgiacomo.travaglini@arm.com public: 111013481Sgiacomo.travaglini@arm.com explicit BarPlusBazEqMatcher(int expected_sum) 111113481Sgiacomo.travaglini@arm.com : expected_sum_(expected_sum) {} 111213481Sgiacomo.travaglini@arm.com 111313481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(const Foo& foo, 111413481Sgiacomo.travaglini@arm.com MatchResultListener* listener) const { 111513481Sgiacomo.travaglini@arm.com return (foo.bar() + foo.baz()) == expected_sum_; 111613481Sgiacomo.travaglini@arm.com } 111713481Sgiacomo.travaglini@arm.com 111813481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const { 111913481Sgiacomo.travaglini@arm.com *os << "bar() + baz() equals " << expected_sum_; 112013481Sgiacomo.travaglini@arm.com } 112113481Sgiacomo.travaglini@arm.com 112213481Sgiacomo.travaglini@arm.com virtual void DescribeNegationTo(::std::ostream* os) const { 112313481Sgiacomo.travaglini@arm.com *os << "bar() + baz() does not equal " << expected_sum_; 112413481Sgiacomo.travaglini@arm.com } 112513481Sgiacomo.travaglini@arm.com private: 112613481Sgiacomo.travaglini@arm.com const int expected_sum_; 112713481Sgiacomo.travaglini@arm.com}; 112813481Sgiacomo.travaglini@arm.com 112913481Sgiacomo.travaglini@arm.cominline Matcher<const Foo&> BarPlusBazEq(int expected_sum) { 113013481Sgiacomo.travaglini@arm.com return MakeMatcher(new BarPlusBazEqMatcher(expected_sum)); 113113481Sgiacomo.travaglini@arm.com} 113213481Sgiacomo.travaglini@arm.com 113313481Sgiacomo.travaglini@arm.com... 113413481Sgiacomo.travaglini@arm.com 113513481Sgiacomo.travaglini@arm.com EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...; 113613481Sgiacomo.travaglini@arm.com``` 113713481Sgiacomo.travaglini@arm.com 113813481Sgiacomo.travaglini@arm.com## Matching Containers ## 113913481Sgiacomo.travaglini@arm.com 114013481Sgiacomo.travaglini@arm.comSometimes an STL container (e.g. list, vector, map, ...) is passed to 114113481Sgiacomo.travaglini@arm.coma mock function and you may want to validate it. Since most STL 114213481Sgiacomo.travaglini@arm.comcontainers support the `==` operator, you can write 114313481Sgiacomo.travaglini@arm.com`Eq(expected_container)` or simply `expected_container` to match a 114413481Sgiacomo.travaglini@arm.comcontainer exactly. 114513481Sgiacomo.travaglini@arm.com 114613481Sgiacomo.travaglini@arm.comSometimes, though, you may want to be more flexible (for example, the 114713481Sgiacomo.travaglini@arm.comfirst element must be an exact match, but the second element can be 114813481Sgiacomo.travaglini@arm.comany positive number, and so on). Also, containers used in tests often 114913481Sgiacomo.travaglini@arm.comhave a small number of elements, and having to define the expected 115013481Sgiacomo.travaglini@arm.comcontainer out-of-line is a bit of a hassle. 115113481Sgiacomo.travaglini@arm.com 115213481Sgiacomo.travaglini@arm.comYou can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in 115313481Sgiacomo.travaglini@arm.comsuch cases: 115413481Sgiacomo.travaglini@arm.com 115513481Sgiacomo.travaglini@arm.com``` 115613481Sgiacomo.travaglini@arm.comusing ::testing::_; 115713481Sgiacomo.travaglini@arm.comusing ::testing::ElementsAre; 115813481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 115913481Sgiacomo.travaglini@arm.com... 116013481Sgiacomo.travaglini@arm.com 116113481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Foo, void(const vector<int>& numbers)); 116213481Sgiacomo.travaglini@arm.com... 116313481Sgiacomo.travaglini@arm.com 116413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5))); 116513481Sgiacomo.travaglini@arm.com``` 116613481Sgiacomo.travaglini@arm.com 116713481Sgiacomo.travaglini@arm.comThe above matcher says that the container must have 4 elements, which 116813481Sgiacomo.travaglini@arm.commust be 1, greater than 0, anything, and 5 respectively. 116913481Sgiacomo.travaglini@arm.com 117013481Sgiacomo.travaglini@arm.comIf you instead write: 117113481Sgiacomo.travaglini@arm.com 117213481Sgiacomo.travaglini@arm.com``` 117313481Sgiacomo.travaglini@arm.comusing ::testing::_; 117413481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 117513481Sgiacomo.travaglini@arm.comusing ::testing::UnorderedElementsAre; 117613481Sgiacomo.travaglini@arm.com... 117713481Sgiacomo.travaglini@arm.com 117813481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Foo, void(const vector<int>& numbers)); 117913481Sgiacomo.travaglini@arm.com... 118013481Sgiacomo.travaglini@arm.com 118113481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5))); 118213481Sgiacomo.travaglini@arm.com``` 118313481Sgiacomo.travaglini@arm.com 118413481Sgiacomo.travaglini@arm.comIt means that the container must have 4 elements, which under some 118513481Sgiacomo.travaglini@arm.compermutation must be 1, greater than 0, anything, and 5 respectively. 118613481Sgiacomo.travaglini@arm.com 118713481Sgiacomo.travaglini@arm.com`ElementsAre()` and `UnorderedElementsAre()` are overloaded to take 0 118813481Sgiacomo.travaglini@arm.comto 10 arguments. If more are needed, you can place them in a C-style 118913481Sgiacomo.travaglini@arm.comarray and use `ElementsAreArray()` or `UnorderedElementsAreArray()` 119013481Sgiacomo.travaglini@arm.cominstead: 119113481Sgiacomo.travaglini@arm.com 119213481Sgiacomo.travaglini@arm.com``` 119313481Sgiacomo.travaglini@arm.comusing ::testing::ElementsAreArray; 119413481Sgiacomo.travaglini@arm.com... 119513481Sgiacomo.travaglini@arm.com 119613481Sgiacomo.travaglini@arm.com // ElementsAreArray accepts an array of element values. 119713481Sgiacomo.travaglini@arm.com const int expected_vector1[] = { 1, 5, 2, 4, ... }; 119813481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1))); 119913481Sgiacomo.travaglini@arm.com 120013481Sgiacomo.travaglini@arm.com // Or, an array of element matchers. 120113481Sgiacomo.travaglini@arm.com Matcher<int> expected_vector2 = { 1, Gt(2), _, 3, ... }; 120213481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2))); 120313481Sgiacomo.travaglini@arm.com``` 120413481Sgiacomo.travaglini@arm.com 120513481Sgiacomo.travaglini@arm.comIn case the array needs to be dynamically created (and therefore the 120613481Sgiacomo.travaglini@arm.comarray size cannot be inferred by the compiler), you can give 120713481Sgiacomo.travaglini@arm.com`ElementsAreArray()` an additional argument to specify the array size: 120813481Sgiacomo.travaglini@arm.com 120913481Sgiacomo.travaglini@arm.com``` 121013481Sgiacomo.travaglini@arm.comusing ::testing::ElementsAreArray; 121113481Sgiacomo.travaglini@arm.com... 121213481Sgiacomo.travaglini@arm.com int* const expected_vector3 = new int[count]; 121313481Sgiacomo.travaglini@arm.com ... fill expected_vector3 with values ... 121413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count))); 121513481Sgiacomo.travaglini@arm.com``` 121613481Sgiacomo.travaglini@arm.com 121713481Sgiacomo.travaglini@arm.com**Tips:** 121813481Sgiacomo.travaglini@arm.com 121913481Sgiacomo.travaglini@arm.com * `ElementsAre*()` can be used to match _any_ container that implements the STL iterator pattern (i.e. it has a `const_iterator` type and supports `begin()/end()`), not just the ones defined in STL. It will even work with container types yet to be written - as long as they follows the above pattern. 122013481Sgiacomo.travaglini@arm.com * You can use nested `ElementsAre*()` to match nested (multi-dimensional) containers. 122113481Sgiacomo.travaglini@arm.com * If the container is passed by pointer instead of by reference, just write `Pointee(ElementsAre*(...))`. 122213481Sgiacomo.travaglini@arm.com * The order of elements _matters_ for `ElementsAre*()`. Therefore don't use it with containers whose element order is undefined (e.g. `hash_map`). 122313481Sgiacomo.travaglini@arm.com 122413481Sgiacomo.travaglini@arm.com## Sharing Matchers ## 122513481Sgiacomo.travaglini@arm.com 122613481Sgiacomo.travaglini@arm.comUnder the hood, a Google Mock matcher object consists of a pointer to 122713481Sgiacomo.travaglini@arm.coma ref-counted implementation object. Copying matchers is allowed and 122813481Sgiacomo.travaglini@arm.comvery efficient, as only the pointer is copied. When the last matcher 122913481Sgiacomo.travaglini@arm.comthat references the implementation object dies, the implementation 123013481Sgiacomo.travaglini@arm.comobject will be deleted. 123113481Sgiacomo.travaglini@arm.com 123213481Sgiacomo.travaglini@arm.comTherefore, if you have some complex matcher that you want to use again 123313481Sgiacomo.travaglini@arm.comand again, there is no need to build it everytime. Just assign it to a 123413481Sgiacomo.travaglini@arm.commatcher variable and use that variable repeatedly! For example, 123513481Sgiacomo.travaglini@arm.com 123613481Sgiacomo.travaglini@arm.com``` 123713481Sgiacomo.travaglini@arm.com Matcher<int> in_range = AllOf(Gt(5), Le(10)); 123813481Sgiacomo.travaglini@arm.com ... use in_range as a matcher in multiple EXPECT_CALLs ... 123913481Sgiacomo.travaglini@arm.com``` 124013481Sgiacomo.travaglini@arm.com 124113481Sgiacomo.travaglini@arm.com# Setting Expectations # 124213481Sgiacomo.travaglini@arm.com 124313481Sgiacomo.travaglini@arm.com## Knowing When to Expect ## 124413481Sgiacomo.travaglini@arm.com 124513481Sgiacomo.travaglini@arm.com`ON_CALL` is likely the single most under-utilized construct in Google Mock. 124613481Sgiacomo.travaglini@arm.com 124713481Sgiacomo.travaglini@arm.comThere are basically two constructs for defining the behavior of a mock object: `ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when a mock method is called, but _doesn't imply any expectation on the method being called._ `EXPECT_CALL` not only defines the behavior, but also sets an expectation that _the method will be called with the given arguments, for the given number of times_ (and _in the given order_ when you specify the order too). 124813481Sgiacomo.travaglini@arm.com 124913481Sgiacomo.travaglini@arm.comSince `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every `EXPECT_CALL` adds a constraint on the behavior of the code under test. Having more constraints than necessary is _baaad_ - even worse than not having enough constraints. 125013481Sgiacomo.travaglini@arm.com 125113481Sgiacomo.travaglini@arm.comThis may be counter-intuitive. How could tests that verify more be worse than tests that verify less? Isn't verification the whole point of tests? 125213481Sgiacomo.travaglini@arm.com 125313481Sgiacomo.travaglini@arm.comThe answer, lies in _what_ a test should verify. **A good test verifies the contract of the code.** If a test over-specifies, it doesn't leave enough freedom to the implementation. As a result, changing the implementation without breaking the contract (e.g. refactoring and optimization), which should be perfectly fine to do, can break such tests. Then you have to spend time fixing them, only to see them broken again the next time the implementation is changed. 125413481Sgiacomo.travaglini@arm.com 125513481Sgiacomo.travaglini@arm.comKeep in mind that one doesn't have to verify more than one property in one test. In fact, **it's a good style to verify only one thing in one test.** If you do that, a bug will likely break only one or two tests instead of dozens (which case would you rather debug?). If you are also in the habit of giving tests descriptive names that tell what they verify, you can often easily guess what's wrong just from the test log itself. 125613481Sgiacomo.travaglini@arm.com 125713481Sgiacomo.travaglini@arm.comSo use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend to verify that the call is made. For example, you may have a bunch of `ON_CALL`s in your test fixture to set the common mock behavior shared by all tests in the same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s to verify different aspects of the code's behavior. Compared with the style where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more resilient to implementational changes (and thus less likely to require maintenance) and makes the intent of the tests more obvious (so they are easier to maintain when you do need to maintain them). 125813481Sgiacomo.travaglini@arm.com 125913481Sgiacomo.travaglini@arm.com## Ignoring Uninteresting Calls ## 126013481Sgiacomo.travaglini@arm.com 126113481Sgiacomo.travaglini@arm.comIf you are not interested in how a mock method is called, just don't 126213481Sgiacomo.travaglini@arm.comsay anything about it. In this case, if the method is ever called, 126313481Sgiacomo.travaglini@arm.comGoogle Mock will perform its default action to allow the test program 126413481Sgiacomo.travaglini@arm.comto continue. If you are not happy with the default action taken by 126513481Sgiacomo.travaglini@arm.comGoogle Mock, you can override it using `DefaultValue<T>::Set()` 126613481Sgiacomo.travaglini@arm.com(described later in this document) or `ON_CALL()`. 126713481Sgiacomo.travaglini@arm.com 126813481Sgiacomo.travaglini@arm.comPlease note that once you expressed interest in a particular mock 126913481Sgiacomo.travaglini@arm.commethod (via `EXPECT_CALL()`), all invocations to it must match some 127013481Sgiacomo.travaglini@arm.comexpectation. If this function is called but the arguments don't match 127113481Sgiacomo.travaglini@arm.comany `EXPECT_CALL()` statement, it will be an error. 127213481Sgiacomo.travaglini@arm.com 127313481Sgiacomo.travaglini@arm.com## Disallowing Unexpected Calls ## 127413481Sgiacomo.travaglini@arm.com 127513481Sgiacomo.travaglini@arm.comIf a mock method shouldn't be called at all, explicitly say so: 127613481Sgiacomo.travaglini@arm.com 127713481Sgiacomo.travaglini@arm.com``` 127813481Sgiacomo.travaglini@arm.comusing ::testing::_; 127913481Sgiacomo.travaglini@arm.com... 128013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(_)) 128113481Sgiacomo.travaglini@arm.com .Times(0); 128213481Sgiacomo.travaglini@arm.com``` 128313481Sgiacomo.travaglini@arm.com 128413481Sgiacomo.travaglini@arm.comIf some calls to the method are allowed, but the rest are not, just 128513481Sgiacomo.travaglini@arm.comlist all the expected calls: 128613481Sgiacomo.travaglini@arm.com 128713481Sgiacomo.travaglini@arm.com``` 128813481Sgiacomo.travaglini@arm.comusing ::testing::AnyNumber; 128913481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 129013481Sgiacomo.travaglini@arm.com... 129113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(5)); 129213481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(Gt(10))) 129313481Sgiacomo.travaglini@arm.com .Times(AnyNumber()); 129413481Sgiacomo.travaglini@arm.com``` 129513481Sgiacomo.travaglini@arm.com 129613481Sgiacomo.travaglini@arm.comA call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` 129713481Sgiacomo.travaglini@arm.comstatements will be an error. 129813481Sgiacomo.travaglini@arm.com 129913481Sgiacomo.travaglini@arm.com## Expecting Ordered Calls ## 130013481Sgiacomo.travaglini@arm.com 130113481Sgiacomo.travaglini@arm.comAlthough an `EXPECT_CALL()` statement defined earlier takes precedence 130213481Sgiacomo.travaglini@arm.comwhen Google Mock tries to match a function call with an expectation, 130313481Sgiacomo.travaglini@arm.comby default calls don't have to happen in the order `EXPECT_CALL()` 130413481Sgiacomo.travaglini@arm.comstatements are written. For example, if the arguments match the 130513481Sgiacomo.travaglini@arm.commatchers in the third `EXPECT_CALL()`, but not those in the first two, 130613481Sgiacomo.travaglini@arm.comthen the third expectation will be used. 130713481Sgiacomo.travaglini@arm.com 130813481Sgiacomo.travaglini@arm.comIf you would rather have all calls occur in the order of the 130913481Sgiacomo.travaglini@arm.comexpectations, put the `EXPECT_CALL()` statements in a block where you 131013481Sgiacomo.travaglini@arm.comdefine a variable of type `InSequence`: 131113481Sgiacomo.travaglini@arm.com 131213481Sgiacomo.travaglini@arm.com``` 131313481Sgiacomo.travaglini@arm.com using ::testing::_; 131413481Sgiacomo.travaglini@arm.com using ::testing::InSequence; 131513481Sgiacomo.travaglini@arm.com 131613481Sgiacomo.travaglini@arm.com { 131713481Sgiacomo.travaglini@arm.com InSequence s; 131813481Sgiacomo.travaglini@arm.com 131913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(5)); 132013481Sgiacomo.travaglini@arm.com EXPECT_CALL(bar, DoThat(_)) 132113481Sgiacomo.travaglini@arm.com .Times(2); 132213481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(6)); 132313481Sgiacomo.travaglini@arm.com } 132413481Sgiacomo.travaglini@arm.com``` 132513481Sgiacomo.travaglini@arm.com 132613481Sgiacomo.travaglini@arm.comIn this example, we expect a call to `foo.DoThis(5)`, followed by two 132713481Sgiacomo.travaglini@arm.comcalls to `bar.DoThat()` where the argument can be anything, which are 132813481Sgiacomo.travaglini@arm.comin turn followed by a call to `foo.DoThis(6)`. If a call occurred 132913481Sgiacomo.travaglini@arm.comout-of-order, Google Mock will report an error. 133013481Sgiacomo.travaglini@arm.com 133113481Sgiacomo.travaglini@arm.com## Expecting Partially Ordered Calls ## 133213481Sgiacomo.travaglini@arm.com 133313481Sgiacomo.travaglini@arm.comSometimes requiring everything to occur in a predetermined order can 133413481Sgiacomo.travaglini@arm.comlead to brittle tests. For example, we may care about `A` occurring 133513481Sgiacomo.travaglini@arm.combefore both `B` and `C`, but aren't interested in the relative order 133613481Sgiacomo.travaglini@arm.comof `B` and `C`. In this case, the test should reflect our real intent, 133713481Sgiacomo.travaglini@arm.cominstead of being overly constraining. 133813481Sgiacomo.travaglini@arm.com 133913481Sgiacomo.travaglini@arm.comGoogle Mock allows you to impose an arbitrary DAG (directed acyclic 134013481Sgiacomo.travaglini@arm.comgraph) on the calls. One way to express the DAG is to use the 134113481Sgiacomo.travaglini@arm.com[After](http://code.google.com/p/googlemock/wiki/V1_7_CheatSheet#The_After_Clause) clause of `EXPECT_CALL`. 134213481Sgiacomo.travaglini@arm.com 134313481Sgiacomo.travaglini@arm.comAnother way is via the `InSequence()` clause (not the same as the 134413481Sgiacomo.travaglini@arm.com`InSequence` class), which we borrowed from jMock 2. It's less 134513481Sgiacomo.travaglini@arm.comflexible than `After()`, but more convenient when you have long chains 134613481Sgiacomo.travaglini@arm.comof sequential calls, as it doesn't require you to come up with 134713481Sgiacomo.travaglini@arm.comdifferent names for the expectations in the chains. Here's how it 134813481Sgiacomo.travaglini@arm.comworks: 134913481Sgiacomo.travaglini@arm.com 135013481Sgiacomo.travaglini@arm.comIf we view `EXPECT_CALL()` statements as nodes in a graph, and add an 135113481Sgiacomo.travaglini@arm.comedge from node A to node B wherever A must occur before B, we can get 135213481Sgiacomo.travaglini@arm.coma DAG. We use the term "sequence" to mean a directed path in this 135313481Sgiacomo.travaglini@arm.comDAG. Now, if we decompose the DAG into sequences, we just need to know 135413481Sgiacomo.travaglini@arm.comwhich sequences each `EXPECT_CALL()` belongs to in order to be able to 135513481Sgiacomo.travaglini@arm.comreconstruct the orginal DAG. 135613481Sgiacomo.travaglini@arm.com 135713481Sgiacomo.travaglini@arm.comSo, to specify the partial order on the expectations we need to do two 135813481Sgiacomo.travaglini@arm.comthings: first to define some `Sequence` objects, and then for each 135913481Sgiacomo.travaglini@arm.com`EXPECT_CALL()` say which `Sequence` objects it is part 136013481Sgiacomo.travaglini@arm.comof. Expectations in the same sequence must occur in the order they are 136113481Sgiacomo.travaglini@arm.comwritten. For example, 136213481Sgiacomo.travaglini@arm.com 136313481Sgiacomo.travaglini@arm.com``` 136413481Sgiacomo.travaglini@arm.com using ::testing::Sequence; 136513481Sgiacomo.travaglini@arm.com 136613481Sgiacomo.travaglini@arm.com Sequence s1, s2; 136713481Sgiacomo.travaglini@arm.com 136813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, A()) 136913481Sgiacomo.travaglini@arm.com .InSequence(s1, s2); 137013481Sgiacomo.travaglini@arm.com EXPECT_CALL(bar, B()) 137113481Sgiacomo.travaglini@arm.com .InSequence(s1); 137213481Sgiacomo.travaglini@arm.com EXPECT_CALL(bar, C()) 137313481Sgiacomo.travaglini@arm.com .InSequence(s2); 137413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, D()) 137513481Sgiacomo.travaglini@arm.com .InSequence(s2); 137613481Sgiacomo.travaglini@arm.com``` 137713481Sgiacomo.travaglini@arm.com 137813481Sgiacomo.travaglini@arm.comspecifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> 137913481Sgiacomo.travaglini@arm.comC -> D`): 138013481Sgiacomo.travaglini@arm.com 138113481Sgiacomo.travaglini@arm.com``` 138213481Sgiacomo.travaglini@arm.com +---> B 138313481Sgiacomo.travaglini@arm.com | 138413481Sgiacomo.travaglini@arm.com A ---| 138513481Sgiacomo.travaglini@arm.com | 138613481Sgiacomo.travaglini@arm.com +---> C ---> D 138713481Sgiacomo.travaglini@arm.com``` 138813481Sgiacomo.travaglini@arm.com 138913481Sgiacomo.travaglini@arm.comThis means that A must occur before B and C, and C must occur before 139013481Sgiacomo.travaglini@arm.comD. There's no restriction about the order other than these. 139113481Sgiacomo.travaglini@arm.com 139213481Sgiacomo.travaglini@arm.com## Controlling When an Expectation Retires ## 139313481Sgiacomo.travaglini@arm.com 139413481Sgiacomo.travaglini@arm.comWhen a mock method is called, Google Mock only consider expectations 139513481Sgiacomo.travaglini@arm.comthat are still active. An expectation is active when created, and 139613481Sgiacomo.travaglini@arm.combecomes inactive (aka _retires_) when a call that has to occur later 139713481Sgiacomo.travaglini@arm.comhas occurred. For example, in 139813481Sgiacomo.travaglini@arm.com 139913481Sgiacomo.travaglini@arm.com``` 140013481Sgiacomo.travaglini@arm.com using ::testing::_; 140113481Sgiacomo.travaglini@arm.com using ::testing::Sequence; 140213481Sgiacomo.travaglini@arm.com 140313481Sgiacomo.travaglini@arm.com Sequence s1, s2; 140413481Sgiacomo.travaglini@arm.com 140513481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1 140613481Sgiacomo.travaglini@arm.com .Times(AnyNumber()) 140713481Sgiacomo.travaglini@arm.com .InSequence(s1, s2); 140813481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2 140913481Sgiacomo.travaglini@arm.com .InSequence(s1); 141013481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3 141113481Sgiacomo.travaglini@arm.com .InSequence(s2); 141213481Sgiacomo.travaglini@arm.com``` 141313481Sgiacomo.travaglini@arm.com 141413481Sgiacomo.travaglini@arm.comas soon as either #2 or #3 is matched, #1 will retire. If a warning 141513481Sgiacomo.travaglini@arm.com`"File too large."` is logged after this, it will be an error. 141613481Sgiacomo.travaglini@arm.com 141713481Sgiacomo.travaglini@arm.comNote that an expectation doesn't retire automatically when it's 141813481Sgiacomo.travaglini@arm.comsaturated. For example, 141913481Sgiacomo.travaglini@arm.com 142013481Sgiacomo.travaglini@arm.com``` 142113481Sgiacomo.travaglini@arm.comusing ::testing::_; 142213481Sgiacomo.travaglini@arm.com... 142313481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, _)); // #1 142413481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2 142513481Sgiacomo.travaglini@arm.com``` 142613481Sgiacomo.travaglini@arm.com 142713481Sgiacomo.travaglini@arm.comsays that there will be exactly one warning with the message `"File 142813481Sgiacomo.travaglini@arm.comtoo large."`. If the second warning contains this message too, #2 will 142913481Sgiacomo.travaglini@arm.commatch again and result in an upper-bound-violated error. 143013481Sgiacomo.travaglini@arm.com 143113481Sgiacomo.travaglini@arm.comIf this is not what you want, you can ask an expectation to retire as 143213481Sgiacomo.travaglini@arm.comsoon as it becomes saturated: 143313481Sgiacomo.travaglini@arm.com 143413481Sgiacomo.travaglini@arm.com``` 143513481Sgiacomo.travaglini@arm.comusing ::testing::_; 143613481Sgiacomo.travaglini@arm.com... 143713481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, _)); // #1 143813481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2 143913481Sgiacomo.travaglini@arm.com .RetiresOnSaturation(); 144013481Sgiacomo.travaglini@arm.com``` 144113481Sgiacomo.travaglini@arm.com 144213481Sgiacomo.travaglini@arm.comHere #2 can be used only once, so if you have two warnings with the 144313481Sgiacomo.travaglini@arm.commessage `"File too large."`, the first will match #2 and the second 144413481Sgiacomo.travaglini@arm.comwill match #1 - there will be no error. 144513481Sgiacomo.travaglini@arm.com 144613481Sgiacomo.travaglini@arm.com# Using Actions # 144713481Sgiacomo.travaglini@arm.com 144813481Sgiacomo.travaglini@arm.com## Returning References from Mock Methods ## 144913481Sgiacomo.travaglini@arm.com 145013481Sgiacomo.travaglini@arm.comIf a mock function's return type is a reference, you need to use 145113481Sgiacomo.travaglini@arm.com`ReturnRef()` instead of `Return()` to return a result: 145213481Sgiacomo.travaglini@arm.com 145313481Sgiacomo.travaglini@arm.com``` 145413481Sgiacomo.travaglini@arm.comusing ::testing::ReturnRef; 145513481Sgiacomo.travaglini@arm.com 145613481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 145713481Sgiacomo.travaglini@arm.com public: 145813481Sgiacomo.travaglini@arm.com MOCK_METHOD0(GetBar, Bar&()); 145913481Sgiacomo.travaglini@arm.com}; 146013481Sgiacomo.travaglini@arm.com... 146113481Sgiacomo.travaglini@arm.com 146213481Sgiacomo.travaglini@arm.com MockFoo foo; 146313481Sgiacomo.travaglini@arm.com Bar bar; 146413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, GetBar()) 146513481Sgiacomo.travaglini@arm.com .WillOnce(ReturnRef(bar)); 146613481Sgiacomo.travaglini@arm.com``` 146713481Sgiacomo.travaglini@arm.com 146813481Sgiacomo.travaglini@arm.com## Returning Live Values from Mock Methods ## 146913481Sgiacomo.travaglini@arm.com 147013481Sgiacomo.travaglini@arm.comThe `Return(x)` action saves a copy of `x` when the action is 147113481Sgiacomo.travaglini@arm.com_created_, and always returns the same value whenever it's 147213481Sgiacomo.travaglini@arm.comexecuted. Sometimes you may want to instead return the _live_ value of 147313481Sgiacomo.travaglini@arm.com`x` (i.e. its value at the time when the action is _executed_.). 147413481Sgiacomo.travaglini@arm.com 147513481Sgiacomo.travaglini@arm.comIf the mock function's return type is a reference, you can do it using 147613481Sgiacomo.travaglini@arm.com`ReturnRef(x)`, as shown in the previous recipe ("Returning References 147713481Sgiacomo.travaglini@arm.comfrom Mock Methods"). However, Google Mock doesn't let you use 147813481Sgiacomo.travaglini@arm.com`ReturnRef()` in a mock function whose return type is not a reference, 147913481Sgiacomo.travaglini@arm.comas doing that usually indicates a user error. So, what shall you do? 148013481Sgiacomo.travaglini@arm.com 148113481Sgiacomo.travaglini@arm.comYou may be tempted to try `ByRef()`: 148213481Sgiacomo.travaglini@arm.com 148313481Sgiacomo.travaglini@arm.com``` 148413481Sgiacomo.travaglini@arm.comusing testing::ByRef; 148513481Sgiacomo.travaglini@arm.comusing testing::Return; 148613481Sgiacomo.travaglini@arm.com 148713481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 148813481Sgiacomo.travaglini@arm.com public: 148913481Sgiacomo.travaglini@arm.com MOCK_METHOD0(GetValue, int()); 149013481Sgiacomo.travaglini@arm.com}; 149113481Sgiacomo.travaglini@arm.com... 149213481Sgiacomo.travaglini@arm.com int x = 0; 149313481Sgiacomo.travaglini@arm.com MockFoo foo; 149413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, GetValue()) 149513481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return(ByRef(x))); 149613481Sgiacomo.travaglini@arm.com x = 42; 149713481Sgiacomo.travaglini@arm.com EXPECT_EQ(42, foo.GetValue()); 149813481Sgiacomo.travaglini@arm.com``` 149913481Sgiacomo.travaglini@arm.com 150013481Sgiacomo.travaglini@arm.comUnfortunately, it doesn't work here. The above code will fail with error: 150113481Sgiacomo.travaglini@arm.com 150213481Sgiacomo.travaglini@arm.com``` 150313481Sgiacomo.travaglini@arm.comValue of: foo.GetValue() 150413481Sgiacomo.travaglini@arm.com Actual: 0 150513481Sgiacomo.travaglini@arm.comExpected: 42 150613481Sgiacomo.travaglini@arm.com``` 150713481Sgiacomo.travaglini@arm.com 150813481Sgiacomo.travaglini@arm.comThe reason is that `Return(value)` converts `value` to the actual 150913481Sgiacomo.travaglini@arm.comreturn type of the mock function at the time when the action is 151013481Sgiacomo.travaglini@arm.com_created_, not when it is _executed_. (This behavior was chosen for 151113481Sgiacomo.travaglini@arm.comthe action to be safe when `value` is a proxy object that references 151213481Sgiacomo.travaglini@arm.comsome temporary objects.) As a result, `ByRef(x)` is converted to an 151313481Sgiacomo.travaglini@arm.com`int` value (instead of a `const int&`) when the expectation is set, 151413481Sgiacomo.travaglini@arm.comand `Return(ByRef(x))` will always return 0. 151513481Sgiacomo.travaglini@arm.com 151613481Sgiacomo.travaglini@arm.com`ReturnPointee(pointer)` was provided to solve this problem 151713481Sgiacomo.travaglini@arm.comspecifically. It returns the value pointed to by `pointer` at the time 151813481Sgiacomo.travaglini@arm.comthe action is _executed_: 151913481Sgiacomo.travaglini@arm.com 152013481Sgiacomo.travaglini@arm.com``` 152113481Sgiacomo.travaglini@arm.comusing testing::ReturnPointee; 152213481Sgiacomo.travaglini@arm.com... 152313481Sgiacomo.travaglini@arm.com int x = 0; 152413481Sgiacomo.travaglini@arm.com MockFoo foo; 152513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, GetValue()) 152613481Sgiacomo.travaglini@arm.com .WillRepeatedly(ReturnPointee(&x)); // Note the & here. 152713481Sgiacomo.travaglini@arm.com x = 42; 152813481Sgiacomo.travaglini@arm.com EXPECT_EQ(42, foo.GetValue()); // This will succeed now. 152913481Sgiacomo.travaglini@arm.com``` 153013481Sgiacomo.travaglini@arm.com 153113481Sgiacomo.travaglini@arm.com## Combining Actions ## 153213481Sgiacomo.travaglini@arm.com 153313481Sgiacomo.travaglini@arm.comWant to do more than one thing when a function is called? That's 153413481Sgiacomo.travaglini@arm.comfine. `DoAll()` allow you to do sequence of actions every time. Only 153513481Sgiacomo.travaglini@arm.comthe return value of the last action in the sequence will be used. 153613481Sgiacomo.travaglini@arm.com 153713481Sgiacomo.travaglini@arm.com``` 153813481Sgiacomo.travaglini@arm.comusing ::testing::DoAll; 153913481Sgiacomo.travaglini@arm.com 154013481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 154113481Sgiacomo.travaglini@arm.com public: 154213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Bar, bool(int n)); 154313481Sgiacomo.travaglini@arm.com}; 154413481Sgiacomo.travaglini@arm.com... 154513481Sgiacomo.travaglini@arm.com 154613481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(_)) 154713481Sgiacomo.travaglini@arm.com .WillOnce(DoAll(action_1, 154813481Sgiacomo.travaglini@arm.com action_2, 154913481Sgiacomo.travaglini@arm.com ... 155013481Sgiacomo.travaglini@arm.com action_n)); 155113481Sgiacomo.travaglini@arm.com``` 155213481Sgiacomo.travaglini@arm.com 155313481Sgiacomo.travaglini@arm.com## Mocking Side Effects ## 155413481Sgiacomo.travaglini@arm.com 155513481Sgiacomo.travaglini@arm.comSometimes a method exhibits its effect not via returning a value but 155613481Sgiacomo.travaglini@arm.comvia side effects. For example, it may change some global state or 155713481Sgiacomo.travaglini@arm.commodify an output argument. To mock side effects, in general you can 155813481Sgiacomo.travaglini@arm.comdefine your own action by implementing `::testing::ActionInterface`. 155913481Sgiacomo.travaglini@arm.com 156013481Sgiacomo.travaglini@arm.comIf all you need to do is to change an output argument, the built-in 156113481Sgiacomo.travaglini@arm.com`SetArgPointee()` action is convenient: 156213481Sgiacomo.travaglini@arm.com 156313481Sgiacomo.travaglini@arm.com``` 156413481Sgiacomo.travaglini@arm.comusing ::testing::SetArgPointee; 156513481Sgiacomo.travaglini@arm.com 156613481Sgiacomo.travaglini@arm.comclass MockMutator : public Mutator { 156713481Sgiacomo.travaglini@arm.com public: 156813481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Mutate, void(bool mutate, int* value)); 156913481Sgiacomo.travaglini@arm.com ... 157013481Sgiacomo.travaglini@arm.com}; 157113481Sgiacomo.travaglini@arm.com... 157213481Sgiacomo.travaglini@arm.com 157313481Sgiacomo.travaglini@arm.com MockMutator mutator; 157413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mutator, Mutate(true, _)) 157513481Sgiacomo.travaglini@arm.com .WillOnce(SetArgPointee<1>(5)); 157613481Sgiacomo.travaglini@arm.com``` 157713481Sgiacomo.travaglini@arm.com 157813481Sgiacomo.travaglini@arm.comIn this example, when `mutator.Mutate()` is called, we will assign 5 157913481Sgiacomo.travaglini@arm.comto the `int` variable pointed to by argument #1 158013481Sgiacomo.travaglini@arm.com(0-based). 158113481Sgiacomo.travaglini@arm.com 158213481Sgiacomo.travaglini@arm.com`SetArgPointee()` conveniently makes an internal copy of the 158313481Sgiacomo.travaglini@arm.comvalue you pass to it, removing the need to keep the value in scope and 158413481Sgiacomo.travaglini@arm.comalive. The implication however is that the value must have a copy 158513481Sgiacomo.travaglini@arm.comconstructor and assignment operator. 158613481Sgiacomo.travaglini@arm.com 158713481Sgiacomo.travaglini@arm.comIf the mock method also needs to return a value as well, you can chain 158813481Sgiacomo.travaglini@arm.com`SetArgPointee()` with `Return()` using `DoAll()`: 158913481Sgiacomo.travaglini@arm.com 159013481Sgiacomo.travaglini@arm.com``` 159113481Sgiacomo.travaglini@arm.comusing ::testing::_; 159213481Sgiacomo.travaglini@arm.comusing ::testing::Return; 159313481Sgiacomo.travaglini@arm.comusing ::testing::SetArgPointee; 159413481Sgiacomo.travaglini@arm.com 159513481Sgiacomo.travaglini@arm.comclass MockMutator : public Mutator { 159613481Sgiacomo.travaglini@arm.com public: 159713481Sgiacomo.travaglini@arm.com ... 159813481Sgiacomo.travaglini@arm.com MOCK_METHOD1(MutateInt, bool(int* value)); 159913481Sgiacomo.travaglini@arm.com}; 160013481Sgiacomo.travaglini@arm.com... 160113481Sgiacomo.travaglini@arm.com 160213481Sgiacomo.travaglini@arm.com MockMutator mutator; 160313481Sgiacomo.travaglini@arm.com EXPECT_CALL(mutator, MutateInt(_)) 160413481Sgiacomo.travaglini@arm.com .WillOnce(DoAll(SetArgPointee<0>(5), 160513481Sgiacomo.travaglini@arm.com Return(true))); 160613481Sgiacomo.travaglini@arm.com``` 160713481Sgiacomo.travaglini@arm.com 160813481Sgiacomo.travaglini@arm.comIf the output argument is an array, use the 160913481Sgiacomo.travaglini@arm.com`SetArrayArgument<N>(first, last)` action instead. It copies the 161013481Sgiacomo.travaglini@arm.comelements in source range `[first, last)` to the array pointed to by 161113481Sgiacomo.travaglini@arm.comthe `N`-th (0-based) argument: 161213481Sgiacomo.travaglini@arm.com 161313481Sgiacomo.travaglini@arm.com``` 161413481Sgiacomo.travaglini@arm.comusing ::testing::NotNull; 161513481Sgiacomo.travaglini@arm.comusing ::testing::SetArrayArgument; 161613481Sgiacomo.travaglini@arm.com 161713481Sgiacomo.travaglini@arm.comclass MockArrayMutator : public ArrayMutator { 161813481Sgiacomo.travaglini@arm.com public: 161913481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Mutate, void(int* values, int num_values)); 162013481Sgiacomo.travaglini@arm.com ... 162113481Sgiacomo.travaglini@arm.com}; 162213481Sgiacomo.travaglini@arm.com... 162313481Sgiacomo.travaglini@arm.com 162413481Sgiacomo.travaglini@arm.com MockArrayMutator mutator; 162513481Sgiacomo.travaglini@arm.com int values[5] = { 1, 2, 3, 4, 5 }; 162613481Sgiacomo.travaglini@arm.com EXPECT_CALL(mutator, Mutate(NotNull(), 5)) 162713481Sgiacomo.travaglini@arm.com .WillOnce(SetArrayArgument<0>(values, values + 5)); 162813481Sgiacomo.travaglini@arm.com``` 162913481Sgiacomo.travaglini@arm.com 163013481Sgiacomo.travaglini@arm.comThis also works when the argument is an output iterator: 163113481Sgiacomo.travaglini@arm.com 163213481Sgiacomo.travaglini@arm.com``` 163313481Sgiacomo.travaglini@arm.comusing ::testing::_; 163413481Sgiacomo.travaglini@arm.comusing ::testing::SeArrayArgument; 163513481Sgiacomo.travaglini@arm.com 163613481Sgiacomo.travaglini@arm.comclass MockRolodex : public Rolodex { 163713481Sgiacomo.travaglini@arm.com public: 163813481Sgiacomo.travaglini@arm.com MOCK_METHOD1(GetNames, void(std::back_insert_iterator<vector<string> >)); 163913481Sgiacomo.travaglini@arm.com ... 164013481Sgiacomo.travaglini@arm.com}; 164113481Sgiacomo.travaglini@arm.com... 164213481Sgiacomo.travaglini@arm.com 164313481Sgiacomo.travaglini@arm.com MockRolodex rolodex; 164413481Sgiacomo.travaglini@arm.com vector<string> names; 164513481Sgiacomo.travaglini@arm.com names.push_back("George"); 164613481Sgiacomo.travaglini@arm.com names.push_back("John"); 164713481Sgiacomo.travaglini@arm.com names.push_back("Thomas"); 164813481Sgiacomo.travaglini@arm.com EXPECT_CALL(rolodex, GetNames(_)) 164913481Sgiacomo.travaglini@arm.com .WillOnce(SetArrayArgument<0>(names.begin(), names.end())); 165013481Sgiacomo.travaglini@arm.com``` 165113481Sgiacomo.travaglini@arm.com 165213481Sgiacomo.travaglini@arm.com## Changing a Mock Object's Behavior Based on the State ## 165313481Sgiacomo.travaglini@arm.com 165413481Sgiacomo.travaglini@arm.comIf 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: 165513481Sgiacomo.travaglini@arm.com 165613481Sgiacomo.travaglini@arm.com``` 165713481Sgiacomo.travaglini@arm.comusing ::testing::InSequence; 165813481Sgiacomo.travaglini@arm.comusing ::testing::Return; 165913481Sgiacomo.travaglini@arm.com 166013481Sgiacomo.travaglini@arm.com... 166113481Sgiacomo.travaglini@arm.com { 166213481Sgiacomo.travaglini@arm.com InSequence seq; 166313481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, IsDirty()) 166413481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return(true)); 166513481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, Flush()); 166613481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, IsDirty()) 166713481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return(false)); 166813481Sgiacomo.travaglini@arm.com } 166913481Sgiacomo.travaglini@arm.com my_mock.FlushIfDirty(); 167013481Sgiacomo.travaglini@arm.com``` 167113481Sgiacomo.travaglini@arm.com 167213481Sgiacomo.travaglini@arm.comThis makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called and return `false` afterwards. 167313481Sgiacomo.travaglini@arm.com 167413481Sgiacomo.travaglini@arm.comIf 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: 167513481Sgiacomo.travaglini@arm.com 167613481Sgiacomo.travaglini@arm.com``` 167713481Sgiacomo.travaglini@arm.comusing ::testing::_; 167813481Sgiacomo.travaglini@arm.comusing ::testing::SaveArg; 167913481Sgiacomo.travaglini@arm.comusing ::testing::Return; 168013481Sgiacomo.travaglini@arm.com 168113481Sgiacomo.travaglini@arm.comACTION_P(ReturnPointee, p) { return *p; } 168213481Sgiacomo.travaglini@arm.com... 168313481Sgiacomo.travaglini@arm.com int previous_value = 0; 168413481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, GetPrevValue()) 168513481Sgiacomo.travaglini@arm.com .WillRepeatedly(ReturnPointee(&previous_value)); 168613481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, UpdateValue(_)) 168713481Sgiacomo.travaglini@arm.com .WillRepeatedly(SaveArg<0>(&previous_value)); 168813481Sgiacomo.travaglini@arm.com my_mock.DoSomethingToUpdateValue(); 168913481Sgiacomo.travaglini@arm.com``` 169013481Sgiacomo.travaglini@arm.com 169113481Sgiacomo.travaglini@arm.comHere `my_mock.GetPrevValue()` will always return the argument of the last `UpdateValue()` call. 169213481Sgiacomo.travaglini@arm.com 169313481Sgiacomo.travaglini@arm.com## Setting the Default Value for a Return Type ## 169413481Sgiacomo.travaglini@arm.com 169513481Sgiacomo.travaglini@arm.comIf a mock method's return type is a built-in C++ type or pointer, by 169613481Sgiacomo.travaglini@arm.comdefault it will return 0 when invoked. You only need to specify an 169713481Sgiacomo.travaglini@arm.comaction if this default value doesn't work for you. 169813481Sgiacomo.travaglini@arm.com 169913481Sgiacomo.travaglini@arm.comSometimes, you may want to change this default value, or you may want 170013481Sgiacomo.travaglini@arm.comto specify a default value for types Google Mock doesn't know 170113481Sgiacomo.travaglini@arm.comabout. You can do this using the `::testing::DefaultValue` class 170213481Sgiacomo.travaglini@arm.comtemplate: 170313481Sgiacomo.travaglini@arm.com 170413481Sgiacomo.travaglini@arm.com``` 170513481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 170613481Sgiacomo.travaglini@arm.com public: 170713481Sgiacomo.travaglini@arm.com MOCK_METHOD0(CalculateBar, Bar()); 170813481Sgiacomo.travaglini@arm.com}; 170913481Sgiacomo.travaglini@arm.com... 171013481Sgiacomo.travaglini@arm.com 171113481Sgiacomo.travaglini@arm.com Bar default_bar; 171213481Sgiacomo.travaglini@arm.com // Sets the default return value for type Bar. 171313481Sgiacomo.travaglini@arm.com DefaultValue<Bar>::Set(default_bar); 171413481Sgiacomo.travaglini@arm.com 171513481Sgiacomo.travaglini@arm.com MockFoo foo; 171613481Sgiacomo.travaglini@arm.com 171713481Sgiacomo.travaglini@arm.com // We don't need to specify an action here, as the default 171813481Sgiacomo.travaglini@arm.com // return value works for us. 171913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, CalculateBar()); 172013481Sgiacomo.travaglini@arm.com 172113481Sgiacomo.travaglini@arm.com foo.CalculateBar(); // This should return default_bar. 172213481Sgiacomo.travaglini@arm.com 172313481Sgiacomo.travaglini@arm.com // Unsets the default return value. 172413481Sgiacomo.travaglini@arm.com DefaultValue<Bar>::Clear(); 172513481Sgiacomo.travaglini@arm.com``` 172613481Sgiacomo.travaglini@arm.com 172713481Sgiacomo.travaglini@arm.comPlease note that changing the default value for a type can make you 172813481Sgiacomo.travaglini@arm.comtests hard to understand. We recommend you to use this feature 172913481Sgiacomo.travaglini@arm.comjudiciously. For example, you may want to make sure the `Set()` and 173013481Sgiacomo.travaglini@arm.com`Clear()` calls are right next to the code that uses your mock. 173113481Sgiacomo.travaglini@arm.com 173213481Sgiacomo.travaglini@arm.com## Setting the Default Actions for a Mock Method ## 173313481Sgiacomo.travaglini@arm.com 173413481Sgiacomo.travaglini@arm.comYou've learned how to change the default value of a given 173513481Sgiacomo.travaglini@arm.comtype. However, this may be too coarse for your purpose: perhaps you 173613481Sgiacomo.travaglini@arm.comhave two mock methods with the same return type and you want them to 173713481Sgiacomo.travaglini@arm.comhave different behaviors. The `ON_CALL()` macro allows you to 173813481Sgiacomo.travaglini@arm.comcustomize your mock's behavior at the method level: 173913481Sgiacomo.travaglini@arm.com 174013481Sgiacomo.travaglini@arm.com``` 174113481Sgiacomo.travaglini@arm.comusing ::testing::_; 174213481Sgiacomo.travaglini@arm.comusing ::testing::AnyNumber; 174313481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 174413481Sgiacomo.travaglini@arm.comusing ::testing::Return; 174513481Sgiacomo.travaglini@arm.com... 174613481Sgiacomo.travaglini@arm.com ON_CALL(foo, Sign(_)) 174713481Sgiacomo.travaglini@arm.com .WillByDefault(Return(-1)); 174813481Sgiacomo.travaglini@arm.com ON_CALL(foo, Sign(0)) 174913481Sgiacomo.travaglini@arm.com .WillByDefault(Return(0)); 175013481Sgiacomo.travaglini@arm.com ON_CALL(foo, Sign(Gt(0))) 175113481Sgiacomo.travaglini@arm.com .WillByDefault(Return(1)); 175213481Sgiacomo.travaglini@arm.com 175313481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Sign(_)) 175413481Sgiacomo.travaglini@arm.com .Times(AnyNumber()); 175513481Sgiacomo.travaglini@arm.com 175613481Sgiacomo.travaglini@arm.com foo.Sign(5); // This should return 1. 175713481Sgiacomo.travaglini@arm.com foo.Sign(-9); // This should return -1. 175813481Sgiacomo.travaglini@arm.com foo.Sign(0); // This should return 0. 175913481Sgiacomo.travaglini@arm.com``` 176013481Sgiacomo.travaglini@arm.com 176113481Sgiacomo.travaglini@arm.comAs you may have guessed, when there are more than one `ON_CALL()` 176213481Sgiacomo.travaglini@arm.comstatements, the news order take precedence over the older ones. In 176313481Sgiacomo.travaglini@arm.comother words, the **last** one that matches the function arguments will 176413481Sgiacomo.travaglini@arm.combe used. This matching order allows you to set up the common behavior 176513481Sgiacomo.travaglini@arm.comin a mock object's constructor or the test fixture's set-up phase and 176613481Sgiacomo.travaglini@arm.comspecialize the mock's behavior later. 176713481Sgiacomo.travaglini@arm.com 176813481Sgiacomo.travaglini@arm.com## Using Functions/Methods/Functors as Actions ## 176913481Sgiacomo.travaglini@arm.com 177013481Sgiacomo.travaglini@arm.comIf the built-in actions don't suit you, you can easily use an existing 177113481Sgiacomo.travaglini@arm.comfunction, method, or functor as an action: 177213481Sgiacomo.travaglini@arm.com 177313481Sgiacomo.travaglini@arm.com``` 177413481Sgiacomo.travaglini@arm.comusing ::testing::_; 177513481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 177613481Sgiacomo.travaglini@arm.com 177713481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 177813481Sgiacomo.travaglini@arm.com public: 177913481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Sum, int(int x, int y)); 178013481Sgiacomo.travaglini@arm.com MOCK_METHOD1(ComplexJob, bool(int x)); 178113481Sgiacomo.travaglini@arm.com}; 178213481Sgiacomo.travaglini@arm.com 178313481Sgiacomo.travaglini@arm.comint CalculateSum(int x, int y) { return x + y; } 178413481Sgiacomo.travaglini@arm.com 178513481Sgiacomo.travaglini@arm.comclass Helper { 178613481Sgiacomo.travaglini@arm.com public: 178713481Sgiacomo.travaglini@arm.com bool ComplexJob(int x); 178813481Sgiacomo.travaglini@arm.com}; 178913481Sgiacomo.travaglini@arm.com... 179013481Sgiacomo.travaglini@arm.com 179113481Sgiacomo.travaglini@arm.com MockFoo foo; 179213481Sgiacomo.travaglini@arm.com Helper helper; 179313481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Sum(_, _)) 179413481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(CalculateSum)); 179513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, ComplexJob(_)) 179613481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(&helper, &Helper::ComplexJob)); 179713481Sgiacomo.travaglini@arm.com 179813481Sgiacomo.travaglini@arm.com foo.Sum(5, 6); // Invokes CalculateSum(5, 6). 179913481Sgiacomo.travaglini@arm.com foo.ComplexJob(10); // Invokes helper.ComplexJob(10); 180013481Sgiacomo.travaglini@arm.com``` 180113481Sgiacomo.travaglini@arm.com 180213481Sgiacomo.travaglini@arm.comThe only requirement is that the type of the function, etc must be 180313481Sgiacomo.travaglini@arm.com_compatible_ with the signature of the mock function, meaning that the 180413481Sgiacomo.travaglini@arm.comlatter's arguments can be implicitly converted to the corresponding 180513481Sgiacomo.travaglini@arm.comarguments of the former, and the former's return type can be 180613481Sgiacomo.travaglini@arm.comimplicitly converted to that of the latter. So, you can invoke 180713481Sgiacomo.travaglini@arm.comsomething whose type is _not_ exactly the same as the mock function, 180813481Sgiacomo.travaglini@arm.comas long as it's safe to do so - nice, huh? 180913481Sgiacomo.travaglini@arm.com 181013481Sgiacomo.travaglini@arm.com## Invoking a Function/Method/Functor Without Arguments ## 181113481Sgiacomo.travaglini@arm.com 181213481Sgiacomo.travaglini@arm.com`Invoke()` is very useful for doing actions that are more complex. It 181313481Sgiacomo.travaglini@arm.compasses the mock function's arguments to the function or functor being 181413481Sgiacomo.travaglini@arm.cominvoked such that the callee has the full context of the call to work 181513481Sgiacomo.travaglini@arm.comwith. If the invoked function is not interested in some or all of the 181613481Sgiacomo.travaglini@arm.comarguments, it can simply ignore them. 181713481Sgiacomo.travaglini@arm.com 181813481Sgiacomo.travaglini@arm.comYet, a common pattern is that a test author wants to invoke a function 181913481Sgiacomo.travaglini@arm.comwithout the arguments of the mock function. `Invoke()` allows her to 182013481Sgiacomo.travaglini@arm.comdo that using a wrapper function that throws away the arguments before 182113481Sgiacomo.travaglini@arm.cominvoking an underlining nullary function. Needless to say, this can be 182213481Sgiacomo.travaglini@arm.comtedious and obscures the intent of the test. 182313481Sgiacomo.travaglini@arm.com 182413481Sgiacomo.travaglini@arm.com`InvokeWithoutArgs()` solves this problem. It's like `Invoke()` except 182513481Sgiacomo.travaglini@arm.comthat it doesn't pass the mock function's arguments to the 182613481Sgiacomo.travaglini@arm.comcallee. Here's an example: 182713481Sgiacomo.travaglini@arm.com 182813481Sgiacomo.travaglini@arm.com``` 182913481Sgiacomo.travaglini@arm.comusing ::testing::_; 183013481Sgiacomo.travaglini@arm.comusing ::testing::InvokeWithoutArgs; 183113481Sgiacomo.travaglini@arm.com 183213481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 183313481Sgiacomo.travaglini@arm.com public: 183413481Sgiacomo.travaglini@arm.com MOCK_METHOD1(ComplexJob, bool(int n)); 183513481Sgiacomo.travaglini@arm.com}; 183613481Sgiacomo.travaglini@arm.com 183713481Sgiacomo.travaglini@arm.combool Job1() { ... } 183813481Sgiacomo.travaglini@arm.com... 183913481Sgiacomo.travaglini@arm.com 184013481Sgiacomo.travaglini@arm.com MockFoo foo; 184113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, ComplexJob(_)) 184213481Sgiacomo.travaglini@arm.com .WillOnce(InvokeWithoutArgs(Job1)); 184313481Sgiacomo.travaglini@arm.com 184413481Sgiacomo.travaglini@arm.com foo.ComplexJob(10); // Invokes Job1(). 184513481Sgiacomo.travaglini@arm.com``` 184613481Sgiacomo.travaglini@arm.com 184713481Sgiacomo.travaglini@arm.com## Invoking an Argument of the Mock Function ## 184813481Sgiacomo.travaglini@arm.com 184913481Sgiacomo.travaglini@arm.comSometimes a mock function will receive a function pointer or a functor 185013481Sgiacomo.travaglini@arm.com(in other words, a "callable") as an argument, e.g. 185113481Sgiacomo.travaglini@arm.com 185213481Sgiacomo.travaglini@arm.com``` 185313481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 185413481Sgiacomo.travaglini@arm.com public: 185513481Sgiacomo.travaglini@arm.com MOCK_METHOD2(DoThis, bool(int n, bool (*fp)(int))); 185613481Sgiacomo.travaglini@arm.com}; 185713481Sgiacomo.travaglini@arm.com``` 185813481Sgiacomo.travaglini@arm.com 185913481Sgiacomo.travaglini@arm.comand you may want to invoke this callable argument: 186013481Sgiacomo.travaglini@arm.com 186113481Sgiacomo.travaglini@arm.com``` 186213481Sgiacomo.travaglini@arm.comusing ::testing::_; 186313481Sgiacomo.travaglini@arm.com... 186413481Sgiacomo.travaglini@arm.com MockFoo foo; 186513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(_, _)) 186613481Sgiacomo.travaglini@arm.com .WillOnce(...); 186713481Sgiacomo.travaglini@arm.com // Will execute (*fp)(5), where fp is the 186813481Sgiacomo.travaglini@arm.com // second argument DoThis() receives. 186913481Sgiacomo.travaglini@arm.com``` 187013481Sgiacomo.travaglini@arm.com 187113481Sgiacomo.travaglini@arm.comArghh, you need to refer to a mock function argument but C++ has no 187213481Sgiacomo.travaglini@arm.comlambda (yet), so you have to define your own action. :-( Or do you 187313481Sgiacomo.travaglini@arm.comreally? 187413481Sgiacomo.travaglini@arm.com 187513481Sgiacomo.travaglini@arm.comWell, Google Mock has an action to solve _exactly_ this problem: 187613481Sgiacomo.travaglini@arm.com 187713481Sgiacomo.travaglini@arm.com``` 187813481Sgiacomo.travaglini@arm.com InvokeArgument<N>(arg_1, arg_2, ..., arg_m) 187913481Sgiacomo.travaglini@arm.com``` 188013481Sgiacomo.travaglini@arm.com 188113481Sgiacomo.travaglini@arm.comwill invoke the `N`-th (0-based) argument the mock function receives, 188213481Sgiacomo.travaglini@arm.comwith `arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is 188313481Sgiacomo.travaglini@arm.coma function pointer or a functor, Google Mock handles them both. 188413481Sgiacomo.travaglini@arm.com 188513481Sgiacomo.travaglini@arm.comWith that, you could write: 188613481Sgiacomo.travaglini@arm.com 188713481Sgiacomo.travaglini@arm.com``` 188813481Sgiacomo.travaglini@arm.comusing ::testing::_; 188913481Sgiacomo.travaglini@arm.comusing ::testing::InvokeArgument; 189013481Sgiacomo.travaglini@arm.com... 189113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(_, _)) 189213481Sgiacomo.travaglini@arm.com .WillOnce(InvokeArgument<1>(5)); 189313481Sgiacomo.travaglini@arm.com // Will execute (*fp)(5), where fp is the 189413481Sgiacomo.travaglini@arm.com // second argument DoThis() receives. 189513481Sgiacomo.travaglini@arm.com``` 189613481Sgiacomo.travaglini@arm.com 189713481Sgiacomo.travaglini@arm.comWhat if the callable takes an argument by reference? No problem - just 189813481Sgiacomo.travaglini@arm.comwrap it inside `ByRef()`: 189913481Sgiacomo.travaglini@arm.com 190013481Sgiacomo.travaglini@arm.com``` 190113481Sgiacomo.travaglini@arm.com... 190213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Bar, bool(bool (*fp)(int, const Helper&))); 190313481Sgiacomo.travaglini@arm.com... 190413481Sgiacomo.travaglini@arm.comusing ::testing::_; 190513481Sgiacomo.travaglini@arm.comusing ::testing::ByRef; 190613481Sgiacomo.travaglini@arm.comusing ::testing::InvokeArgument; 190713481Sgiacomo.travaglini@arm.com... 190813481Sgiacomo.travaglini@arm.com 190913481Sgiacomo.travaglini@arm.com MockFoo foo; 191013481Sgiacomo.travaglini@arm.com Helper helper; 191113481Sgiacomo.travaglini@arm.com ... 191213481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(_)) 191313481Sgiacomo.travaglini@arm.com .WillOnce(InvokeArgument<0>(5, ByRef(helper))); 191413481Sgiacomo.travaglini@arm.com // ByRef(helper) guarantees that a reference to helper, not a copy of it, 191513481Sgiacomo.travaglini@arm.com // will be passed to the callable. 191613481Sgiacomo.travaglini@arm.com``` 191713481Sgiacomo.travaglini@arm.com 191813481Sgiacomo.travaglini@arm.comWhat if the callable takes an argument by reference and we do **not** 191913481Sgiacomo.travaglini@arm.comwrap the argument in `ByRef()`? Then `InvokeArgument()` will _make a 192013481Sgiacomo.travaglini@arm.comcopy_ of the argument, and pass a _reference to the copy_, instead of 192113481Sgiacomo.travaglini@arm.coma reference to the original value, to the callable. This is especially 192213481Sgiacomo.travaglini@arm.comhandy when the argument is a temporary value: 192313481Sgiacomo.travaglini@arm.com 192413481Sgiacomo.travaglini@arm.com``` 192513481Sgiacomo.travaglini@arm.com... 192613481Sgiacomo.travaglini@arm.com MOCK_METHOD1(DoThat, bool(bool (*f)(const double& x, const string& s))); 192713481Sgiacomo.travaglini@arm.com... 192813481Sgiacomo.travaglini@arm.comusing ::testing::_; 192913481Sgiacomo.travaglini@arm.comusing ::testing::InvokeArgument; 193013481Sgiacomo.travaglini@arm.com... 193113481Sgiacomo.travaglini@arm.com 193213481Sgiacomo.travaglini@arm.com MockFoo foo; 193313481Sgiacomo.travaglini@arm.com ... 193413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat(_)) 193513481Sgiacomo.travaglini@arm.com .WillOnce(InvokeArgument<0>(5.0, string("Hi"))); 193613481Sgiacomo.travaglini@arm.com // Will execute (*f)(5.0, string("Hi")), where f is the function pointer 193713481Sgiacomo.travaglini@arm.com // DoThat() receives. Note that the values 5.0 and string("Hi") are 193813481Sgiacomo.travaglini@arm.com // temporary and dead once the EXPECT_CALL() statement finishes. Yet 193913481Sgiacomo.travaglini@arm.com // it's fine to perform this action later, since a copy of the values 194013481Sgiacomo.travaglini@arm.com // are kept inside the InvokeArgument action. 194113481Sgiacomo.travaglini@arm.com``` 194213481Sgiacomo.travaglini@arm.com 194313481Sgiacomo.travaglini@arm.com## Ignoring an Action's Result ## 194413481Sgiacomo.travaglini@arm.com 194513481Sgiacomo.travaglini@arm.comSometimes you have an action that returns _something_, but you need an 194613481Sgiacomo.travaglini@arm.comaction that returns `void` (perhaps you want to use it in a mock 194713481Sgiacomo.travaglini@arm.comfunction that returns `void`, or perhaps it needs to be used in 194813481Sgiacomo.travaglini@arm.com`DoAll()` and it's not the last in the list). `IgnoreResult()` lets 194913481Sgiacomo.travaglini@arm.comyou do that. For example: 195013481Sgiacomo.travaglini@arm.com 195113481Sgiacomo.travaglini@arm.com``` 195213481Sgiacomo.travaglini@arm.comusing ::testing::_; 195313481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 195413481Sgiacomo.travaglini@arm.comusing ::testing::Return; 195513481Sgiacomo.travaglini@arm.com 195613481Sgiacomo.travaglini@arm.comint Process(const MyData& data); 195713481Sgiacomo.travaglini@arm.comstring DoSomething(); 195813481Sgiacomo.travaglini@arm.com 195913481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 196013481Sgiacomo.travaglini@arm.com public: 196113481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Abc, void(const MyData& data)); 196213481Sgiacomo.travaglini@arm.com MOCK_METHOD0(Xyz, bool()); 196313481Sgiacomo.travaglini@arm.com}; 196413481Sgiacomo.travaglini@arm.com... 196513481Sgiacomo.travaglini@arm.com 196613481Sgiacomo.travaglini@arm.com MockFoo foo; 196713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Abc(_)) 196813481Sgiacomo.travaglini@arm.com // .WillOnce(Invoke(Process)); 196913481Sgiacomo.travaglini@arm.com // The above line won't compile as Process() returns int but Abc() needs 197013481Sgiacomo.travaglini@arm.com // to return void. 197113481Sgiacomo.travaglini@arm.com .WillOnce(IgnoreResult(Invoke(Process))); 197213481Sgiacomo.travaglini@arm.com 197313481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Xyz()) 197413481Sgiacomo.travaglini@arm.com .WillOnce(DoAll(IgnoreResult(Invoke(DoSomething)), 197513481Sgiacomo.travaglini@arm.com // Ignores the string DoSomething() returns. 197613481Sgiacomo.travaglini@arm.com Return(true))); 197713481Sgiacomo.travaglini@arm.com``` 197813481Sgiacomo.travaglini@arm.com 197913481Sgiacomo.travaglini@arm.comNote that you **cannot** use `IgnoreResult()` on an action that already 198013481Sgiacomo.travaglini@arm.comreturns `void`. Doing so will lead to ugly compiler errors. 198113481Sgiacomo.travaglini@arm.com 198213481Sgiacomo.travaglini@arm.com## Selecting an Action's Arguments ## 198313481Sgiacomo.travaglini@arm.com 198413481Sgiacomo.travaglini@arm.comSay you have a mock function `Foo()` that takes seven arguments, and 198513481Sgiacomo.travaglini@arm.comyou have a custom action that you want to invoke when `Foo()` is 198613481Sgiacomo.travaglini@arm.comcalled. Trouble is, the custom action only wants three arguments: 198713481Sgiacomo.travaglini@arm.com 198813481Sgiacomo.travaglini@arm.com``` 198913481Sgiacomo.travaglini@arm.comusing ::testing::_; 199013481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 199113481Sgiacomo.travaglini@arm.com... 199213481Sgiacomo.travaglini@arm.com MOCK_METHOD7(Foo, bool(bool visible, const string& name, int x, int y, 199313481Sgiacomo.travaglini@arm.com const map<pair<int, int>, double>& weight, 199413481Sgiacomo.travaglini@arm.com double min_weight, double max_wight)); 199513481Sgiacomo.travaglini@arm.com... 199613481Sgiacomo.travaglini@arm.com 199713481Sgiacomo.travaglini@arm.combool IsVisibleInQuadrant1(bool visible, int x, int y) { 199813481Sgiacomo.travaglini@arm.com return visible && x >= 0 && y >= 0; 199913481Sgiacomo.travaglini@arm.com} 200013481Sgiacomo.travaglini@arm.com... 200113481Sgiacomo.travaglini@arm.com 200213481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _)) 200313481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-( 200413481Sgiacomo.travaglini@arm.com``` 200513481Sgiacomo.travaglini@arm.com 200613481Sgiacomo.travaglini@arm.comTo please the compiler God, you can to define an "adaptor" that has 200713481Sgiacomo.travaglini@arm.comthe same signature as `Foo()` and calls the custom action with the 200813481Sgiacomo.travaglini@arm.comright arguments: 200913481Sgiacomo.travaglini@arm.com 201013481Sgiacomo.travaglini@arm.com``` 201113481Sgiacomo.travaglini@arm.comusing ::testing::_; 201213481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 201313481Sgiacomo.travaglini@arm.com 201413481Sgiacomo.travaglini@arm.combool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y, 201513481Sgiacomo.travaglini@arm.com const map<pair<int, int>, double>& weight, 201613481Sgiacomo.travaglini@arm.com double min_weight, double max_wight) { 201713481Sgiacomo.travaglini@arm.com return IsVisibleInQuadrant1(visible, x, y); 201813481Sgiacomo.travaglini@arm.com} 201913481Sgiacomo.travaglini@arm.com... 202013481Sgiacomo.travaglini@arm.com 202113481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _)) 202213481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works. 202313481Sgiacomo.travaglini@arm.com``` 202413481Sgiacomo.travaglini@arm.com 202513481Sgiacomo.travaglini@arm.comBut isn't this awkward? 202613481Sgiacomo.travaglini@arm.com 202713481Sgiacomo.travaglini@arm.comGoogle Mock provides a generic _action adaptor_, so you can spend your 202813481Sgiacomo.travaglini@arm.comtime minding more important business than writing your own 202913481Sgiacomo.travaglini@arm.comadaptors. Here's the syntax: 203013481Sgiacomo.travaglini@arm.com 203113481Sgiacomo.travaglini@arm.com``` 203213481Sgiacomo.travaglini@arm.com WithArgs<N1, N2, ..., Nk>(action) 203313481Sgiacomo.travaglini@arm.com``` 203413481Sgiacomo.travaglini@arm.com 203513481Sgiacomo.travaglini@arm.comcreates an action that passes the arguments of the mock function at 203613481Sgiacomo.travaglini@arm.comthe given indices (0-based) to the inner `action` and performs 203713481Sgiacomo.travaglini@arm.comit. Using `WithArgs`, our original example can be written as: 203813481Sgiacomo.travaglini@arm.com 203913481Sgiacomo.travaglini@arm.com``` 204013481Sgiacomo.travaglini@arm.comusing ::testing::_; 204113481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 204213481Sgiacomo.travaglini@arm.comusing ::testing::WithArgs; 204313481Sgiacomo.travaglini@arm.com... 204413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _)) 204513481Sgiacomo.travaglini@arm.com .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); 204613481Sgiacomo.travaglini@arm.com // No need to define your own adaptor. 204713481Sgiacomo.travaglini@arm.com``` 204813481Sgiacomo.travaglini@arm.com 204913481Sgiacomo.travaglini@arm.comFor better readability, Google Mock also gives you: 205013481Sgiacomo.travaglini@arm.com 205113481Sgiacomo.travaglini@arm.com * `WithoutArgs(action)` when the inner `action` takes _no_ argument, and 205213481Sgiacomo.travaglini@arm.com * `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes _one_ argument. 205313481Sgiacomo.travaglini@arm.com 205413481Sgiacomo.travaglini@arm.comAs you may have realized, `InvokeWithoutArgs(...)` is just syntactic 205513481Sgiacomo.travaglini@arm.comsugar for `WithoutArgs(Inovke(...))`. 205613481Sgiacomo.travaglini@arm.com 205713481Sgiacomo.travaglini@arm.comHere are more tips: 205813481Sgiacomo.travaglini@arm.com 205913481Sgiacomo.travaglini@arm.com * The inner action used in `WithArgs` and friends does not have to be `Invoke()` -- it can be anything. 206013481Sgiacomo.travaglini@arm.com * You can repeat an argument in the argument list if necessary, e.g. `WithArgs<2, 3, 3, 5>(...)`. 206113481Sgiacomo.travaglini@arm.com * You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`. 206213481Sgiacomo.travaglini@arm.com * 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. 206313481Sgiacomo.travaglini@arm.com 206413481Sgiacomo.travaglini@arm.com## Ignoring Arguments in Action Functions ## 206513481Sgiacomo.travaglini@arm.com 206613481Sgiacomo.travaglini@arm.comThe selecting-an-action's-arguments recipe showed us one way to make a 206713481Sgiacomo.travaglini@arm.commock function and an action with incompatible argument lists fit 206813481Sgiacomo.travaglini@arm.comtogether. The downside is that wrapping the action in 206913481Sgiacomo.travaglini@arm.com`WithArgs<...>()` can get tedious for people writing the tests. 207013481Sgiacomo.travaglini@arm.com 207113481Sgiacomo.travaglini@arm.comIf you are defining a function, method, or functor to be used with 207213481Sgiacomo.travaglini@arm.com`Invoke*()`, and you are not interested in some of its arguments, an 207313481Sgiacomo.travaglini@arm.comalternative to `WithArgs` is to declare the uninteresting arguments as 207413481Sgiacomo.travaglini@arm.com`Unused`. This makes the definition less cluttered and less fragile in 207513481Sgiacomo.travaglini@arm.comcase the types of the uninteresting arguments change. It could also 207613481Sgiacomo.travaglini@arm.comincrease the chance the action function can be reused. For example, 207713481Sgiacomo.travaglini@arm.comgiven 207813481Sgiacomo.travaglini@arm.com 207913481Sgiacomo.travaglini@arm.com``` 208013481Sgiacomo.travaglini@arm.com MOCK_METHOD3(Foo, double(const string& label, double x, double y)); 208113481Sgiacomo.travaglini@arm.com MOCK_METHOD3(Bar, double(int index, double x, double y)); 208213481Sgiacomo.travaglini@arm.com``` 208313481Sgiacomo.travaglini@arm.com 208413481Sgiacomo.travaglini@arm.cominstead of 208513481Sgiacomo.travaglini@arm.com 208613481Sgiacomo.travaglini@arm.com``` 208713481Sgiacomo.travaglini@arm.comusing ::testing::_; 208813481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 208913481Sgiacomo.travaglini@arm.com 209013481Sgiacomo.travaglini@arm.comdouble DistanceToOriginWithLabel(const string& label, double x, double y) { 209113481Sgiacomo.travaglini@arm.com return sqrt(x*x + y*y); 209213481Sgiacomo.travaglini@arm.com} 209313481Sgiacomo.travaglini@arm.com 209413481Sgiacomo.travaglini@arm.comdouble DistanceToOriginWithIndex(int index, double x, double y) { 209513481Sgiacomo.travaglini@arm.com return sqrt(x*x + y*y); 209613481Sgiacomo.travaglini@arm.com} 209713481Sgiacomo.travaglini@arm.com... 209813481Sgiacomo.travaglini@arm.com 209913481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Foo("abc", _, _)) 210013481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOriginWithLabel)); 210113481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Bar(5, _, _)) 210213481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOriginWithIndex)); 210313481Sgiacomo.travaglini@arm.com``` 210413481Sgiacomo.travaglini@arm.com 210513481Sgiacomo.travaglini@arm.comyou could write 210613481Sgiacomo.travaglini@arm.com 210713481Sgiacomo.travaglini@arm.com``` 210813481Sgiacomo.travaglini@arm.comusing ::testing::_; 210913481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 211013481Sgiacomo.travaglini@arm.comusing ::testing::Unused; 211113481Sgiacomo.travaglini@arm.com 211213481Sgiacomo.travaglini@arm.comdouble DistanceToOrigin(Unused, double x, double y) { 211313481Sgiacomo.travaglini@arm.com return sqrt(x*x + y*y); 211413481Sgiacomo.travaglini@arm.com} 211513481Sgiacomo.travaglini@arm.com... 211613481Sgiacomo.travaglini@arm.com 211713481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Foo("abc", _, _)) 211813481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOrigin)); 211913481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Bar(5, _, _)) 212013481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOrigin)); 212113481Sgiacomo.travaglini@arm.com``` 212213481Sgiacomo.travaglini@arm.com 212313481Sgiacomo.travaglini@arm.com## Sharing Actions ## 212413481Sgiacomo.travaglini@arm.com 212513481Sgiacomo.travaglini@arm.comJust like matchers, a Google Mock action object consists of a pointer 212613481Sgiacomo.travaglini@arm.comto a ref-counted implementation object. Therefore copying actions is 212713481Sgiacomo.travaglini@arm.comalso allowed and very efficient. When the last action that references 212813481Sgiacomo.travaglini@arm.comthe implementation object dies, the implementation object will be 212913481Sgiacomo.travaglini@arm.comdeleted. 213013481Sgiacomo.travaglini@arm.com 213113481Sgiacomo.travaglini@arm.comIf you have some complex action that you want to use again and again, 213213481Sgiacomo.travaglini@arm.comyou may not have to build it from scratch everytime. If the action 213313481Sgiacomo.travaglini@arm.comdoesn't have an internal state (i.e. if it always does the same thing 213413481Sgiacomo.travaglini@arm.comno matter how many times it has been called), you can assign it to an 213513481Sgiacomo.travaglini@arm.comaction variable and use that variable repeatedly. For example: 213613481Sgiacomo.travaglini@arm.com 213713481Sgiacomo.travaglini@arm.com``` 213813481Sgiacomo.travaglini@arm.com Action<bool(int*)> set_flag = DoAll(SetArgPointee<0>(5), 213913481Sgiacomo.travaglini@arm.com Return(true)); 214013481Sgiacomo.travaglini@arm.com ... use set_flag in .WillOnce() and .WillRepeatedly() ... 214113481Sgiacomo.travaglini@arm.com``` 214213481Sgiacomo.travaglini@arm.com 214313481Sgiacomo.travaglini@arm.comHowever, if the action has its own state, you may be surprised if you 214413481Sgiacomo.travaglini@arm.comshare the action object. Suppose you have an action factory 214513481Sgiacomo.travaglini@arm.com`IncrementCounter(init)` which creates an action that increments and 214613481Sgiacomo.travaglini@arm.comreturns a counter whose initial value is `init`, using two actions 214713481Sgiacomo.travaglini@arm.comcreated from the same expression and using a shared action will 214813481Sgiacomo.travaglini@arm.comexihibit different behaviors. Example: 214913481Sgiacomo.travaglini@arm.com 215013481Sgiacomo.travaglini@arm.com``` 215113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis()) 215213481Sgiacomo.travaglini@arm.com .WillRepeatedly(IncrementCounter(0)); 215313481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat()) 215413481Sgiacomo.travaglini@arm.com .WillRepeatedly(IncrementCounter(0)); 215513481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 1. 215613481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 2. 215713481Sgiacomo.travaglini@arm.com foo.DoThat(); // Returns 1 - Blah() uses a different 215813481Sgiacomo.travaglini@arm.com // counter than Bar()'s. 215913481Sgiacomo.travaglini@arm.com``` 216013481Sgiacomo.travaglini@arm.com 216113481Sgiacomo.travaglini@arm.comversus 216213481Sgiacomo.travaglini@arm.com 216313481Sgiacomo.travaglini@arm.com``` 216413481Sgiacomo.travaglini@arm.com Action<int()> increment = IncrementCounter(0); 216513481Sgiacomo.travaglini@arm.com 216613481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis()) 216713481Sgiacomo.travaglini@arm.com .WillRepeatedly(increment); 216813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat()) 216913481Sgiacomo.travaglini@arm.com .WillRepeatedly(increment); 217013481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 1. 217113481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 2. 217213481Sgiacomo.travaglini@arm.com foo.DoThat(); // Returns 3 - the counter is shared. 217313481Sgiacomo.travaglini@arm.com``` 217413481Sgiacomo.travaglini@arm.com 217513481Sgiacomo.travaglini@arm.com# Misc Recipes on Using Google Mock # 217613481Sgiacomo.travaglini@arm.com 217713481Sgiacomo.travaglini@arm.com## Making the Compilation Faster ## 217813481Sgiacomo.travaglini@arm.com 217913481Sgiacomo.travaglini@arm.comBelieve it or not, the _vast majority_ of the time spent on compiling 218013481Sgiacomo.travaglini@arm.coma mock class is in generating its constructor and destructor, as they 218113481Sgiacomo.travaglini@arm.comperform non-trivial tasks (e.g. verification of the 218213481Sgiacomo.travaglini@arm.comexpectations). What's more, mock methods with different signatures 218313481Sgiacomo.travaglini@arm.comhave different types and thus their constructors/destructors need to 218413481Sgiacomo.travaglini@arm.combe generated by the compiler separately. As a result, if you mock many 218513481Sgiacomo.travaglini@arm.comdifferent types of methods, compiling your mock class can get really 218613481Sgiacomo.travaglini@arm.comslow. 218713481Sgiacomo.travaglini@arm.com 218813481Sgiacomo.travaglini@arm.comIf you are experiencing slow compilation, you can move the definition 218913481Sgiacomo.travaglini@arm.comof your mock class' constructor and destructor out of the class body 219013481Sgiacomo.travaglini@arm.comand into a `.cpp` file. This way, even if you `#include` your mock 219113481Sgiacomo.travaglini@arm.comclass in N files, the compiler only needs to generate its constructor 219213481Sgiacomo.travaglini@arm.comand destructor once, resulting in a much faster compilation. 219313481Sgiacomo.travaglini@arm.com 219413481Sgiacomo.travaglini@arm.comLet's illustrate the idea using an example. Here's the definition of a 219513481Sgiacomo.travaglini@arm.commock class before applying this recipe: 219613481Sgiacomo.travaglini@arm.com 219713481Sgiacomo.travaglini@arm.com``` 219813481Sgiacomo.travaglini@arm.com// File mock_foo.h. 219913481Sgiacomo.travaglini@arm.com... 220013481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 220113481Sgiacomo.travaglini@arm.com public: 220213481Sgiacomo.travaglini@arm.com // Since we don't declare the constructor or the destructor, 220313481Sgiacomo.travaglini@arm.com // the compiler will generate them in every translation unit 220413481Sgiacomo.travaglini@arm.com // where this mock class is used. 220513481Sgiacomo.travaglini@arm.com 220613481Sgiacomo.travaglini@arm.com MOCK_METHOD0(DoThis, int()); 220713481Sgiacomo.travaglini@arm.com MOCK_METHOD1(DoThat, bool(const char* str)); 220813481Sgiacomo.travaglini@arm.com ... more mock methods ... 220913481Sgiacomo.travaglini@arm.com}; 221013481Sgiacomo.travaglini@arm.com``` 221113481Sgiacomo.travaglini@arm.com 221213481Sgiacomo.travaglini@arm.comAfter the change, it would look like: 221313481Sgiacomo.travaglini@arm.com 221413481Sgiacomo.travaglini@arm.com``` 221513481Sgiacomo.travaglini@arm.com// File mock_foo.h. 221613481Sgiacomo.travaglini@arm.com... 221713481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 221813481Sgiacomo.travaglini@arm.com public: 221913481Sgiacomo.travaglini@arm.com // The constructor and destructor are declared, but not defined, here. 222013481Sgiacomo.travaglini@arm.com MockFoo(); 222113481Sgiacomo.travaglini@arm.com virtual ~MockFoo(); 222213481Sgiacomo.travaglini@arm.com 222313481Sgiacomo.travaglini@arm.com MOCK_METHOD0(DoThis, int()); 222413481Sgiacomo.travaglini@arm.com MOCK_METHOD1(DoThat, bool(const char* str)); 222513481Sgiacomo.travaglini@arm.com ... more mock methods ... 222613481Sgiacomo.travaglini@arm.com}; 222713481Sgiacomo.travaglini@arm.com``` 222813481Sgiacomo.travaglini@arm.comand 222913481Sgiacomo.travaglini@arm.com``` 223013481Sgiacomo.travaglini@arm.com// File mock_foo.cpp. 223113481Sgiacomo.travaglini@arm.com#include "path/to/mock_foo.h" 223213481Sgiacomo.travaglini@arm.com 223313481Sgiacomo.travaglini@arm.com// The definitions may appear trivial, but the functions actually do a 223413481Sgiacomo.travaglini@arm.com// lot of things through the constructors/destructors of the member 223513481Sgiacomo.travaglini@arm.com// variables used to implement the mock methods. 223613481Sgiacomo.travaglini@arm.comMockFoo::MockFoo() {} 223713481Sgiacomo.travaglini@arm.comMockFoo::~MockFoo() {} 223813481Sgiacomo.travaglini@arm.com``` 223913481Sgiacomo.travaglini@arm.com 224013481Sgiacomo.travaglini@arm.com## Forcing a Verification ## 224113481Sgiacomo.travaglini@arm.com 224213481Sgiacomo.travaglini@arm.comWhen it's being destoyed, your friendly mock object will automatically 224313481Sgiacomo.travaglini@arm.comverify that all expectations on it have been satisfied, and will 224413481Sgiacomo.travaglini@arm.comgenerate [Google Test](http://code.google.com/p/googletest/) failures 224513481Sgiacomo.travaglini@arm.comif not. This is convenient as it leaves you with one less thing to 224613481Sgiacomo.travaglini@arm.comworry about. That is, unless you are not sure if your mock object will 224713481Sgiacomo.travaglini@arm.combe destoyed. 224813481Sgiacomo.travaglini@arm.com 224913481Sgiacomo.travaglini@arm.comHow could it be that your mock object won't eventually be destroyed? 225013481Sgiacomo.travaglini@arm.comWell, it might be created on the heap and owned by the code you are 225113481Sgiacomo.travaglini@arm.comtesting. Suppose there's a bug in that code and it doesn't delete the 225213481Sgiacomo.travaglini@arm.commock object properly - you could end up with a passing test when 225313481Sgiacomo.travaglini@arm.comthere's actually a bug. 225413481Sgiacomo.travaglini@arm.com 225513481Sgiacomo.travaglini@arm.comUsing a heap checker is a good idea and can alleviate the concern, but 225613481Sgiacomo.travaglini@arm.comits implementation may not be 100% reliable. So, sometimes you do want 225713481Sgiacomo.travaglini@arm.comto _force_ Google Mock to verify a mock object before it is 225813481Sgiacomo.travaglini@arm.com(hopefully) destructed. You can do this with 225913481Sgiacomo.travaglini@arm.com`Mock::VerifyAndClearExpectations(&mock_object)`: 226013481Sgiacomo.travaglini@arm.com 226113481Sgiacomo.travaglini@arm.com``` 226213481Sgiacomo.travaglini@arm.comTEST(MyServerTest, ProcessesRequest) { 226313481Sgiacomo.travaglini@arm.com using ::testing::Mock; 226413481Sgiacomo.travaglini@arm.com 226513481Sgiacomo.travaglini@arm.com MockFoo* const foo = new MockFoo; 226613481Sgiacomo.travaglini@arm.com EXPECT_CALL(*foo, ...)...; 226713481Sgiacomo.travaglini@arm.com // ... other expectations ... 226813481Sgiacomo.travaglini@arm.com 226913481Sgiacomo.travaglini@arm.com // server now owns foo. 227013481Sgiacomo.travaglini@arm.com MyServer server(foo); 227113481Sgiacomo.travaglini@arm.com server.ProcessRequest(...); 227213481Sgiacomo.travaglini@arm.com 227313481Sgiacomo.travaglini@arm.com // In case that server's destructor will forget to delete foo, 227413481Sgiacomo.travaglini@arm.com // this will verify the expectations anyway. 227513481Sgiacomo.travaglini@arm.com Mock::VerifyAndClearExpectations(foo); 227613481Sgiacomo.travaglini@arm.com} // server is destroyed when it goes out of scope here. 227713481Sgiacomo.travaglini@arm.com``` 227813481Sgiacomo.travaglini@arm.com 227913481Sgiacomo.travaglini@arm.com**Tip:** The `Mock::VerifyAndClearExpectations()` function returns a 228013481Sgiacomo.travaglini@arm.com`bool` to indicate whether the verification was successful (`true` for 228113481Sgiacomo.travaglini@arm.comyes), so you can wrap that function call inside a `ASSERT_TRUE()` if 228213481Sgiacomo.travaglini@arm.comthere is no point going further when the verification has failed. 228313481Sgiacomo.travaglini@arm.com 228413481Sgiacomo.travaglini@arm.com## Using Check Points ## 228513481Sgiacomo.travaglini@arm.com 228613481Sgiacomo.travaglini@arm.comSometimes you may want to "reset" a mock object at various check 228713481Sgiacomo.travaglini@arm.compoints in your test: at each check point, you verify that all existing 228813481Sgiacomo.travaglini@arm.comexpectations on the mock object have been satisfied, and then you set 228913481Sgiacomo.travaglini@arm.comsome new expectations on it as if it's newly created. This allows you 229013481Sgiacomo.travaglini@arm.comto work with a mock object in "phases" whose sizes are each 229113481Sgiacomo.travaglini@arm.commanageable. 229213481Sgiacomo.travaglini@arm.com 229313481Sgiacomo.travaglini@arm.comOne such scenario is that in your test's `SetUp()` function, you may 229413481Sgiacomo.travaglini@arm.comwant to put the object you are testing into a certain state, with the 229513481Sgiacomo.travaglini@arm.comhelp from a mock object. Once in the desired state, you want to clear 229613481Sgiacomo.travaglini@arm.comall expectations on the mock, such that in the `TEST_F` body you can 229713481Sgiacomo.travaglini@arm.comset fresh expectations on it. 229813481Sgiacomo.travaglini@arm.com 229913481Sgiacomo.travaglini@arm.comAs you may have figured out, the `Mock::VerifyAndClearExpectations()` 230013481Sgiacomo.travaglini@arm.comfunction we saw in the previous recipe can help you here. Or, if you 230113481Sgiacomo.travaglini@arm.comare using `ON_CALL()` to set default actions on the mock object and 230213481Sgiacomo.travaglini@arm.comwant to clear the default actions as well, use 230313481Sgiacomo.travaglini@arm.com`Mock::VerifyAndClear(&mock_object)` instead. This function does what 230413481Sgiacomo.travaglini@arm.com`Mock::VerifyAndClearExpectations(&mock_object)` does and returns the 230513481Sgiacomo.travaglini@arm.comsame `bool`, **plus** it clears the `ON_CALL()` statements on 230613481Sgiacomo.travaglini@arm.com`mock_object` too. 230713481Sgiacomo.travaglini@arm.com 230813481Sgiacomo.travaglini@arm.comAnother trick you can use to achieve the same effect is to put the 230913481Sgiacomo.travaglini@arm.comexpectations in sequences and insert calls to a dummy "check-point" 231013481Sgiacomo.travaglini@arm.comfunction at specific places. Then you can verify that the mock 231113481Sgiacomo.travaglini@arm.comfunction calls do happen at the right time. For example, if you are 231213481Sgiacomo.travaglini@arm.comexercising code: 231313481Sgiacomo.travaglini@arm.com 231413481Sgiacomo.travaglini@arm.com``` 231513481Sgiacomo.travaglini@arm.comFoo(1); 231613481Sgiacomo.travaglini@arm.comFoo(2); 231713481Sgiacomo.travaglini@arm.comFoo(3); 231813481Sgiacomo.travaglini@arm.com``` 231913481Sgiacomo.travaglini@arm.com 232013481Sgiacomo.travaglini@arm.comand want to verify that `Foo(1)` and `Foo(3)` both invoke 232113481Sgiacomo.travaglini@arm.com`mock.Bar("a")`, but `Foo(2)` doesn't invoke anything. You can write: 232213481Sgiacomo.travaglini@arm.com 232313481Sgiacomo.travaglini@arm.com``` 232413481Sgiacomo.travaglini@arm.comusing ::testing::MockFunction; 232513481Sgiacomo.travaglini@arm.com 232613481Sgiacomo.travaglini@arm.comTEST(FooTest, InvokesBarCorrectly) { 232713481Sgiacomo.travaglini@arm.com MyMock mock; 232813481Sgiacomo.travaglini@arm.com // Class MockFunction<F> has exactly one mock method. It is named 232913481Sgiacomo.travaglini@arm.com // Call() and has type F. 233013481Sgiacomo.travaglini@arm.com MockFunction<void(string check_point_name)> check; 233113481Sgiacomo.travaglini@arm.com { 233213481Sgiacomo.travaglini@arm.com InSequence s; 233313481Sgiacomo.travaglini@arm.com 233413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Bar("a")); 233513481Sgiacomo.travaglini@arm.com EXPECT_CALL(check, Call("1")); 233613481Sgiacomo.travaglini@arm.com EXPECT_CALL(check, Call("2")); 233713481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Bar("a")); 233813481Sgiacomo.travaglini@arm.com } 233913481Sgiacomo.travaglini@arm.com Foo(1); 234013481Sgiacomo.travaglini@arm.com check.Call("1"); 234113481Sgiacomo.travaglini@arm.com Foo(2); 234213481Sgiacomo.travaglini@arm.com check.Call("2"); 234313481Sgiacomo.travaglini@arm.com Foo(3); 234413481Sgiacomo.travaglini@arm.com} 234513481Sgiacomo.travaglini@arm.com``` 234613481Sgiacomo.travaglini@arm.com 234713481Sgiacomo.travaglini@arm.comThe expectation spec says that the first `Bar("a")` must happen before 234813481Sgiacomo.travaglini@arm.comcheck point "1", the second `Bar("a")` must happen after check point "2", 234913481Sgiacomo.travaglini@arm.comand nothing should happen between the two check points. The explicit 235013481Sgiacomo.travaglini@arm.comcheck points make it easy to tell which `Bar("a")` is called by which 235113481Sgiacomo.travaglini@arm.comcall to `Foo()`. 235213481Sgiacomo.travaglini@arm.com 235313481Sgiacomo.travaglini@arm.com## Mocking Destructors ## 235413481Sgiacomo.travaglini@arm.com 235513481Sgiacomo.travaglini@arm.comSometimes you want to make sure a mock object is destructed at the 235613481Sgiacomo.travaglini@arm.comright time, e.g. after `bar->A()` is called but before `bar->B()` is 235713481Sgiacomo.travaglini@arm.comcalled. We already know that you can specify constraints on the order 235813481Sgiacomo.travaglini@arm.comof mock function calls, so all we need to do is to mock the destructor 235913481Sgiacomo.travaglini@arm.comof the mock function. 236013481Sgiacomo.travaglini@arm.com 236113481Sgiacomo.travaglini@arm.comThis sounds simple, except for one problem: a destructor is a special 236213481Sgiacomo.travaglini@arm.comfunction with special syntax and special semantics, and the 236313481Sgiacomo.travaglini@arm.com`MOCK_METHOD0` macro doesn't work for it: 236413481Sgiacomo.travaglini@arm.com 236513481Sgiacomo.travaglini@arm.com``` 236613481Sgiacomo.travaglini@arm.com MOCK_METHOD0(~MockFoo, void()); // Won't compile! 236713481Sgiacomo.travaglini@arm.com``` 236813481Sgiacomo.travaglini@arm.com 236913481Sgiacomo.travaglini@arm.comThe good news is that you can use a simple pattern to achieve the same 237013481Sgiacomo.travaglini@arm.comeffect. First, add a mock function `Die()` to your mock class and call 237113481Sgiacomo.travaglini@arm.comit in the destructor, like this: 237213481Sgiacomo.travaglini@arm.com 237313481Sgiacomo.travaglini@arm.com``` 237413481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 237513481Sgiacomo.travaglini@arm.com ... 237613481Sgiacomo.travaglini@arm.com // Add the following two lines to the mock class. 237713481Sgiacomo.travaglini@arm.com MOCK_METHOD0(Die, void()); 237813481Sgiacomo.travaglini@arm.com virtual ~MockFoo() { Die(); } 237913481Sgiacomo.travaglini@arm.com}; 238013481Sgiacomo.travaglini@arm.com``` 238113481Sgiacomo.travaglini@arm.com 238213481Sgiacomo.travaglini@arm.com(If the name `Die()` clashes with an existing symbol, choose another 238313481Sgiacomo.travaglini@arm.comname.) Now, we have translated the problem of testing when a `MockFoo` 238413481Sgiacomo.travaglini@arm.comobject dies to testing when its `Die()` method is called: 238513481Sgiacomo.travaglini@arm.com 238613481Sgiacomo.travaglini@arm.com``` 238713481Sgiacomo.travaglini@arm.com MockFoo* foo = new MockFoo; 238813481Sgiacomo.travaglini@arm.com MockBar* bar = new MockBar; 238913481Sgiacomo.travaglini@arm.com ... 239013481Sgiacomo.travaglini@arm.com { 239113481Sgiacomo.travaglini@arm.com InSequence s; 239213481Sgiacomo.travaglini@arm.com 239313481Sgiacomo.travaglini@arm.com // Expects *foo to die after bar->A() and before bar->B(). 239413481Sgiacomo.travaglini@arm.com EXPECT_CALL(*bar, A()); 239513481Sgiacomo.travaglini@arm.com EXPECT_CALL(*foo, Die()); 239613481Sgiacomo.travaglini@arm.com EXPECT_CALL(*bar, B()); 239713481Sgiacomo.travaglini@arm.com } 239813481Sgiacomo.travaglini@arm.com``` 239913481Sgiacomo.travaglini@arm.com 240013481Sgiacomo.travaglini@arm.comAnd that's that. 240113481Sgiacomo.travaglini@arm.com 240213481Sgiacomo.travaglini@arm.com## Using Google Mock and Threads ## 240313481Sgiacomo.travaglini@arm.com 240413481Sgiacomo.travaglini@arm.com**IMPORTANT NOTE:** What we describe in this recipe is **ONLY** true on 240513481Sgiacomo.travaglini@arm.complatforms where Google Mock is thread-safe. Currently these are only 240613481Sgiacomo.travaglini@arm.complatforms that support the pthreads library (this includes Linux and Mac). 240713481Sgiacomo.travaglini@arm.comTo make it thread-safe on other platforms we only need to implement 240813481Sgiacomo.travaglini@arm.comsome synchronization operations in `"gtest/internal/gtest-port.h"`. 240913481Sgiacomo.travaglini@arm.com 241013481Sgiacomo.travaglini@arm.comIn a **unit** test, it's best if you could isolate and test a piece of 241113481Sgiacomo.travaglini@arm.comcode in a single-threaded context. That avoids race conditions and 241213481Sgiacomo.travaglini@arm.comdead locks, and makes debugging your test much easier. 241313481Sgiacomo.travaglini@arm.com 241413481Sgiacomo.travaglini@arm.comYet many programs are multi-threaded, and sometimes to test something 241513481Sgiacomo.travaglini@arm.comwe need to pound on it from more than one thread. Google Mock works 241613481Sgiacomo.travaglini@arm.comfor this purpose too. 241713481Sgiacomo.travaglini@arm.com 241813481Sgiacomo.travaglini@arm.comRemember the steps for using a mock: 241913481Sgiacomo.travaglini@arm.com 242013481Sgiacomo.travaglini@arm.com 1. Create a mock object `foo`. 242113481Sgiacomo.travaglini@arm.com 1. Set its default actions and expectations using `ON_CALL()` and `EXPECT_CALL()`. 242213481Sgiacomo.travaglini@arm.com 1. The code under test calls methods of `foo`. 242313481Sgiacomo.travaglini@arm.com 1. Optionally, verify and reset the mock. 242413481Sgiacomo.travaglini@arm.com 1. Destroy the mock yourself, or let the code under test destroy it. The destructor will automatically verify it. 242513481Sgiacomo.travaglini@arm.com 242613481Sgiacomo.travaglini@arm.comIf you follow the following simple rules, your mocks and threads can 242713481Sgiacomo.travaglini@arm.comlive happily togeter: 242813481Sgiacomo.travaglini@arm.com 242913481Sgiacomo.travaglini@arm.com * Execute your _test code_ (as opposed to the code being tested) in _one_ thread. This makes your test easy to follow. 243013481Sgiacomo.travaglini@arm.com * Obviously, you can do step #1 without locking. 243113481Sgiacomo.travaglini@arm.com * When doing step #2 and #5, make sure no other thread is accessing `foo`. Obvious too, huh? 243213481Sgiacomo.travaglini@arm.com * #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. 243313481Sgiacomo.travaglini@arm.com 243413481Sgiacomo.travaglini@arm.comIf you violate the rules (for example, if you set expectations on a 243513481Sgiacomo.travaglini@arm.commock while another thread is calling its methods), you get undefined 243613481Sgiacomo.travaglini@arm.combehavior. That's not fun, so don't do it. 243713481Sgiacomo.travaglini@arm.com 243813481Sgiacomo.travaglini@arm.comGoogle Mock guarantees that the action for a mock function is done in 243913481Sgiacomo.travaglini@arm.comthe same thread that called the mock function. For example, in 244013481Sgiacomo.travaglini@arm.com 244113481Sgiacomo.travaglini@arm.com``` 244213481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(1)) 244313481Sgiacomo.travaglini@arm.com .WillOnce(action1); 244413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(2)) 244513481Sgiacomo.travaglini@arm.com .WillOnce(action2); 244613481Sgiacomo.travaglini@arm.com``` 244713481Sgiacomo.travaglini@arm.com 244813481Sgiacomo.travaglini@arm.comif `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, 244913481Sgiacomo.travaglini@arm.comGoogle Mock will execute `action1` in thread 1 and `action2` in thread 245013481Sgiacomo.travaglini@arm.com2. 245113481Sgiacomo.travaglini@arm.com 245213481Sgiacomo.travaglini@arm.comGoogle Mock does _not_ impose a sequence on actions performed in 245313481Sgiacomo.travaglini@arm.comdifferent threads (doing so may create deadlocks as the actions may 245413481Sgiacomo.travaglini@arm.comneed to cooperate). This means that the execution of `action1` and 245513481Sgiacomo.travaglini@arm.com`action2` in the above example _may_ interleave. If this is a problem, 245613481Sgiacomo.travaglini@arm.comyou should add proper synchronization logic to `action1` and `action2` 245713481Sgiacomo.travaglini@arm.comto make the test thread-safe. 245813481Sgiacomo.travaglini@arm.com 245913481Sgiacomo.travaglini@arm.com 246013481Sgiacomo.travaglini@arm.comAlso, remember that `DefaultValue<T>` is a global resource that 246113481Sgiacomo.travaglini@arm.compotentially affects _all_ living mock objects in your 246213481Sgiacomo.travaglini@arm.comprogram. Naturally, you won't want to mess with it from multiple 246313481Sgiacomo.travaglini@arm.comthreads or when there still are mocks in action. 246413481Sgiacomo.travaglini@arm.com 246513481Sgiacomo.travaglini@arm.com## Controlling How Much Information Google Mock Prints ## 246613481Sgiacomo.travaglini@arm.com 246713481Sgiacomo.travaglini@arm.comWhen Google Mock sees something that has the potential of being an 246813481Sgiacomo.travaglini@arm.comerror (e.g. a mock function with no expectation is called, a.k.a. an 246913481Sgiacomo.travaglini@arm.comuninteresting call, which is allowed but perhaps you forgot to 247013481Sgiacomo.travaglini@arm.comexplicitly ban the call), it prints some warning messages, including 247113481Sgiacomo.travaglini@arm.comthe arguments of the function and the return value. Hopefully this 247213481Sgiacomo.travaglini@arm.comwill remind you to take a look and see if there is indeed a problem. 247313481Sgiacomo.travaglini@arm.com 247413481Sgiacomo.travaglini@arm.comSometimes you are confident that your tests are correct and may not 247513481Sgiacomo.travaglini@arm.comappreciate such friendly messages. Some other times, you are debugging 247613481Sgiacomo.travaglini@arm.comyour tests or learning about the behavior of the code you are testing, 247713481Sgiacomo.travaglini@arm.comand wish you could observe every mock call that happens (including 247813481Sgiacomo.travaglini@arm.comargument values and the return value). Clearly, one size doesn't fit 247913481Sgiacomo.travaglini@arm.comall. 248013481Sgiacomo.travaglini@arm.com 248113481Sgiacomo.travaglini@arm.comYou can control how much Google Mock tells you using the 248213481Sgiacomo.travaglini@arm.com`--gmock_verbose=LEVEL` command-line flag, where `LEVEL` is a string 248313481Sgiacomo.travaglini@arm.comwith three possible values: 248413481Sgiacomo.travaglini@arm.com 248513481Sgiacomo.travaglini@arm.com * `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. 248613481Sgiacomo.travaglini@arm.com * `warning`: Google Mock will print both warnings and errors (less verbose). This is the default. 248713481Sgiacomo.travaglini@arm.com * `error`: Google Mock will print errors only (least verbose). 248813481Sgiacomo.travaglini@arm.com 248913481Sgiacomo.travaglini@arm.comAlternatively, you can adjust the value of that flag from within your 249013481Sgiacomo.travaglini@arm.comtests like so: 249113481Sgiacomo.travaglini@arm.com 249213481Sgiacomo.travaglini@arm.com``` 249313481Sgiacomo.travaglini@arm.com ::testing::FLAGS_gmock_verbose = "error"; 249413481Sgiacomo.travaglini@arm.com``` 249513481Sgiacomo.travaglini@arm.com 249613481Sgiacomo.travaglini@arm.comNow, judiciously use the right flag to enable Google Mock serve you better! 249713481Sgiacomo.travaglini@arm.com 249813481Sgiacomo.travaglini@arm.com## Gaining Super Vision into Mock Calls ## 249913481Sgiacomo.travaglini@arm.com 250013481Sgiacomo.travaglini@arm.comYou have a test using Google Mock. It fails: Google Mock tells you 250113481Sgiacomo.travaglini@arm.comthat some expectations aren't satisfied. However, you aren't sure why: 250213481Sgiacomo.travaglini@arm.comIs there a typo somewhere in the matchers? Did you mess up the order 250313481Sgiacomo.travaglini@arm.comof the `EXPECT_CALL`s? Or is the code under test doing something 250413481Sgiacomo.travaglini@arm.comwrong? How can you find out the cause? 250513481Sgiacomo.travaglini@arm.com 250613481Sgiacomo.travaglini@arm.comWon't it be nice if you have X-ray vision and can actually see the 250713481Sgiacomo.travaglini@arm.comtrace of all `EXPECT_CALL`s and mock method calls as they are made? 250813481Sgiacomo.travaglini@arm.comFor each call, would you like to see its actual argument values and 250913481Sgiacomo.travaglini@arm.comwhich `EXPECT_CALL` Google Mock thinks it matches? 251013481Sgiacomo.travaglini@arm.com 251113481Sgiacomo.travaglini@arm.comYou can unlock this power by running your test with the 251213481Sgiacomo.travaglini@arm.com`--gmock_verbose=info` flag. For example, given the test program: 251313481Sgiacomo.travaglini@arm.com 251413481Sgiacomo.travaglini@arm.com``` 251513481Sgiacomo.travaglini@arm.comusing testing::_; 251613481Sgiacomo.travaglini@arm.comusing testing::HasSubstr; 251713481Sgiacomo.travaglini@arm.comusing testing::Return; 251813481Sgiacomo.travaglini@arm.com 251913481Sgiacomo.travaglini@arm.comclass MockFoo { 252013481Sgiacomo.travaglini@arm.com public: 252113481Sgiacomo.travaglini@arm.com MOCK_METHOD2(F, void(const string& x, const string& y)); 252213481Sgiacomo.travaglini@arm.com}; 252313481Sgiacomo.travaglini@arm.com 252413481Sgiacomo.travaglini@arm.comTEST(Foo, Bar) { 252513481Sgiacomo.travaglini@arm.com MockFoo mock; 252613481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return()); 252713481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, F("a", "b")); 252813481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, F("c", HasSubstr("d"))); 252913481Sgiacomo.travaglini@arm.com 253013481Sgiacomo.travaglini@arm.com mock.F("a", "good"); 253113481Sgiacomo.travaglini@arm.com mock.F("a", "b"); 253213481Sgiacomo.travaglini@arm.com} 253313481Sgiacomo.travaglini@arm.com``` 253413481Sgiacomo.travaglini@arm.com 253513481Sgiacomo.travaglini@arm.comif you run it with `--gmock_verbose=info`, you will see this output: 253613481Sgiacomo.travaglini@arm.com 253713481Sgiacomo.travaglini@arm.com``` 253813481Sgiacomo.travaglini@arm.com[ RUN ] Foo.Bar 253913481Sgiacomo.travaglini@arm.com 254013481Sgiacomo.travaglini@arm.comfoo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked 254113481Sgiacomo.travaglini@arm.comfoo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked 254213481Sgiacomo.travaglini@arm.comfoo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked 254313481Sgiacomo.travaglini@arm.comfoo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))... 254413481Sgiacomo.travaglini@arm.com Function call: F(@0x7fff7c8dad40"a", @0x7fff7c8dad10"good") 254513481Sgiacomo.travaglini@arm.comfoo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))... 254613481Sgiacomo.travaglini@arm.com Function call: F(@0x7fff7c8dada0"a", @0x7fff7c8dad70"b") 254713481Sgiacomo.travaglini@arm.comfoo_test.cc:16: Failure 254813481Sgiacomo.travaglini@arm.comActual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))... 254913481Sgiacomo.travaglini@arm.com Expected: to be called once 255013481Sgiacomo.travaglini@arm.com Actual: never called - unsatisfied and active 255113481Sgiacomo.travaglini@arm.com[ FAILED ] Foo.Bar 255213481Sgiacomo.travaglini@arm.com``` 255313481Sgiacomo.travaglini@arm.com 255413481Sgiacomo.travaglini@arm.comSuppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo 255513481Sgiacomo.travaglini@arm.comand should actually be `"a"`. With the above message, you should see 255613481Sgiacomo.travaglini@arm.comthat the actual `F("a", "good")` call is matched by the first 255713481Sgiacomo.travaglini@arm.com`EXPECT_CALL`, not the third as you thought. From that it should be 255813481Sgiacomo.travaglini@arm.comobvious that the third `EXPECT_CALL` is written wrong. Case solved. 255913481Sgiacomo.travaglini@arm.com 256013481Sgiacomo.travaglini@arm.com## Running Tests in Emacs ## 256113481Sgiacomo.travaglini@arm.com 256213481Sgiacomo.travaglini@arm.comIf you build and run your tests in Emacs, the source file locations of 256313481Sgiacomo.travaglini@arm.comGoogle Mock and [Google Test](http://code.google.com/p/googletest/) 256413481Sgiacomo.travaglini@arm.comerrors will be highlighted. Just press `<Enter>` on one of them and 256513481Sgiacomo.travaglini@arm.comyou'll be taken to the offending line. Or, you can just type `C-x `` 256613481Sgiacomo.travaglini@arm.comto jump to the next error. 256713481Sgiacomo.travaglini@arm.com 256813481Sgiacomo.travaglini@arm.comTo make it even easier, you can add the following lines to your 256913481Sgiacomo.travaglini@arm.com`~/.emacs` file: 257013481Sgiacomo.travaglini@arm.com 257113481Sgiacomo.travaglini@arm.com``` 257213481Sgiacomo.travaglini@arm.com(global-set-key "\M-m" 'compile) ; m is for make 257313481Sgiacomo.travaglini@arm.com(global-set-key [M-down] 'next-error) 257413481Sgiacomo.travaglini@arm.com(global-set-key [M-up] '(lambda () (interactive) (next-error -1))) 257513481Sgiacomo.travaglini@arm.com``` 257613481Sgiacomo.travaglini@arm.com 257713481Sgiacomo.travaglini@arm.comThen you can type `M-m` to start a build, or `M-up`/`M-down` to move 257813481Sgiacomo.travaglini@arm.comback and forth between errors. 257913481Sgiacomo.travaglini@arm.com 258013481Sgiacomo.travaglini@arm.com## Fusing Google Mock Source Files ## 258113481Sgiacomo.travaglini@arm.com 258213481Sgiacomo.travaglini@arm.comGoogle Mock's implementation consists of dozens of files (excluding 258313481Sgiacomo.travaglini@arm.comits own tests). Sometimes you may want them to be packaged up in 258413481Sgiacomo.travaglini@arm.comfewer files instead, such that you can easily copy them to a new 258513481Sgiacomo.travaglini@arm.commachine and start hacking there. For this we provide an experimental 258613481Sgiacomo.travaglini@arm.comPython script `fuse_gmock_files.py` in the `scripts/` directory 258713481Sgiacomo.travaglini@arm.com(starting with release 1.2.0). Assuming you have Python 2.4 or above 258813481Sgiacomo.travaglini@arm.cominstalled on your machine, just go to that directory and run 258913481Sgiacomo.travaglini@arm.com``` 259013481Sgiacomo.travaglini@arm.compython fuse_gmock_files.py OUTPUT_DIR 259113481Sgiacomo.travaglini@arm.com``` 259213481Sgiacomo.travaglini@arm.com 259313481Sgiacomo.travaglini@arm.comand you should see an `OUTPUT_DIR` directory being created with files 259413481Sgiacomo.travaglini@arm.com`gtest/gtest.h`, `gmock/gmock.h`, and `gmock-gtest-all.cc` in it. 259513481Sgiacomo.travaglini@arm.comThese three files contain everything you need to use Google Mock (and 259613481Sgiacomo.travaglini@arm.comGoogle Test). Just copy them to anywhere you want and you are ready 259713481Sgiacomo.travaglini@arm.comto write tests and use mocks. You can use the 259813481Sgiacomo.travaglini@arm.com[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 259913481Sgiacomo.travaglini@arm.comagainst them. 260013481Sgiacomo.travaglini@arm.com 260113481Sgiacomo.travaglini@arm.com# Extending Google Mock # 260213481Sgiacomo.travaglini@arm.com 260313481Sgiacomo.travaglini@arm.com## Writing New Matchers Quickly ## 260413481Sgiacomo.travaglini@arm.com 260513481Sgiacomo.travaglini@arm.comThe `MATCHER*` family of macros can be used to define custom matchers 260613481Sgiacomo.travaglini@arm.comeasily. The syntax: 260713481Sgiacomo.travaglini@arm.com 260813481Sgiacomo.travaglini@arm.com``` 260913481Sgiacomo.travaglini@arm.comMATCHER(name, description_string_expression) { statements; } 261013481Sgiacomo.travaglini@arm.com``` 261113481Sgiacomo.travaglini@arm.com 261213481Sgiacomo.travaglini@arm.comwill define a matcher with the given name that executes the 261313481Sgiacomo.travaglini@arm.comstatements, which must return a `bool` to indicate if the match 261413481Sgiacomo.travaglini@arm.comsucceeds. Inside the statements, you can refer to the value being 261513481Sgiacomo.travaglini@arm.commatched by `arg`, and refer to its type by `arg_type`. 261613481Sgiacomo.travaglini@arm.com 261713481Sgiacomo.travaglini@arm.comThe description string is a `string`-typed expression that documents 261813481Sgiacomo.travaglini@arm.comwhat the matcher does, and is used to generate the failure message 261913481Sgiacomo.travaglini@arm.comwhen the match fails. It can (and should) reference the special 262013481Sgiacomo.travaglini@arm.com`bool` variable `negation`, and should evaluate to the description of 262113481Sgiacomo.travaglini@arm.comthe matcher when `negation` is `false`, or that of the matcher's 262213481Sgiacomo.travaglini@arm.comnegation when `negation` is `true`. 262313481Sgiacomo.travaglini@arm.com 262413481Sgiacomo.travaglini@arm.comFor convenience, we allow the description string to be empty (`""`), 262513481Sgiacomo.travaglini@arm.comin which case Google Mock will use the sequence of words in the 262613481Sgiacomo.travaglini@arm.commatcher name as the description. 262713481Sgiacomo.travaglini@arm.com 262813481Sgiacomo.travaglini@arm.comFor example: 262913481Sgiacomo.travaglini@arm.com``` 263013481Sgiacomo.travaglini@arm.comMATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; } 263113481Sgiacomo.travaglini@arm.com``` 263213481Sgiacomo.travaglini@arm.comallows you to write 263313481Sgiacomo.travaglini@arm.com``` 263413481Sgiacomo.travaglini@arm.com // Expects mock_foo.Bar(n) to be called where n is divisible by 7. 263513481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7())); 263613481Sgiacomo.travaglini@arm.com``` 263713481Sgiacomo.travaglini@arm.comor, 263813481Sgiacomo.travaglini@arm.com``` 263913481Sgiacomo.travaglini@arm.comusing ::testing::Not; 264013481Sgiacomo.travaglini@arm.com... 264113481Sgiacomo.travaglini@arm.com EXPECT_THAT(some_expression, IsDivisibleBy7()); 264213481Sgiacomo.travaglini@arm.com EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7())); 264313481Sgiacomo.travaglini@arm.com``` 264413481Sgiacomo.travaglini@arm.comIf the above assertions fail, they will print something like: 264513481Sgiacomo.travaglini@arm.com``` 264613481Sgiacomo.travaglini@arm.com Value of: some_expression 264713481Sgiacomo.travaglini@arm.com Expected: is divisible by 7 264813481Sgiacomo.travaglini@arm.com Actual: 27 264913481Sgiacomo.travaglini@arm.com... 265013481Sgiacomo.travaglini@arm.com Value of: some_other_expression 265113481Sgiacomo.travaglini@arm.com Expected: not (is divisible by 7) 265213481Sgiacomo.travaglini@arm.com Actual: 21 265313481Sgiacomo.travaglini@arm.com``` 265413481Sgiacomo.travaglini@arm.comwhere the descriptions `"is divisible by 7"` and `"not (is divisible 265513481Sgiacomo.travaglini@arm.comby 7)"` are automatically calculated from the matcher name 265613481Sgiacomo.travaglini@arm.com`IsDivisibleBy7`. 265713481Sgiacomo.travaglini@arm.com 265813481Sgiacomo.travaglini@arm.comAs you may have noticed, the auto-generated descriptions (especially 265913481Sgiacomo.travaglini@arm.comthose for the negation) may not be so great. You can always override 266013481Sgiacomo.travaglini@arm.comthem with a string expression of your own: 266113481Sgiacomo.travaglini@arm.com``` 266213481Sgiacomo.travaglini@arm.comMATCHER(IsDivisibleBy7, std::string(negation ? "isn't" : "is") + 266313481Sgiacomo.travaglini@arm.com " divisible by 7") { 266413481Sgiacomo.travaglini@arm.com return (arg % 7) == 0; 266513481Sgiacomo.travaglini@arm.com} 266613481Sgiacomo.travaglini@arm.com``` 266713481Sgiacomo.travaglini@arm.com 266813481Sgiacomo.travaglini@arm.comOptionally, you can stream additional information to a hidden argument 266913481Sgiacomo.travaglini@arm.comnamed `result_listener` to explain the match result. For example, a 267013481Sgiacomo.travaglini@arm.combetter definition of `IsDivisibleBy7` is: 267113481Sgiacomo.travaglini@arm.com``` 267213481Sgiacomo.travaglini@arm.comMATCHER(IsDivisibleBy7, "") { 267313481Sgiacomo.travaglini@arm.com if ((arg % 7) == 0) 267413481Sgiacomo.travaglini@arm.com return true; 267513481Sgiacomo.travaglini@arm.com 267613481Sgiacomo.travaglini@arm.com *result_listener << "the remainder is " << (arg % 7); 267713481Sgiacomo.travaglini@arm.com return false; 267813481Sgiacomo.travaglini@arm.com} 267913481Sgiacomo.travaglini@arm.com``` 268013481Sgiacomo.travaglini@arm.com 268113481Sgiacomo.travaglini@arm.comWith this definition, the above assertion will give a better message: 268213481Sgiacomo.travaglini@arm.com``` 268313481Sgiacomo.travaglini@arm.com Value of: some_expression 268413481Sgiacomo.travaglini@arm.com Expected: is divisible by 7 268513481Sgiacomo.travaglini@arm.com Actual: 27 (the remainder is 6) 268613481Sgiacomo.travaglini@arm.com``` 268713481Sgiacomo.travaglini@arm.com 268813481Sgiacomo.travaglini@arm.comYou should let `MatchAndExplain()` print _any additional information_ 268913481Sgiacomo.travaglini@arm.comthat can help a user understand the match result. Note that it should 269013481Sgiacomo.travaglini@arm.comexplain why the match succeeds in case of a success (unless it's 269113481Sgiacomo.travaglini@arm.comobvious) - this is useful when the matcher is used inside 269213481Sgiacomo.travaglini@arm.com`Not()`. There is no need to print the argument value itself, as 269313481Sgiacomo.travaglini@arm.comGoogle Mock already prints it for you. 269413481Sgiacomo.travaglini@arm.com 269513481Sgiacomo.travaglini@arm.com**Notes:** 269613481Sgiacomo.travaglini@arm.com 269713481Sgiacomo.travaglini@arm.com 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. 269813481Sgiacomo.travaglini@arm.com 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. 269913481Sgiacomo.travaglini@arm.com 270013481Sgiacomo.travaglini@arm.com## Writing New Parameterized Matchers Quickly ## 270113481Sgiacomo.travaglini@arm.com 270213481Sgiacomo.travaglini@arm.comSometimes you'll want to define a matcher that has parameters. For that you 270313481Sgiacomo.travaglini@arm.comcan use the macro: 270413481Sgiacomo.travaglini@arm.com``` 270513481Sgiacomo.travaglini@arm.comMATCHER_P(name, param_name, description_string) { statements; } 270613481Sgiacomo.travaglini@arm.com``` 270713481Sgiacomo.travaglini@arm.comwhere the description string can be either `""` or a string expression 270813481Sgiacomo.travaglini@arm.comthat references `negation` and `param_name`. 270913481Sgiacomo.travaglini@arm.com 271013481Sgiacomo.travaglini@arm.comFor example: 271113481Sgiacomo.travaglini@arm.com``` 271213481Sgiacomo.travaglini@arm.comMATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; } 271313481Sgiacomo.travaglini@arm.com``` 271413481Sgiacomo.travaglini@arm.comwill allow you to write: 271513481Sgiacomo.travaglini@arm.com``` 271613481Sgiacomo.travaglini@arm.com EXPECT_THAT(Blah("a"), HasAbsoluteValue(n)); 271713481Sgiacomo.travaglini@arm.com``` 271813481Sgiacomo.travaglini@arm.comwhich may lead to this message (assuming `n` is 10): 271913481Sgiacomo.travaglini@arm.com``` 272013481Sgiacomo.travaglini@arm.com Value of: Blah("a") 272113481Sgiacomo.travaglini@arm.com Expected: has absolute value 10 272213481Sgiacomo.travaglini@arm.com Actual: -9 272313481Sgiacomo.travaglini@arm.com``` 272413481Sgiacomo.travaglini@arm.com 272513481Sgiacomo.travaglini@arm.comNote that both the matcher description and its parameter are 272613481Sgiacomo.travaglini@arm.comprinted, making the message human-friendly. 272713481Sgiacomo.travaglini@arm.com 272813481Sgiacomo.travaglini@arm.comIn the matcher definition body, you can write `foo_type` to 272913481Sgiacomo.travaglini@arm.comreference the type of a parameter named `foo`. For example, in the 273013481Sgiacomo.travaglini@arm.combody of `MATCHER_P(HasAbsoluteValue, value)` above, you can write 273113481Sgiacomo.travaglini@arm.com`value_type` to refer to the type of `value`. 273213481Sgiacomo.travaglini@arm.com 273313481Sgiacomo.travaglini@arm.comGoogle Mock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to 273413481Sgiacomo.travaglini@arm.com`MATCHER_P10` to support multi-parameter matchers: 273513481Sgiacomo.travaglini@arm.com``` 273613481Sgiacomo.travaglini@arm.comMATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; } 273713481Sgiacomo.travaglini@arm.com``` 273813481Sgiacomo.travaglini@arm.com 273913481Sgiacomo.travaglini@arm.comPlease note that the custom description string is for a particular 274013481Sgiacomo.travaglini@arm.com**instance** of the matcher, where the parameters have been bound to 274113481Sgiacomo.travaglini@arm.comactual values. Therefore usually you'll want the parameter values to 274213481Sgiacomo.travaglini@arm.combe part of the description. Google Mock lets you do that by 274313481Sgiacomo.travaglini@arm.comreferencing the matcher parameters in the description string 274413481Sgiacomo.travaglini@arm.comexpression. 274513481Sgiacomo.travaglini@arm.com 274613481Sgiacomo.travaglini@arm.comFor example, 274713481Sgiacomo.travaglini@arm.com``` 274813481Sgiacomo.travaglini@arm.com using ::testing::PrintToString; 274913481Sgiacomo.travaglini@arm.com MATCHER_P2(InClosedRange, low, hi, 275013481Sgiacomo.travaglini@arm.com std::string(negation ? "isn't" : "is") + " in range [" + 275113481Sgiacomo.travaglini@arm.com PrintToString(low) + ", " + PrintToString(hi) + "]") { 275213481Sgiacomo.travaglini@arm.com return low <= arg && arg <= hi; 275313481Sgiacomo.travaglini@arm.com } 275413481Sgiacomo.travaglini@arm.com ... 275513481Sgiacomo.travaglini@arm.com EXPECT_THAT(3, InClosedRange(4, 6)); 275613481Sgiacomo.travaglini@arm.com``` 275713481Sgiacomo.travaglini@arm.comwould generate a failure that contains the message: 275813481Sgiacomo.travaglini@arm.com``` 275913481Sgiacomo.travaglini@arm.com Expected: is in range [4, 6] 276013481Sgiacomo.travaglini@arm.com``` 276113481Sgiacomo.travaglini@arm.com 276213481Sgiacomo.travaglini@arm.comIf you specify `""` as the description, the failure message will 276313481Sgiacomo.travaglini@arm.comcontain the sequence of words in the matcher name followed by the 276413481Sgiacomo.travaglini@arm.comparameter values printed as a tuple. For example, 276513481Sgiacomo.travaglini@arm.com``` 276613481Sgiacomo.travaglini@arm.com MATCHER_P2(InClosedRange, low, hi, "") { ... } 276713481Sgiacomo.travaglini@arm.com ... 276813481Sgiacomo.travaglini@arm.com EXPECT_THAT(3, InClosedRange(4, 6)); 276913481Sgiacomo.travaglini@arm.com``` 277013481Sgiacomo.travaglini@arm.comwould generate a failure that contains the text: 277113481Sgiacomo.travaglini@arm.com``` 277213481Sgiacomo.travaglini@arm.com Expected: in closed range (4, 6) 277313481Sgiacomo.travaglini@arm.com``` 277413481Sgiacomo.travaglini@arm.com 277513481Sgiacomo.travaglini@arm.comFor the purpose of typing, you can view 277613481Sgiacomo.travaglini@arm.com``` 277713481Sgiacomo.travaglini@arm.comMATCHER_Pk(Foo, p1, ..., pk, description_string) { ... } 277813481Sgiacomo.travaglini@arm.com``` 277913481Sgiacomo.travaglini@arm.comas shorthand for 278013481Sgiacomo.travaglini@arm.com``` 278113481Sgiacomo.travaglini@arm.comtemplate <typename p1_type, ..., typename pk_type> 278213481Sgiacomo.travaglini@arm.comFooMatcherPk<p1_type, ..., pk_type> 278313481Sgiacomo.travaglini@arm.comFoo(p1_type p1, ..., pk_type pk) { ... } 278413481Sgiacomo.travaglini@arm.com``` 278513481Sgiacomo.travaglini@arm.com 278613481Sgiacomo.travaglini@arm.comWhen you write `Foo(v1, ..., vk)`, the compiler infers the types of 278713481Sgiacomo.travaglini@arm.comthe parameters `v1`, ..., and `vk` for you. If you are not happy with 278813481Sgiacomo.travaglini@arm.comthe result of the type inference, you can specify the types by 278913481Sgiacomo.travaglini@arm.comexplicitly instantiating the template, as in `Foo<long, bool>(5, false)`. 279013481Sgiacomo.travaglini@arm.comAs said earlier, you don't get to (or need to) specify 279113481Sgiacomo.travaglini@arm.com`arg_type` as that's determined by the context in which the matcher 279213481Sgiacomo.travaglini@arm.comis used. 279313481Sgiacomo.travaglini@arm.com 279413481Sgiacomo.travaglini@arm.comYou can assign the result of expression `Foo(p1, ..., pk)` to a 279513481Sgiacomo.travaglini@arm.comvariable of type `FooMatcherPk<p1_type, ..., pk_type>`. This can be 279613481Sgiacomo.travaglini@arm.comuseful when composing matchers. Matchers that don't have a parameter 279713481Sgiacomo.travaglini@arm.comor have only one parameter have special types: you can assign `Foo()` 279813481Sgiacomo.travaglini@arm.comto a `FooMatcher`-typed variable, and assign `Foo(p)` to a 279913481Sgiacomo.travaglini@arm.com`FooMatcherP<p_type>`-typed variable. 280013481Sgiacomo.travaglini@arm.com 280113481Sgiacomo.travaglini@arm.comWhile you can instantiate a matcher template with reference types, 280213481Sgiacomo.travaglini@arm.compassing the parameters by pointer usually makes your code more 280313481Sgiacomo.travaglini@arm.comreadable. If, however, you still want to pass a parameter by 280413481Sgiacomo.travaglini@arm.comreference, be aware that in the failure message generated by the 280513481Sgiacomo.travaglini@arm.commatcher you will see the value of the referenced object but not its 280613481Sgiacomo.travaglini@arm.comaddress. 280713481Sgiacomo.travaglini@arm.com 280813481Sgiacomo.travaglini@arm.comYou can overload matchers with different numbers of parameters: 280913481Sgiacomo.travaglini@arm.com``` 281013481Sgiacomo.travaglini@arm.comMATCHER_P(Blah, a, description_string_1) { ... } 281113481Sgiacomo.travaglini@arm.comMATCHER_P2(Blah, a, b, description_string_2) { ... } 281213481Sgiacomo.travaglini@arm.com``` 281313481Sgiacomo.travaglini@arm.com 281413481Sgiacomo.travaglini@arm.comWhile it's tempting to always use the `MATCHER*` macros when defining 281513481Sgiacomo.travaglini@arm.coma new matcher, you should also consider implementing 281613481Sgiacomo.travaglini@arm.com`MatcherInterface` or using `MakePolymorphicMatcher()` instead (see 281713481Sgiacomo.travaglini@arm.comthe recipes that follow), especially if you need to use the matcher a 281813481Sgiacomo.travaglini@arm.comlot. While these approaches require more work, they give you more 281913481Sgiacomo.travaglini@arm.comcontrol on the types of the value being matched and the matcher 282013481Sgiacomo.travaglini@arm.comparameters, which in general leads to better compiler error messages 282113481Sgiacomo.travaglini@arm.comthat pay off in the long run. They also allow overloading matchers 282213481Sgiacomo.travaglini@arm.combased on parameter types (as opposed to just based on the number of 282313481Sgiacomo.travaglini@arm.comparameters). 282413481Sgiacomo.travaglini@arm.com 282513481Sgiacomo.travaglini@arm.com## Writing New Monomorphic Matchers ## 282613481Sgiacomo.travaglini@arm.com 282713481Sgiacomo.travaglini@arm.comA matcher of argument type `T` implements 282813481Sgiacomo.travaglini@arm.com`::testing::MatcherInterface<T>` and does two things: it tests whether a 282913481Sgiacomo.travaglini@arm.comvalue of type `T` matches the matcher, and can describe what kind of 283013481Sgiacomo.travaglini@arm.comvalues it matches. The latter ability is used for generating readable 283113481Sgiacomo.travaglini@arm.comerror messages when expectations are violated. 283213481Sgiacomo.travaglini@arm.com 283313481Sgiacomo.travaglini@arm.comThe interface looks like this: 283413481Sgiacomo.travaglini@arm.com 283513481Sgiacomo.travaglini@arm.com``` 283613481Sgiacomo.travaglini@arm.comclass MatchResultListener { 283713481Sgiacomo.travaglini@arm.com public: 283813481Sgiacomo.travaglini@arm.com ... 283913481Sgiacomo.travaglini@arm.com // Streams x to the underlying ostream; does nothing if the ostream 284013481Sgiacomo.travaglini@arm.com // is NULL. 284113481Sgiacomo.travaglini@arm.com template <typename T> 284213481Sgiacomo.travaglini@arm.com MatchResultListener& operator<<(const T& x); 284313481Sgiacomo.travaglini@arm.com 284413481Sgiacomo.travaglini@arm.com // Returns the underlying ostream. 284513481Sgiacomo.travaglini@arm.com ::std::ostream* stream(); 284613481Sgiacomo.travaglini@arm.com}; 284713481Sgiacomo.travaglini@arm.com 284813481Sgiacomo.travaglini@arm.comtemplate <typename T> 284913481Sgiacomo.travaglini@arm.comclass MatcherInterface { 285013481Sgiacomo.travaglini@arm.com public: 285113481Sgiacomo.travaglini@arm.com virtual ~MatcherInterface(); 285213481Sgiacomo.travaglini@arm.com 285313481Sgiacomo.travaglini@arm.com // Returns true iff the matcher matches x; also explains the match 285413481Sgiacomo.travaglini@arm.com // result to 'listener'. 285513481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0; 285613481Sgiacomo.travaglini@arm.com 285713481Sgiacomo.travaglini@arm.com // Describes this matcher to an ostream. 285813481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const = 0; 285913481Sgiacomo.travaglini@arm.com 286013481Sgiacomo.travaglini@arm.com // Describes the negation of this matcher to an ostream. 286113481Sgiacomo.travaglini@arm.com virtual void DescribeNegationTo(::std::ostream* os) const; 286213481Sgiacomo.travaglini@arm.com}; 286313481Sgiacomo.travaglini@arm.com``` 286413481Sgiacomo.travaglini@arm.com 286513481Sgiacomo.travaglini@arm.comIf you need a custom matcher but `Truly()` is not a good option (for 286613481Sgiacomo.travaglini@arm.comexample, you may not be happy with the way `Truly(predicate)` 286713481Sgiacomo.travaglini@arm.comdescribes itself, or you may want your matcher to be polymorphic as 286813481Sgiacomo.travaglini@arm.com`Eq(value)` is), you can define a matcher to do whatever you want in 286913481Sgiacomo.travaglini@arm.comtwo steps: first implement the matcher interface, and then define a 287013481Sgiacomo.travaglini@arm.comfactory function to create a matcher instance. The second step is not 287113481Sgiacomo.travaglini@arm.comstrictly needed but it makes the syntax of using the matcher nicer. 287213481Sgiacomo.travaglini@arm.com 287313481Sgiacomo.travaglini@arm.comFor example, you can define a matcher to test whether an `int` is 287413481Sgiacomo.travaglini@arm.comdivisible by 7 and then use it like this: 287513481Sgiacomo.travaglini@arm.com``` 287613481Sgiacomo.travaglini@arm.comusing ::testing::MakeMatcher; 287713481Sgiacomo.travaglini@arm.comusing ::testing::Matcher; 287813481Sgiacomo.travaglini@arm.comusing ::testing::MatcherInterface; 287913481Sgiacomo.travaglini@arm.comusing ::testing::MatchResultListener; 288013481Sgiacomo.travaglini@arm.com 288113481Sgiacomo.travaglini@arm.comclass DivisibleBy7Matcher : public MatcherInterface<int> { 288213481Sgiacomo.travaglini@arm.com public: 288313481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(int n, MatchResultListener* listener) const { 288413481Sgiacomo.travaglini@arm.com return (n % 7) == 0; 288513481Sgiacomo.travaglini@arm.com } 288613481Sgiacomo.travaglini@arm.com 288713481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const { 288813481Sgiacomo.travaglini@arm.com *os << "is divisible by 7"; 288913481Sgiacomo.travaglini@arm.com } 289013481Sgiacomo.travaglini@arm.com 289113481Sgiacomo.travaglini@arm.com virtual void DescribeNegationTo(::std::ostream* os) const { 289213481Sgiacomo.travaglini@arm.com *os << "is not divisible by 7"; 289313481Sgiacomo.travaglini@arm.com } 289413481Sgiacomo.travaglini@arm.com}; 289513481Sgiacomo.travaglini@arm.com 289613481Sgiacomo.travaglini@arm.cominline Matcher<int> DivisibleBy7() { 289713481Sgiacomo.travaglini@arm.com return MakeMatcher(new DivisibleBy7Matcher); 289813481Sgiacomo.travaglini@arm.com} 289913481Sgiacomo.travaglini@arm.com... 290013481Sgiacomo.travaglini@arm.com 290113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(DivisibleBy7())); 290213481Sgiacomo.travaglini@arm.com``` 290313481Sgiacomo.travaglini@arm.com 290413481Sgiacomo.travaglini@arm.comYou may improve the matcher message by streaming additional 290513481Sgiacomo.travaglini@arm.cominformation to the `listener` argument in `MatchAndExplain()`: 290613481Sgiacomo.travaglini@arm.com 290713481Sgiacomo.travaglini@arm.com``` 290813481Sgiacomo.travaglini@arm.comclass DivisibleBy7Matcher : public MatcherInterface<int> { 290913481Sgiacomo.travaglini@arm.com public: 291013481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(int n, 291113481Sgiacomo.travaglini@arm.com MatchResultListener* listener) const { 291213481Sgiacomo.travaglini@arm.com const int remainder = n % 7; 291313481Sgiacomo.travaglini@arm.com if (remainder != 0) { 291413481Sgiacomo.travaglini@arm.com *listener << "the remainder is " << remainder; 291513481Sgiacomo.travaglini@arm.com } 291613481Sgiacomo.travaglini@arm.com return remainder == 0; 291713481Sgiacomo.travaglini@arm.com } 291813481Sgiacomo.travaglini@arm.com ... 291913481Sgiacomo.travaglini@arm.com}; 292013481Sgiacomo.travaglini@arm.com``` 292113481Sgiacomo.travaglini@arm.com 292213481Sgiacomo.travaglini@arm.comThen, `EXPECT_THAT(x, DivisibleBy7());` may general a message like this: 292313481Sgiacomo.travaglini@arm.com``` 292413481Sgiacomo.travaglini@arm.comValue of: x 292513481Sgiacomo.travaglini@arm.comExpected: is divisible by 7 292613481Sgiacomo.travaglini@arm.com Actual: 23 (the remainder is 2) 292713481Sgiacomo.travaglini@arm.com``` 292813481Sgiacomo.travaglini@arm.com 292913481Sgiacomo.travaglini@arm.com## Writing New Polymorphic Matchers ## 293013481Sgiacomo.travaglini@arm.com 293113481Sgiacomo.travaglini@arm.comYou've learned how to write your own matchers in the previous 293213481Sgiacomo.travaglini@arm.comrecipe. Just one problem: a matcher created using `MakeMatcher()` only 293313481Sgiacomo.travaglini@arm.comworks for one particular type of arguments. If you want a 293413481Sgiacomo.travaglini@arm.com_polymorphic_ matcher that works with arguments of several types (for 293513481Sgiacomo.travaglini@arm.cominstance, `Eq(x)` can be used to match a `value` as long as `value` == 293613481Sgiacomo.travaglini@arm.com`x` compiles -- `value` and `x` don't have to share the same type), 293713481Sgiacomo.travaglini@arm.comyou can learn the trick from `"gmock/gmock-matchers.h"` but it's a bit 293813481Sgiacomo.travaglini@arm.cominvolved. 293913481Sgiacomo.travaglini@arm.com 294013481Sgiacomo.travaglini@arm.comFortunately, most of the time you can define a polymorphic matcher 294113481Sgiacomo.travaglini@arm.comeasily with the help of `MakePolymorphicMatcher()`. Here's how you can 294213481Sgiacomo.travaglini@arm.comdefine `NotNull()` as an example: 294313481Sgiacomo.travaglini@arm.com 294413481Sgiacomo.travaglini@arm.com``` 294513481Sgiacomo.travaglini@arm.comusing ::testing::MakePolymorphicMatcher; 294613481Sgiacomo.travaglini@arm.comusing ::testing::MatchResultListener; 294713481Sgiacomo.travaglini@arm.comusing ::testing::NotNull; 294813481Sgiacomo.travaglini@arm.comusing ::testing::PolymorphicMatcher; 294913481Sgiacomo.travaglini@arm.com 295013481Sgiacomo.travaglini@arm.comclass NotNullMatcher { 295113481Sgiacomo.travaglini@arm.com public: 295213481Sgiacomo.travaglini@arm.com // To implement a polymorphic matcher, first define a COPYABLE class 295313481Sgiacomo.travaglini@arm.com // that has three members MatchAndExplain(), DescribeTo(), and 295413481Sgiacomo.travaglini@arm.com // DescribeNegationTo(), like the following. 295513481Sgiacomo.travaglini@arm.com 295613481Sgiacomo.travaglini@arm.com // In this example, we want to use NotNull() with any pointer, so 295713481Sgiacomo.travaglini@arm.com // MatchAndExplain() accepts a pointer of any type as its first argument. 295813481Sgiacomo.travaglini@arm.com // In general, you can define MatchAndExplain() as an ordinary method or 295913481Sgiacomo.travaglini@arm.com // a method template, or even overload it. 296013481Sgiacomo.travaglini@arm.com template <typename T> 296113481Sgiacomo.travaglini@arm.com bool MatchAndExplain(T* p, 296213481Sgiacomo.travaglini@arm.com MatchResultListener* /* listener */) const { 296313481Sgiacomo.travaglini@arm.com return p != NULL; 296413481Sgiacomo.travaglini@arm.com } 296513481Sgiacomo.travaglini@arm.com 296613481Sgiacomo.travaglini@arm.com // Describes the property of a value matching this matcher. 296713481Sgiacomo.travaglini@arm.com void DescribeTo(::std::ostream* os) const { *os << "is not NULL"; } 296813481Sgiacomo.travaglini@arm.com 296913481Sgiacomo.travaglini@arm.com // Describes the property of a value NOT matching this matcher. 297013481Sgiacomo.travaglini@arm.com void DescribeNegationTo(::std::ostream* os) const { *os << "is NULL"; } 297113481Sgiacomo.travaglini@arm.com}; 297213481Sgiacomo.travaglini@arm.com 297313481Sgiacomo.travaglini@arm.com// To construct a polymorphic matcher, pass an instance of the class 297413481Sgiacomo.travaglini@arm.com// to MakePolymorphicMatcher(). Note the return type. 297513481Sgiacomo.travaglini@arm.cominline PolymorphicMatcher<NotNullMatcher> NotNull() { 297613481Sgiacomo.travaglini@arm.com return MakePolymorphicMatcher(NotNullMatcher()); 297713481Sgiacomo.travaglini@arm.com} 297813481Sgiacomo.travaglini@arm.com... 297913481Sgiacomo.travaglini@arm.com 298013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer. 298113481Sgiacomo.travaglini@arm.com``` 298213481Sgiacomo.travaglini@arm.com 298313481Sgiacomo.travaglini@arm.com**Note:** Your polymorphic matcher class does **not** need to inherit from 298413481Sgiacomo.travaglini@arm.com`MatcherInterface` or any other class, and its methods do **not** need 298513481Sgiacomo.travaglini@arm.comto be virtual. 298613481Sgiacomo.travaglini@arm.com 298713481Sgiacomo.travaglini@arm.comLike in a monomorphic matcher, you may explain the match result by 298813481Sgiacomo.travaglini@arm.comstreaming additional information to the `listener` argument in 298913481Sgiacomo.travaglini@arm.com`MatchAndExplain()`. 299013481Sgiacomo.travaglini@arm.com 299113481Sgiacomo.travaglini@arm.com## Writing New Cardinalities ## 299213481Sgiacomo.travaglini@arm.com 299313481Sgiacomo.travaglini@arm.comA cardinality is used in `Times()` to tell Google Mock how many times 299413481Sgiacomo.travaglini@arm.comyou expect a call to occur. It doesn't have to be exact. For example, 299513481Sgiacomo.travaglini@arm.comyou can say `AtLeast(5)` or `Between(2, 4)`. 299613481Sgiacomo.travaglini@arm.com 299713481Sgiacomo.travaglini@arm.comIf the built-in set of cardinalities doesn't suit you, you are free to 299813481Sgiacomo.travaglini@arm.comdefine your own by implementing the following interface (in namespace 299913481Sgiacomo.travaglini@arm.com`testing`): 300013481Sgiacomo.travaglini@arm.com 300113481Sgiacomo.travaglini@arm.com``` 300213481Sgiacomo.travaglini@arm.comclass CardinalityInterface { 300313481Sgiacomo.travaglini@arm.com public: 300413481Sgiacomo.travaglini@arm.com virtual ~CardinalityInterface(); 300513481Sgiacomo.travaglini@arm.com 300613481Sgiacomo.travaglini@arm.com // Returns true iff call_count calls will satisfy this cardinality. 300713481Sgiacomo.travaglini@arm.com virtual bool IsSatisfiedByCallCount(int call_count) const = 0; 300813481Sgiacomo.travaglini@arm.com 300913481Sgiacomo.travaglini@arm.com // Returns true iff call_count calls will saturate this cardinality. 301013481Sgiacomo.travaglini@arm.com virtual bool IsSaturatedByCallCount(int call_count) const = 0; 301113481Sgiacomo.travaglini@arm.com 301213481Sgiacomo.travaglini@arm.com // Describes self to an ostream. 301313481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const = 0; 301413481Sgiacomo.travaglini@arm.com}; 301513481Sgiacomo.travaglini@arm.com``` 301613481Sgiacomo.travaglini@arm.com 301713481Sgiacomo.travaglini@arm.comFor example, to specify that a call must occur even number of times, 301813481Sgiacomo.travaglini@arm.comyou can write 301913481Sgiacomo.travaglini@arm.com 302013481Sgiacomo.travaglini@arm.com``` 302113481Sgiacomo.travaglini@arm.comusing ::testing::Cardinality; 302213481Sgiacomo.travaglini@arm.comusing ::testing::CardinalityInterface; 302313481Sgiacomo.travaglini@arm.comusing ::testing::MakeCardinality; 302413481Sgiacomo.travaglini@arm.com 302513481Sgiacomo.travaglini@arm.comclass EvenNumberCardinality : public CardinalityInterface { 302613481Sgiacomo.travaglini@arm.com public: 302713481Sgiacomo.travaglini@arm.com virtual bool IsSatisfiedByCallCount(int call_count) const { 302813481Sgiacomo.travaglini@arm.com return (call_count % 2) == 0; 302913481Sgiacomo.travaglini@arm.com } 303013481Sgiacomo.travaglini@arm.com 303113481Sgiacomo.travaglini@arm.com virtual bool IsSaturatedByCallCount(int call_count) const { 303213481Sgiacomo.travaglini@arm.com return false; 303313481Sgiacomo.travaglini@arm.com } 303413481Sgiacomo.travaglini@arm.com 303513481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const { 303613481Sgiacomo.travaglini@arm.com *os << "called even number of times"; 303713481Sgiacomo.travaglini@arm.com } 303813481Sgiacomo.travaglini@arm.com}; 303913481Sgiacomo.travaglini@arm.com 304013481Sgiacomo.travaglini@arm.comCardinality EvenNumber() { 304113481Sgiacomo.travaglini@arm.com return MakeCardinality(new EvenNumberCardinality); 304213481Sgiacomo.travaglini@arm.com} 304313481Sgiacomo.travaglini@arm.com... 304413481Sgiacomo.travaglini@arm.com 304513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(3)) 304613481Sgiacomo.travaglini@arm.com .Times(EvenNumber()); 304713481Sgiacomo.travaglini@arm.com``` 304813481Sgiacomo.travaglini@arm.com 304913481Sgiacomo.travaglini@arm.com## Writing New Actions Quickly ## 305013481Sgiacomo.travaglini@arm.com 305113481Sgiacomo.travaglini@arm.comIf the built-in actions don't work for you, and you find it 305213481Sgiacomo.travaglini@arm.cominconvenient to use `Invoke()`, you can use a macro from the `ACTION*` 305313481Sgiacomo.travaglini@arm.comfamily to quickly define a new action that can be used in your code as 305413481Sgiacomo.travaglini@arm.comif it's a built-in action. 305513481Sgiacomo.travaglini@arm.com 305613481Sgiacomo.travaglini@arm.comBy writing 305713481Sgiacomo.travaglini@arm.com``` 305813481Sgiacomo.travaglini@arm.comACTION(name) { statements; } 305913481Sgiacomo.travaglini@arm.com``` 306013481Sgiacomo.travaglini@arm.comin a namespace scope (i.e. not inside a class or function), you will 306113481Sgiacomo.travaglini@arm.comdefine an action with the given name that executes the statements. 306213481Sgiacomo.travaglini@arm.comThe value returned by `statements` will be used as the return value of 306313481Sgiacomo.travaglini@arm.comthe action. Inside the statements, you can refer to the K-th 306413481Sgiacomo.travaglini@arm.com(0-based) argument of the mock function as `argK`. For example: 306513481Sgiacomo.travaglini@arm.com``` 306613481Sgiacomo.travaglini@arm.comACTION(IncrementArg1) { return ++(*arg1); } 306713481Sgiacomo.travaglini@arm.com``` 306813481Sgiacomo.travaglini@arm.comallows you to write 306913481Sgiacomo.travaglini@arm.com``` 307013481Sgiacomo.travaglini@arm.com... WillOnce(IncrementArg1()); 307113481Sgiacomo.travaglini@arm.com``` 307213481Sgiacomo.travaglini@arm.com 307313481Sgiacomo.travaglini@arm.comNote that you don't need to specify the types of the mock function 307413481Sgiacomo.travaglini@arm.comarguments. Rest assured that your code is type-safe though: 307513481Sgiacomo.travaglini@arm.comyou'll get a compiler error if `*arg1` doesn't support the `++` 307613481Sgiacomo.travaglini@arm.comoperator, or if the type of `++(*arg1)` isn't compatible with the mock 307713481Sgiacomo.travaglini@arm.comfunction's return type. 307813481Sgiacomo.travaglini@arm.com 307913481Sgiacomo.travaglini@arm.comAnother example: 308013481Sgiacomo.travaglini@arm.com``` 308113481Sgiacomo.travaglini@arm.comACTION(Foo) { 308213481Sgiacomo.travaglini@arm.com (*arg2)(5); 308313481Sgiacomo.travaglini@arm.com Blah(); 308413481Sgiacomo.travaglini@arm.com *arg1 = 0; 308513481Sgiacomo.travaglini@arm.com return arg0; 308613481Sgiacomo.travaglini@arm.com} 308713481Sgiacomo.travaglini@arm.com``` 308813481Sgiacomo.travaglini@arm.comdefines an action `Foo()` that invokes argument #2 (a function pointer) 308913481Sgiacomo.travaglini@arm.comwith 5, calls function `Blah()`, sets the value pointed to by argument 309013481Sgiacomo.travaglini@arm.com#1 to 0, and returns argument #0. 309113481Sgiacomo.travaglini@arm.com 309213481Sgiacomo.travaglini@arm.comFor more convenience and flexibility, you can also use the following 309313481Sgiacomo.travaglini@arm.compre-defined symbols in the body of `ACTION`: 309413481Sgiacomo.travaglini@arm.com 309513481Sgiacomo.travaglini@arm.com| `argK_type` | The type of the K-th (0-based) argument of the mock function | 309613481Sgiacomo.travaglini@arm.com|:------------|:-------------------------------------------------------------| 309713481Sgiacomo.travaglini@arm.com| `args` | All arguments of the mock function as a tuple | 309813481Sgiacomo.travaglini@arm.com| `args_type` | The type of all arguments of the mock function as a tuple | 309913481Sgiacomo.travaglini@arm.com| `return_type` | The return type of the mock function | 310013481Sgiacomo.travaglini@arm.com| `function_type` | The type of the mock function | 310113481Sgiacomo.travaglini@arm.com 310213481Sgiacomo.travaglini@arm.comFor example, when using an `ACTION` as a stub action for mock function: 310313481Sgiacomo.travaglini@arm.com``` 310413481Sgiacomo.travaglini@arm.comint DoSomething(bool flag, int* ptr); 310513481Sgiacomo.travaglini@arm.com``` 310613481Sgiacomo.travaglini@arm.comwe have: 310713481Sgiacomo.travaglini@arm.com| **Pre-defined Symbol** | **Is Bound To** | 310813481Sgiacomo.travaglini@arm.com|:-----------------------|:----------------| 310913481Sgiacomo.travaglini@arm.com| `arg0` | the value of `flag` | 311013481Sgiacomo.travaglini@arm.com| `arg0_type` | the type `bool` | 311113481Sgiacomo.travaglini@arm.com| `arg1` | the value of `ptr` | 311213481Sgiacomo.travaglini@arm.com| `arg1_type` | the type `int*` | 311313481Sgiacomo.travaglini@arm.com| `args` | the tuple `(flag, ptr)` | 311413481Sgiacomo.travaglini@arm.com| `args_type` | the type `std::tr1::tuple<bool, int*>` | 311513481Sgiacomo.travaglini@arm.com| `return_type` | the type `int` | 311613481Sgiacomo.travaglini@arm.com| `function_type` | the type `int(bool, int*)` | 311713481Sgiacomo.travaglini@arm.com 311813481Sgiacomo.travaglini@arm.com## Writing New Parameterized Actions Quickly ## 311913481Sgiacomo.travaglini@arm.com 312013481Sgiacomo.travaglini@arm.comSometimes you'll want to parameterize an action you define. For that 312113481Sgiacomo.travaglini@arm.comwe have another macro 312213481Sgiacomo.travaglini@arm.com``` 312313481Sgiacomo.travaglini@arm.comACTION_P(name, param) { statements; } 312413481Sgiacomo.travaglini@arm.com``` 312513481Sgiacomo.travaglini@arm.com 312613481Sgiacomo.travaglini@arm.comFor example, 312713481Sgiacomo.travaglini@arm.com``` 312813481Sgiacomo.travaglini@arm.comACTION_P(Add, n) { return arg0 + n; } 312913481Sgiacomo.travaglini@arm.com``` 313013481Sgiacomo.travaglini@arm.comwill allow you to write 313113481Sgiacomo.travaglini@arm.com``` 313213481Sgiacomo.travaglini@arm.com// Returns argument #0 + 5. 313313481Sgiacomo.travaglini@arm.com... WillOnce(Add(5)); 313413481Sgiacomo.travaglini@arm.com``` 313513481Sgiacomo.travaglini@arm.com 313613481Sgiacomo.travaglini@arm.comFor convenience, we use the term _arguments_ for the values used to 313713481Sgiacomo.travaglini@arm.cominvoke the mock function, and the term _parameters_ for the values 313813481Sgiacomo.travaglini@arm.comused to instantiate an action. 313913481Sgiacomo.travaglini@arm.com 314013481Sgiacomo.travaglini@arm.comNote that you don't need to provide the type of the parameter either. 314113481Sgiacomo.travaglini@arm.comSuppose the parameter is named `param`, you can also use the 314213481Sgiacomo.travaglini@arm.comGoogle-Mock-defined symbol `param_type` to refer to the type of the 314313481Sgiacomo.travaglini@arm.comparameter as inferred by the compiler. For example, in the body of 314413481Sgiacomo.travaglini@arm.com`ACTION_P(Add, n)` above, you can write `n_type` for the type of `n`. 314513481Sgiacomo.travaglini@arm.com 314613481Sgiacomo.travaglini@arm.comGoogle Mock also provides `ACTION_P2`, `ACTION_P3`, and etc to support 314713481Sgiacomo.travaglini@arm.commulti-parameter actions. For example, 314813481Sgiacomo.travaglini@arm.com``` 314913481Sgiacomo.travaglini@arm.comACTION_P2(ReturnDistanceTo, x, y) { 315013481Sgiacomo.travaglini@arm.com double dx = arg0 - x; 315113481Sgiacomo.travaglini@arm.com double dy = arg1 - y; 315213481Sgiacomo.travaglini@arm.com return sqrt(dx*dx + dy*dy); 315313481Sgiacomo.travaglini@arm.com} 315413481Sgiacomo.travaglini@arm.com``` 315513481Sgiacomo.travaglini@arm.comlets you write 315613481Sgiacomo.travaglini@arm.com``` 315713481Sgiacomo.travaglini@arm.com... WillOnce(ReturnDistanceTo(5.0, 26.5)); 315813481Sgiacomo.travaglini@arm.com``` 315913481Sgiacomo.travaglini@arm.com 316013481Sgiacomo.travaglini@arm.comYou can view `ACTION` as a degenerated parameterized action where the 316113481Sgiacomo.travaglini@arm.comnumber of parameters is 0. 316213481Sgiacomo.travaglini@arm.com 316313481Sgiacomo.travaglini@arm.comYou can also easily define actions overloaded on the number of parameters: 316413481Sgiacomo.travaglini@arm.com``` 316513481Sgiacomo.travaglini@arm.comACTION_P(Plus, a) { ... } 316613481Sgiacomo.travaglini@arm.comACTION_P2(Plus, a, b) { ... } 316713481Sgiacomo.travaglini@arm.com``` 316813481Sgiacomo.travaglini@arm.com 316913481Sgiacomo.travaglini@arm.com## Restricting the Type of an Argument or Parameter in an ACTION ## 317013481Sgiacomo.travaglini@arm.com 317113481Sgiacomo.travaglini@arm.comFor maximum brevity and reusability, the `ACTION*` macros don't ask 317213481Sgiacomo.travaglini@arm.comyou to provide the types of the mock function arguments and the action 317313481Sgiacomo.travaglini@arm.comparameters. Instead, we let the compiler infer the types for us. 317413481Sgiacomo.travaglini@arm.com 317513481Sgiacomo.travaglini@arm.comSometimes, however, we may want to be more explicit about the types. 317613481Sgiacomo.travaglini@arm.comThere are several tricks to do that. For example: 317713481Sgiacomo.travaglini@arm.com``` 317813481Sgiacomo.travaglini@arm.comACTION(Foo) { 317913481Sgiacomo.travaglini@arm.com // Makes sure arg0 can be converted to int. 318013481Sgiacomo.travaglini@arm.com int n = arg0; 318113481Sgiacomo.travaglini@arm.com ... use n instead of arg0 here ... 318213481Sgiacomo.travaglini@arm.com} 318313481Sgiacomo.travaglini@arm.com 318413481Sgiacomo.travaglini@arm.comACTION_P(Bar, param) { 318513481Sgiacomo.travaglini@arm.com // Makes sure the type of arg1 is const char*. 318613481Sgiacomo.travaglini@arm.com ::testing::StaticAssertTypeEq<const char*, arg1_type>(); 318713481Sgiacomo.travaglini@arm.com 318813481Sgiacomo.travaglini@arm.com // Makes sure param can be converted to bool. 318913481Sgiacomo.travaglini@arm.com bool flag = param; 319013481Sgiacomo.travaglini@arm.com} 319113481Sgiacomo.travaglini@arm.com``` 319213481Sgiacomo.travaglini@arm.comwhere `StaticAssertTypeEq` is a compile-time assertion in Google Test 319313481Sgiacomo.travaglini@arm.comthat verifies two types are the same. 319413481Sgiacomo.travaglini@arm.com 319513481Sgiacomo.travaglini@arm.com## Writing New Action Templates Quickly ## 319613481Sgiacomo.travaglini@arm.com 319713481Sgiacomo.travaglini@arm.comSometimes you want to give an action explicit template parameters that 319813481Sgiacomo.travaglini@arm.comcannot be inferred from its value parameters. `ACTION_TEMPLATE()` 319913481Sgiacomo.travaglini@arm.comsupports that and can be viewed as an extension to `ACTION()` and 320013481Sgiacomo.travaglini@arm.com`ACTION_P*()`. 320113481Sgiacomo.travaglini@arm.com 320213481Sgiacomo.travaglini@arm.comThe syntax: 320313481Sgiacomo.travaglini@arm.com``` 320413481Sgiacomo.travaglini@arm.comACTION_TEMPLATE(ActionName, 320513481Sgiacomo.travaglini@arm.com HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m), 320613481Sgiacomo.travaglini@arm.com AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; } 320713481Sgiacomo.travaglini@arm.com``` 320813481Sgiacomo.travaglini@arm.com 320913481Sgiacomo.travaglini@arm.comdefines an action template that takes _m_ explicit template parameters 321013481Sgiacomo.travaglini@arm.comand _n_ value parameters, where _m_ is between 1 and 10, and _n_ is 321113481Sgiacomo.travaglini@arm.combetween 0 and 10. `name_i` is the name of the i-th template 321213481Sgiacomo.travaglini@arm.comparameter, and `kind_i` specifies whether it's a `typename`, an 321313481Sgiacomo.travaglini@arm.comintegral constant, or a template. `p_i` is the name of the i-th value 321413481Sgiacomo.travaglini@arm.comparameter. 321513481Sgiacomo.travaglini@arm.com 321613481Sgiacomo.travaglini@arm.comExample: 321713481Sgiacomo.travaglini@arm.com``` 321813481Sgiacomo.travaglini@arm.com// DuplicateArg<k, T>(output) converts the k-th argument of the mock 321913481Sgiacomo.travaglini@arm.com// function to type T and copies it to *output. 322013481Sgiacomo.travaglini@arm.comACTION_TEMPLATE(DuplicateArg, 322113481Sgiacomo.travaglini@arm.com // Note the comma between int and k: 322213481Sgiacomo.travaglini@arm.com HAS_2_TEMPLATE_PARAMS(int, k, typename, T), 322313481Sgiacomo.travaglini@arm.com AND_1_VALUE_PARAMS(output)) { 322413481Sgiacomo.travaglini@arm.com *output = T(std::tr1::get<k>(args)); 322513481Sgiacomo.travaglini@arm.com} 322613481Sgiacomo.travaglini@arm.com``` 322713481Sgiacomo.travaglini@arm.com 322813481Sgiacomo.travaglini@arm.comTo create an instance of an action template, write: 322913481Sgiacomo.travaglini@arm.com``` 323013481Sgiacomo.travaglini@arm.com ActionName<t1, ..., t_m>(v1, ..., v_n) 323113481Sgiacomo.travaglini@arm.com``` 323213481Sgiacomo.travaglini@arm.comwhere the `t`s are the template arguments and the 323313481Sgiacomo.travaglini@arm.com`v`s are the value arguments. The value argument 323413481Sgiacomo.travaglini@arm.comtypes are inferred by the compiler. For example: 323513481Sgiacomo.travaglini@arm.com``` 323613481Sgiacomo.travaglini@arm.comusing ::testing::_; 323713481Sgiacomo.travaglini@arm.com... 323813481Sgiacomo.travaglini@arm.com int n; 323913481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _)) 324013481Sgiacomo.travaglini@arm.com .WillOnce(DuplicateArg<1, unsigned char>(&n)); 324113481Sgiacomo.travaglini@arm.com``` 324213481Sgiacomo.travaglini@arm.com 324313481Sgiacomo.travaglini@arm.comIf you want to explicitly specify the value argument types, you can 324413481Sgiacomo.travaglini@arm.comprovide additional template arguments: 324513481Sgiacomo.travaglini@arm.com``` 324613481Sgiacomo.travaglini@arm.com ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n) 324713481Sgiacomo.travaglini@arm.com``` 324813481Sgiacomo.travaglini@arm.comwhere `u_i` is the desired type of `v_i`. 324913481Sgiacomo.travaglini@arm.com 325013481Sgiacomo.travaglini@arm.com`ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the 325113481Sgiacomo.travaglini@arm.comnumber of value parameters, but not on the number of template 325213481Sgiacomo.travaglini@arm.comparameters. Without the restriction, the meaning of the following is 325313481Sgiacomo.travaglini@arm.comunclear: 325413481Sgiacomo.travaglini@arm.com 325513481Sgiacomo.travaglini@arm.com``` 325613481Sgiacomo.travaglini@arm.com OverloadedAction<int, bool>(x); 325713481Sgiacomo.travaglini@arm.com``` 325813481Sgiacomo.travaglini@arm.com 325913481Sgiacomo.travaglini@arm.comAre we using a single-template-parameter action where `bool` refers to 326013481Sgiacomo.travaglini@arm.comthe type of `x`, or a two-template-parameter action where the compiler 326113481Sgiacomo.travaglini@arm.comis asked to infer the type of `x`? 326213481Sgiacomo.travaglini@arm.com 326313481Sgiacomo.travaglini@arm.com## Using the ACTION Object's Type ## 326413481Sgiacomo.travaglini@arm.com 326513481Sgiacomo.travaglini@arm.comIf you are writing a function that returns an `ACTION` object, you'll 326613481Sgiacomo.travaglini@arm.comneed to know its type. The type depends on the macro used to define 326713481Sgiacomo.travaglini@arm.comthe action and the parameter types. The rule is relatively simple: 326813481Sgiacomo.travaglini@arm.com| **Given Definition** | **Expression** | **Has Type** | 326913481Sgiacomo.travaglini@arm.com|:---------------------|:---------------|:-------------| 327013481Sgiacomo.travaglini@arm.com| `ACTION(Foo)` | `Foo()` | `FooAction` | 327113481Sgiacomo.travaglini@arm.com| `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` | 327213481Sgiacomo.travaglini@arm.com| `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` | 327313481Sgiacomo.travaglini@arm.com| `ACTION_TEMPLATE(Bar, HAS_m_TEMPLATE_PARAMS(...), AND_1_VALUE_PARAMS(p1))` | `Bar<t1, ..., t_m>(int_value)` | `FooActionP<t1, ..., t_m, int>` | 327413481Sgiacomo.travaglini@arm.com| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` | 327513481Sgiacomo.travaglini@arm.com| `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>` | 327613481Sgiacomo.travaglini@arm.com| ... | ... | ... | 327713481Sgiacomo.travaglini@arm.com 327813481Sgiacomo.travaglini@arm.comNote that we have to pick different suffixes (`Action`, `ActionP`, 327913481Sgiacomo.travaglini@arm.com`ActionP2`, and etc) for actions with different numbers of value 328013481Sgiacomo.travaglini@arm.comparameters, or the action definitions cannot be overloaded on the 328113481Sgiacomo.travaglini@arm.comnumber of them. 328213481Sgiacomo.travaglini@arm.com 328313481Sgiacomo.travaglini@arm.com## Writing New Monomorphic Actions ## 328413481Sgiacomo.travaglini@arm.com 328513481Sgiacomo.travaglini@arm.comWhile the `ACTION*` macros are very convenient, sometimes they are 328613481Sgiacomo.travaglini@arm.cominappropriate. For example, despite the tricks shown in the previous 328713481Sgiacomo.travaglini@arm.comrecipes, they don't let you directly specify the types of the mock 328813481Sgiacomo.travaglini@arm.comfunction arguments and the action parameters, which in general leads 328913481Sgiacomo.travaglini@arm.comto unoptimized compiler error messages that can baffle unfamiliar 329013481Sgiacomo.travaglini@arm.comusers. They also don't allow overloading actions based on parameter 329113481Sgiacomo.travaglini@arm.comtypes without jumping through some hoops. 329213481Sgiacomo.travaglini@arm.com 329313481Sgiacomo.travaglini@arm.comAn alternative to the `ACTION*` macros is to implement 329413481Sgiacomo.travaglini@arm.com`::testing::ActionInterface<F>`, where `F` is the type of the mock 329513481Sgiacomo.travaglini@arm.comfunction in which the action will be used. For example: 329613481Sgiacomo.travaglini@arm.com 329713481Sgiacomo.travaglini@arm.com``` 329813481Sgiacomo.travaglini@arm.comtemplate <typename F>class ActionInterface { 329913481Sgiacomo.travaglini@arm.com public: 330013481Sgiacomo.travaglini@arm.com virtual ~ActionInterface(); 330113481Sgiacomo.travaglini@arm.com 330213481Sgiacomo.travaglini@arm.com // Performs the action. Result is the return type of function type 330313481Sgiacomo.travaglini@arm.com // F, and ArgumentTuple is the tuple of arguments of F. 330413481Sgiacomo.travaglini@arm.com // 330513481Sgiacomo.travaglini@arm.com // For example, if F is int(bool, const string&), then Result would 330613481Sgiacomo.travaglini@arm.com // be int, and ArgumentTuple would be tr1::tuple<bool, const string&>. 330713481Sgiacomo.travaglini@arm.com virtual Result Perform(const ArgumentTuple& args) = 0; 330813481Sgiacomo.travaglini@arm.com}; 330913481Sgiacomo.travaglini@arm.com 331013481Sgiacomo.travaglini@arm.comusing ::testing::_; 331113481Sgiacomo.travaglini@arm.comusing ::testing::Action; 331213481Sgiacomo.travaglini@arm.comusing ::testing::ActionInterface; 331313481Sgiacomo.travaglini@arm.comusing ::testing::MakeAction; 331413481Sgiacomo.travaglini@arm.com 331513481Sgiacomo.travaglini@arm.comtypedef int IncrementMethod(int*); 331613481Sgiacomo.travaglini@arm.com 331713481Sgiacomo.travaglini@arm.comclass IncrementArgumentAction : public ActionInterface<IncrementMethod> { 331813481Sgiacomo.travaglini@arm.com public: 331913481Sgiacomo.travaglini@arm.com virtual int Perform(const tr1::tuple<int*>& args) { 332013481Sgiacomo.travaglini@arm.com int* p = tr1::get<0>(args); // Grabs the first argument. 332113481Sgiacomo.travaglini@arm.com return *p++; 332213481Sgiacomo.travaglini@arm.com } 332313481Sgiacomo.travaglini@arm.com}; 332413481Sgiacomo.travaglini@arm.com 332513481Sgiacomo.travaglini@arm.comAction<IncrementMethod> IncrementArgument() { 332613481Sgiacomo.travaglini@arm.com return MakeAction(new IncrementArgumentAction); 332713481Sgiacomo.travaglini@arm.com} 332813481Sgiacomo.travaglini@arm.com... 332913481Sgiacomo.travaglini@arm.com 333013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Baz(_)) 333113481Sgiacomo.travaglini@arm.com .WillOnce(IncrementArgument()); 333213481Sgiacomo.travaglini@arm.com 333313481Sgiacomo.travaglini@arm.com int n = 5; 333413481Sgiacomo.travaglini@arm.com foo.Baz(&n); // Should return 5 and change n to 6. 333513481Sgiacomo.travaglini@arm.com``` 333613481Sgiacomo.travaglini@arm.com 333713481Sgiacomo.travaglini@arm.com## Writing New Polymorphic Actions ## 333813481Sgiacomo.travaglini@arm.com 333913481Sgiacomo.travaglini@arm.comThe previous recipe showed you how to define your own action. This is 334013481Sgiacomo.travaglini@arm.comall good, except that you need to know the type of the function in 334113481Sgiacomo.travaglini@arm.comwhich the action will be used. Sometimes that can be a problem. For 334213481Sgiacomo.travaglini@arm.comexample, if you want to use the action in functions with _different_ 334313481Sgiacomo.travaglini@arm.comtypes (e.g. like `Return()` and `SetArgPointee()`). 334413481Sgiacomo.travaglini@arm.com 334513481Sgiacomo.travaglini@arm.comIf an action can be used in several types of mock functions, we say 334613481Sgiacomo.travaglini@arm.comit's _polymorphic_. The `MakePolymorphicAction()` function template 334713481Sgiacomo.travaglini@arm.commakes it easy to define such an action: 334813481Sgiacomo.travaglini@arm.com 334913481Sgiacomo.travaglini@arm.com``` 335013481Sgiacomo.travaglini@arm.comnamespace testing { 335113481Sgiacomo.travaglini@arm.com 335213481Sgiacomo.travaglini@arm.comtemplate <typename Impl> 335313481Sgiacomo.travaglini@arm.comPolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl); 335413481Sgiacomo.travaglini@arm.com 335513481Sgiacomo.travaglini@arm.com} // namespace testing 335613481Sgiacomo.travaglini@arm.com``` 335713481Sgiacomo.travaglini@arm.com 335813481Sgiacomo.travaglini@arm.comAs an example, let's define an action that returns the second argument 335913481Sgiacomo.travaglini@arm.comin the mock function's argument list. The first step is to define an 336013481Sgiacomo.travaglini@arm.comimplementation class: 336113481Sgiacomo.travaglini@arm.com 336213481Sgiacomo.travaglini@arm.com``` 336313481Sgiacomo.travaglini@arm.comclass ReturnSecondArgumentAction { 336413481Sgiacomo.travaglini@arm.com public: 336513481Sgiacomo.travaglini@arm.com template <typename Result, typename ArgumentTuple> 336613481Sgiacomo.travaglini@arm.com Result Perform(const ArgumentTuple& args) const { 336713481Sgiacomo.travaglini@arm.com // To get the i-th (0-based) argument, use tr1::get<i>(args). 336813481Sgiacomo.travaglini@arm.com return tr1::get<1>(args); 336913481Sgiacomo.travaglini@arm.com } 337013481Sgiacomo.travaglini@arm.com}; 337113481Sgiacomo.travaglini@arm.com``` 337213481Sgiacomo.travaglini@arm.com 337313481Sgiacomo.travaglini@arm.comThis implementation class does _not_ need to inherit from any 337413481Sgiacomo.travaglini@arm.comparticular class. What matters is that it must have a `Perform()` 337513481Sgiacomo.travaglini@arm.commethod template. This method template takes the mock function's 337613481Sgiacomo.travaglini@arm.comarguments as a tuple in a **single** argument, and returns the result of 337713481Sgiacomo.travaglini@arm.comthe action. It can be either `const` or not, but must be invokable 337813481Sgiacomo.travaglini@arm.comwith exactly one template argument, which is the result type. In other 337913481Sgiacomo.travaglini@arm.comwords, you must be able to call `Perform<R>(args)` where `R` is the 338013481Sgiacomo.travaglini@arm.commock function's return type and `args` is its arguments in a tuple. 338113481Sgiacomo.travaglini@arm.com 338213481Sgiacomo.travaglini@arm.comNext, we use `MakePolymorphicAction()` to turn an instance of the 338313481Sgiacomo.travaglini@arm.comimplementation class into the polymorphic action we need. It will be 338413481Sgiacomo.travaglini@arm.comconvenient to have a wrapper for this: 338513481Sgiacomo.travaglini@arm.com 338613481Sgiacomo.travaglini@arm.com``` 338713481Sgiacomo.travaglini@arm.comusing ::testing::MakePolymorphicAction; 338813481Sgiacomo.travaglini@arm.comusing ::testing::PolymorphicAction; 338913481Sgiacomo.travaglini@arm.com 339013481Sgiacomo.travaglini@arm.comPolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() { 339113481Sgiacomo.travaglini@arm.com return MakePolymorphicAction(ReturnSecondArgumentAction()); 339213481Sgiacomo.travaglini@arm.com} 339313481Sgiacomo.travaglini@arm.com``` 339413481Sgiacomo.travaglini@arm.com 339513481Sgiacomo.travaglini@arm.comNow, you can use this polymorphic action the same way you use the 339613481Sgiacomo.travaglini@arm.combuilt-in ones: 339713481Sgiacomo.travaglini@arm.com 339813481Sgiacomo.travaglini@arm.com``` 339913481Sgiacomo.travaglini@arm.comusing ::testing::_; 340013481Sgiacomo.travaglini@arm.com 340113481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 340213481Sgiacomo.travaglini@arm.com public: 340313481Sgiacomo.travaglini@arm.com MOCK_METHOD2(DoThis, int(bool flag, int n)); 340413481Sgiacomo.travaglini@arm.com MOCK_METHOD3(DoThat, string(int x, const char* str1, const char* str2)); 340513481Sgiacomo.travaglini@arm.com}; 340613481Sgiacomo.travaglini@arm.com... 340713481Sgiacomo.travaglini@arm.com 340813481Sgiacomo.travaglini@arm.com MockFoo foo; 340913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(_, _)) 341013481Sgiacomo.travaglini@arm.com .WillOnce(ReturnSecondArgument()); 341113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat(_, _, _)) 341213481Sgiacomo.travaglini@arm.com .WillOnce(ReturnSecondArgument()); 341313481Sgiacomo.travaglini@arm.com ... 341413481Sgiacomo.travaglini@arm.com foo.DoThis(true, 5); // Will return 5. 341513481Sgiacomo.travaglini@arm.com foo.DoThat(1, "Hi", "Bye"); // Will return "Hi". 341613481Sgiacomo.travaglini@arm.com``` 341713481Sgiacomo.travaglini@arm.com 341813481Sgiacomo.travaglini@arm.com## Teaching Google Mock How to Print Your Values ## 341913481Sgiacomo.travaglini@arm.com 342013481Sgiacomo.travaglini@arm.comWhen an uninteresting or unexpected call occurs, Google Mock prints the 342113481Sgiacomo.travaglini@arm.comargument values and the stack trace to help you debug. Assertion 342213481Sgiacomo.travaglini@arm.commacros like `EXPECT_THAT` and `EXPECT_EQ` also print the values in 342313481Sgiacomo.travaglini@arm.comquestion when the assertion fails. Google Mock and Google Test do this using 342413481Sgiacomo.travaglini@arm.comGoogle Test's user-extensible value printer. 342513481Sgiacomo.travaglini@arm.com 342613481Sgiacomo.travaglini@arm.comThis printer knows how to print built-in C++ types, native arrays, STL 342713481Sgiacomo.travaglini@arm.comcontainers, and any type that supports the `<<` operator. For other 342813481Sgiacomo.travaglini@arm.comtypes, it prints the raw bytes in the value and hopes that you the 342913481Sgiacomo.travaglini@arm.comuser can figure it out. 343013481Sgiacomo.travaglini@arm.com[Google Test's advanced guide](http://code.google.com/p/googletest/wiki/AdvancedGuide#Teaching_Google_Test_How_to_Print_Your_Values) 343113481Sgiacomo.travaglini@arm.comexplains how to extend the printer to do a better job at 343213481Sgiacomo.travaglini@arm.comprinting your particular type than to dump the bytes.