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