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_5_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.comagainst `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_5_CheatSheet.md) for 87413481Sgiacomo.travaglini@arm.comthe complete list. 87513481Sgiacomo.travaglini@arm.com 87613481Sgiacomo.travaglini@arm.com## Using Matchers as Predicates ## 87713481Sgiacomo.travaglini@arm.com 87813481Sgiacomo.travaglini@arm.comHave you noticed that a matcher is just a fancy predicate that also 87913481Sgiacomo.travaglini@arm.comknows how to describe itself? Many existing algorithms take predicates 88013481Sgiacomo.travaglini@arm.comas arguments (e.g. those defined in STL's `<algorithm>` header), and 88113481Sgiacomo.travaglini@arm.comit would be a shame if Google Mock matchers are not allowed to 88213481Sgiacomo.travaglini@arm.comparticipate. 88313481Sgiacomo.travaglini@arm.com 88413481Sgiacomo.travaglini@arm.comLuckily, you can use a matcher where a unary predicate functor is 88513481Sgiacomo.travaglini@arm.comexpected by wrapping it inside the `Matches()` function. For example, 88613481Sgiacomo.travaglini@arm.com 88713481Sgiacomo.travaglini@arm.com``` 88813481Sgiacomo.travaglini@arm.com#include <algorithm> 88913481Sgiacomo.travaglini@arm.com#include <vector> 89013481Sgiacomo.travaglini@arm.com 89113481Sgiacomo.travaglini@arm.comstd::vector<int> v; 89213481Sgiacomo.travaglini@arm.com... 89313481Sgiacomo.travaglini@arm.com// How many elements in v are >= 10? 89413481Sgiacomo.travaglini@arm.comconst int count = count_if(v.begin(), v.end(), Matches(Ge(10))); 89513481Sgiacomo.travaglini@arm.com``` 89613481Sgiacomo.travaglini@arm.com 89713481Sgiacomo.travaglini@arm.comSince you can build complex matchers from simpler ones easily using 89813481Sgiacomo.travaglini@arm.comGoogle Mock, this gives you a way to conveniently construct composite 89913481Sgiacomo.travaglini@arm.compredicates (doing the same using STL's `<functional>` header is just 90013481Sgiacomo.travaglini@arm.compainful). For example, here's a predicate that's satisfied by any 90113481Sgiacomo.travaglini@arm.comnumber that is >= 0, <= 100, and != 50: 90213481Sgiacomo.travaglini@arm.com 90313481Sgiacomo.travaglini@arm.com``` 90413481Sgiacomo.travaglini@arm.comMatches(AllOf(Ge(0), Le(100), Ne(50))) 90513481Sgiacomo.travaglini@arm.com``` 90613481Sgiacomo.travaglini@arm.com 90713481Sgiacomo.travaglini@arm.com## Using Matchers in Google Test Assertions ## 90813481Sgiacomo.travaglini@arm.com 90913481Sgiacomo.travaglini@arm.comSince matchers are basically predicates that also know how to describe 91013481Sgiacomo.travaglini@arm.comthemselves, there is a way to take advantage of them in 91113481Sgiacomo.travaglini@arm.com[Google Test](http://code.google.com/p/googletest/) assertions. It's 91213481Sgiacomo.travaglini@arm.comcalled `ASSERT_THAT` and `EXPECT_THAT`: 91313481Sgiacomo.travaglini@arm.com 91413481Sgiacomo.travaglini@arm.com``` 91513481Sgiacomo.travaglini@arm.com ASSERT_THAT(value, matcher); // Asserts that value matches matcher. 91613481Sgiacomo.travaglini@arm.com EXPECT_THAT(value, matcher); // The non-fatal version. 91713481Sgiacomo.travaglini@arm.com``` 91813481Sgiacomo.travaglini@arm.com 91913481Sgiacomo.travaglini@arm.comFor example, in a Google Test test you can write: 92013481Sgiacomo.travaglini@arm.com 92113481Sgiacomo.travaglini@arm.com``` 92213481Sgiacomo.travaglini@arm.com#include <gmock/gmock.h> 92313481Sgiacomo.travaglini@arm.com 92413481Sgiacomo.travaglini@arm.comusing ::testing::AllOf; 92513481Sgiacomo.travaglini@arm.comusing ::testing::Ge; 92613481Sgiacomo.travaglini@arm.comusing ::testing::Le; 92713481Sgiacomo.travaglini@arm.comusing ::testing::MatchesRegex; 92813481Sgiacomo.travaglini@arm.comusing ::testing::StartsWith; 92913481Sgiacomo.travaglini@arm.com... 93013481Sgiacomo.travaglini@arm.com 93113481Sgiacomo.travaglini@arm.com EXPECT_THAT(Foo(), StartsWith("Hello")); 93213481Sgiacomo.travaglini@arm.com EXPECT_THAT(Bar(), MatchesRegex("Line \\d+")); 93313481Sgiacomo.travaglini@arm.com ASSERT_THAT(Baz(), AllOf(Ge(5), Le(10))); 93413481Sgiacomo.travaglini@arm.com``` 93513481Sgiacomo.travaglini@arm.com 93613481Sgiacomo.travaglini@arm.comwhich (as you can probably guess) executes `Foo()`, `Bar()`, and 93713481Sgiacomo.travaglini@arm.com`Baz()`, and verifies that: 93813481Sgiacomo.travaglini@arm.com 93913481Sgiacomo.travaglini@arm.com * `Foo()` returns a string that starts with `"Hello"`. 94013481Sgiacomo.travaglini@arm.com * `Bar()` returns a string that matches regular expression `"Line \\d+"`. 94113481Sgiacomo.travaglini@arm.com * `Baz()` returns a number in the range [5, 10]. 94213481Sgiacomo.travaglini@arm.com 94313481Sgiacomo.travaglini@arm.comThe nice thing about these macros is that _they read like 94413481Sgiacomo.travaglini@arm.comEnglish_. They generate informative messages too. For example, if the 94513481Sgiacomo.travaglini@arm.comfirst `EXPECT_THAT()` above fails, the message will be something like: 94613481Sgiacomo.travaglini@arm.com 94713481Sgiacomo.travaglini@arm.com``` 94813481Sgiacomo.travaglini@arm.comValue of: Foo() 94913481Sgiacomo.travaglini@arm.com Actual: "Hi, world!" 95013481Sgiacomo.travaglini@arm.comExpected: starts with "Hello" 95113481Sgiacomo.travaglini@arm.com``` 95213481Sgiacomo.travaglini@arm.com 95313481Sgiacomo.travaglini@arm.com**Credit:** The idea of `(ASSERT|EXPECT)_THAT` was stolen from the 95413481Sgiacomo.travaglini@arm.com[Hamcrest](http://code.google.com/p/hamcrest/) project, which adds 95513481Sgiacomo.travaglini@arm.com`assertThat()` to JUnit. 95613481Sgiacomo.travaglini@arm.com 95713481Sgiacomo.travaglini@arm.com## Using Predicates as Matchers ## 95813481Sgiacomo.travaglini@arm.com 95913481Sgiacomo.travaglini@arm.comGoogle Mock provides a built-in set of matchers. In case you find them 96013481Sgiacomo.travaglini@arm.comlacking, you can use an arbitray unary predicate function or functor 96113481Sgiacomo.travaglini@arm.comas a matcher - as long as the predicate accepts a value of the type 96213481Sgiacomo.travaglini@arm.comyou want. You do this by wrapping the predicate inside the `Truly()` 96313481Sgiacomo.travaglini@arm.comfunction, for example: 96413481Sgiacomo.travaglini@arm.com 96513481Sgiacomo.travaglini@arm.com``` 96613481Sgiacomo.travaglini@arm.comusing ::testing::Truly; 96713481Sgiacomo.travaglini@arm.com 96813481Sgiacomo.travaglini@arm.comint IsEven(int n) { return (n % 2) == 0 ? 1 : 0; } 96913481Sgiacomo.travaglini@arm.com... 97013481Sgiacomo.travaglini@arm.com 97113481Sgiacomo.travaglini@arm.com // Bar() must be called with an even number. 97213481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(Truly(IsEven))); 97313481Sgiacomo.travaglini@arm.com``` 97413481Sgiacomo.travaglini@arm.com 97513481Sgiacomo.travaglini@arm.comNote that the predicate function / functor doesn't have to return 97613481Sgiacomo.travaglini@arm.com`bool`. It works as long as the return value can be used as the 97713481Sgiacomo.travaglini@arm.comcondition in statement `if (condition) ...`. 97813481Sgiacomo.travaglini@arm.com 97913481Sgiacomo.travaglini@arm.com## Matching Arguments that Are Not Copyable ## 98013481Sgiacomo.travaglini@arm.com 98113481Sgiacomo.travaglini@arm.comWhen you do an `EXPECT_CALL(mock_obj, Foo(bar))`, Google Mock saves 98213481Sgiacomo.travaglini@arm.comaway a copy of `bar`. When `Foo()` is called later, Google Mock 98313481Sgiacomo.travaglini@arm.comcompares the argument to `Foo()` with the saved copy of `bar`. This 98413481Sgiacomo.travaglini@arm.comway, you don't need to worry about `bar` being modified or destroyed 98513481Sgiacomo.travaglini@arm.comafter the `EXPECT_CALL()` is executed. The same is true when you use 98613481Sgiacomo.travaglini@arm.commatchers like `Eq(bar)`, `Le(bar)`, and so on. 98713481Sgiacomo.travaglini@arm.com 98813481Sgiacomo.travaglini@arm.comBut what if `bar` cannot be copied (i.e. has no copy constructor)? You 98913481Sgiacomo.travaglini@arm.comcould define your own matcher function and use it with `Truly()`, as 99013481Sgiacomo.travaglini@arm.comthe previous couple of recipes have shown. Or, you may be able to get 99113481Sgiacomo.travaglini@arm.comaway from it if you can guarantee that `bar` won't be changed after 99213481Sgiacomo.travaglini@arm.comthe `EXPECT_CALL()` is executed. Just tell Google Mock that it should 99313481Sgiacomo.travaglini@arm.comsave a reference to `bar`, instead of a copy of it. Here's how: 99413481Sgiacomo.travaglini@arm.com 99513481Sgiacomo.travaglini@arm.com``` 99613481Sgiacomo.travaglini@arm.comusing ::testing::Eq; 99713481Sgiacomo.travaglini@arm.comusing ::testing::ByRef; 99813481Sgiacomo.travaglini@arm.comusing ::testing::Lt; 99913481Sgiacomo.travaglini@arm.com... 100013481Sgiacomo.travaglini@arm.com // Expects that Foo()'s argument == bar. 100113481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_obj, Foo(Eq(ByRef(bar)))); 100213481Sgiacomo.travaglini@arm.com 100313481Sgiacomo.travaglini@arm.com // Expects that Foo()'s argument < bar. 100413481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_obj, Foo(Lt(ByRef(bar)))); 100513481Sgiacomo.travaglini@arm.com``` 100613481Sgiacomo.travaglini@arm.com 100713481Sgiacomo.travaglini@arm.comRemember: if you do this, don't change `bar` after the 100813481Sgiacomo.travaglini@arm.com`EXPECT_CALL()`, or the result is undefined. 100913481Sgiacomo.travaglini@arm.com 101013481Sgiacomo.travaglini@arm.com## Validating a Member of an Object ## 101113481Sgiacomo.travaglini@arm.com 101213481Sgiacomo.travaglini@arm.comOften a mock function takes a reference to object as an argument. When 101313481Sgiacomo.travaglini@arm.commatching the argument, you may not want to compare the entire object 101413481Sgiacomo.travaglini@arm.comagainst a fixed object, as that may be over-specification. Instead, 101513481Sgiacomo.travaglini@arm.comyou may need to validate a certain member variable or the result of a 101613481Sgiacomo.travaglini@arm.comcertain getter method of the object. You can do this with `Field()` 101713481Sgiacomo.travaglini@arm.comand `Property()`. More specifically, 101813481Sgiacomo.travaglini@arm.com 101913481Sgiacomo.travaglini@arm.com``` 102013481Sgiacomo.travaglini@arm.comField(&Foo::bar, m) 102113481Sgiacomo.travaglini@arm.com``` 102213481Sgiacomo.travaglini@arm.com 102313481Sgiacomo.travaglini@arm.comis a matcher that matches a `Foo` object whose `bar` member variable 102413481Sgiacomo.travaglini@arm.comsatisfies matcher `m`. 102513481Sgiacomo.travaglini@arm.com 102613481Sgiacomo.travaglini@arm.com``` 102713481Sgiacomo.travaglini@arm.comProperty(&Foo::baz, m) 102813481Sgiacomo.travaglini@arm.com``` 102913481Sgiacomo.travaglini@arm.com 103013481Sgiacomo.travaglini@arm.comis a matcher that matches a `Foo` object whose `baz()` method returns 103113481Sgiacomo.travaglini@arm.coma value that satisfies matcher `m`. 103213481Sgiacomo.travaglini@arm.com 103313481Sgiacomo.travaglini@arm.comFor example: 103413481Sgiacomo.travaglini@arm.com 103513481Sgiacomo.travaglini@arm.com> | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. | 103613481Sgiacomo.travaglini@arm.com|:-----------------------------|:-----------------------------------| 103713481Sgiacomo.travaglini@arm.com> | `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. | 103813481Sgiacomo.travaglini@arm.com 103913481Sgiacomo.travaglini@arm.comNote that in `Property(&Foo::baz, ...)`, method `baz()` must take no 104013481Sgiacomo.travaglini@arm.comargument and be declared as `const`. 104113481Sgiacomo.travaglini@arm.com 104213481Sgiacomo.travaglini@arm.comBTW, `Field()` and `Property()` can also match plain pointers to 104313481Sgiacomo.travaglini@arm.comobjects. For instance, 104413481Sgiacomo.travaglini@arm.com 104513481Sgiacomo.travaglini@arm.com``` 104613481Sgiacomo.travaglini@arm.comField(&Foo::number, Ge(3)) 104713481Sgiacomo.travaglini@arm.com``` 104813481Sgiacomo.travaglini@arm.com 104913481Sgiacomo.travaglini@arm.commatches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, 105013481Sgiacomo.travaglini@arm.comthe match will always fail regardless of the inner matcher. 105113481Sgiacomo.travaglini@arm.com 105213481Sgiacomo.travaglini@arm.comWhat if you want to validate more than one members at the same time? 105313481Sgiacomo.travaglini@arm.comRemember that there is `AllOf()`. 105413481Sgiacomo.travaglini@arm.com 105513481Sgiacomo.travaglini@arm.com## Validating the Value Pointed to by a Pointer Argument ## 105613481Sgiacomo.travaglini@arm.com 105713481Sgiacomo.travaglini@arm.comC++ functions often take pointers as arguments. You can use matchers 105813481Sgiacomo.travaglini@arm.comlike `NULL`, `NotNull()`, and other comparison matchers to match a 105913481Sgiacomo.travaglini@arm.compointer, but what if you want to make sure the value _pointed to_ by 106013481Sgiacomo.travaglini@arm.comthe pointer, instead of the pointer itself, has a certain property? 106113481Sgiacomo.travaglini@arm.comWell, you can use the `Pointee(m)` matcher. 106213481Sgiacomo.travaglini@arm.com 106313481Sgiacomo.travaglini@arm.com`Pointee(m)` matches a pointer iff `m` matches the value the pointer 106413481Sgiacomo.travaglini@arm.compoints to. For example: 106513481Sgiacomo.travaglini@arm.com 106613481Sgiacomo.travaglini@arm.com``` 106713481Sgiacomo.travaglini@arm.comusing ::testing::Ge; 106813481Sgiacomo.travaglini@arm.comusing ::testing::Pointee; 106913481Sgiacomo.travaglini@arm.com... 107013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(Pointee(Ge(3)))); 107113481Sgiacomo.travaglini@arm.com``` 107213481Sgiacomo.travaglini@arm.com 107313481Sgiacomo.travaglini@arm.comexpects `foo.Bar()` to be called with a pointer that points to a value 107413481Sgiacomo.travaglini@arm.comgreater than or equal to 3. 107513481Sgiacomo.travaglini@arm.com 107613481Sgiacomo.travaglini@arm.comOne nice thing about `Pointee()` is that it treats a `NULL` pointer as 107713481Sgiacomo.travaglini@arm.coma match failure, so you can write `Pointee(m)` instead of 107813481Sgiacomo.travaglini@arm.com 107913481Sgiacomo.travaglini@arm.com``` 108013481Sgiacomo.travaglini@arm.com AllOf(NotNull(), Pointee(m)) 108113481Sgiacomo.travaglini@arm.com``` 108213481Sgiacomo.travaglini@arm.com 108313481Sgiacomo.travaglini@arm.comwithout worrying that a `NULL` pointer will crash your test. 108413481Sgiacomo.travaglini@arm.com 108513481Sgiacomo.travaglini@arm.comAlso, did we tell you that `Pointee()` works with both raw pointers 108613481Sgiacomo.travaglini@arm.com**and** smart pointers (`linked_ptr`, `shared_ptr`, `scoped_ptr`, and 108713481Sgiacomo.travaglini@arm.cometc)? 108813481Sgiacomo.travaglini@arm.com 108913481Sgiacomo.travaglini@arm.comWhat if you have a pointer to pointer? You guessed it - you can use 109013481Sgiacomo.travaglini@arm.comnested `Pointee()` to probe deeper inside the value. For example, 109113481Sgiacomo.travaglini@arm.com`Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer 109213481Sgiacomo.travaglini@arm.comthat points to a number less than 3 (what a mouthful...). 109313481Sgiacomo.travaglini@arm.com 109413481Sgiacomo.travaglini@arm.com## Testing a Certain Property of an Object ## 109513481Sgiacomo.travaglini@arm.com 109613481Sgiacomo.travaglini@arm.comSometimes you want to specify that an object argument has a certain 109713481Sgiacomo.travaglini@arm.comproperty, but there is no existing matcher that does this. If you want 109813481Sgiacomo.travaglini@arm.comgood error messages, you should define a matcher. If you want to do it 109913481Sgiacomo.travaglini@arm.comquick and dirty, you could get away with writing an ordinary function. 110013481Sgiacomo.travaglini@arm.com 110113481Sgiacomo.travaglini@arm.comLet's say you have a mock function that takes an object of type `Foo`, 110213481Sgiacomo.travaglini@arm.comwhich has an `int bar()` method and an `int baz()` method, and you 110313481Sgiacomo.travaglini@arm.comwant to constrain that the argument's `bar()` value plus its `baz()` 110413481Sgiacomo.travaglini@arm.comvalue is a given number. Here's how you can define a matcher to do it: 110513481Sgiacomo.travaglini@arm.com 110613481Sgiacomo.travaglini@arm.com``` 110713481Sgiacomo.travaglini@arm.comusing ::testing::MatcherInterface; 110813481Sgiacomo.travaglini@arm.comusing ::testing::MatchResultListener; 110913481Sgiacomo.travaglini@arm.com 111013481Sgiacomo.travaglini@arm.comclass BarPlusBazEqMatcher : public MatcherInterface<const Foo&> { 111113481Sgiacomo.travaglini@arm.com public: 111213481Sgiacomo.travaglini@arm.com explicit BarPlusBazEqMatcher(int expected_sum) 111313481Sgiacomo.travaglini@arm.com : expected_sum_(expected_sum) {} 111413481Sgiacomo.travaglini@arm.com 111513481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(const Foo& foo, 111613481Sgiacomo.travaglini@arm.com MatchResultListener* listener) const { 111713481Sgiacomo.travaglini@arm.com return (foo.bar() + foo.baz()) == expected_sum_; 111813481Sgiacomo.travaglini@arm.com } 111913481Sgiacomo.travaglini@arm.com 112013481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const { 112113481Sgiacomo.travaglini@arm.com *os << "bar() + baz() equals " << expected_sum_; 112213481Sgiacomo.travaglini@arm.com } 112313481Sgiacomo.travaglini@arm.com 112413481Sgiacomo.travaglini@arm.com virtual void DescribeNegationTo(::std::ostream* os) const { 112513481Sgiacomo.travaglini@arm.com *os << "bar() + baz() does not equal " << expected_sum_; 112613481Sgiacomo.travaglini@arm.com } 112713481Sgiacomo.travaglini@arm.com private: 112813481Sgiacomo.travaglini@arm.com const int expected_sum_; 112913481Sgiacomo.travaglini@arm.com}; 113013481Sgiacomo.travaglini@arm.com 113113481Sgiacomo.travaglini@arm.cominline Matcher<const Foo&> BarPlusBazEq(int expected_sum) { 113213481Sgiacomo.travaglini@arm.com return MakeMatcher(new BarPlusBazEqMatcher(expected_sum)); 113313481Sgiacomo.travaglini@arm.com} 113413481Sgiacomo.travaglini@arm.com 113513481Sgiacomo.travaglini@arm.com... 113613481Sgiacomo.travaglini@arm.com 113713481Sgiacomo.travaglini@arm.com EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...; 113813481Sgiacomo.travaglini@arm.com``` 113913481Sgiacomo.travaglini@arm.com 114013481Sgiacomo.travaglini@arm.com## Matching Containers ## 114113481Sgiacomo.travaglini@arm.com 114213481Sgiacomo.travaglini@arm.comSometimes an STL container (e.g. list, vector, map, ...) is passed to 114313481Sgiacomo.travaglini@arm.coma mock function and you may want to validate it. Since most STL 114413481Sgiacomo.travaglini@arm.comcontainers support the `==` operator, you can write 114513481Sgiacomo.travaglini@arm.com`Eq(expected_container)` or simply `expected_container` to match a 114613481Sgiacomo.travaglini@arm.comcontainer exactly. 114713481Sgiacomo.travaglini@arm.com 114813481Sgiacomo.travaglini@arm.comSometimes, though, you may want to be more flexible (for example, the 114913481Sgiacomo.travaglini@arm.comfirst element must be an exact match, but the second element can be 115013481Sgiacomo.travaglini@arm.comany positive number, and so on). Also, containers used in tests often 115113481Sgiacomo.travaglini@arm.comhave a small number of elements, and having to define the expected 115213481Sgiacomo.travaglini@arm.comcontainer out-of-line is a bit of a hassle. 115313481Sgiacomo.travaglini@arm.com 115413481Sgiacomo.travaglini@arm.comYou can use the `ElementsAre()` matcher in such cases: 115513481Sgiacomo.travaglini@arm.com 115613481Sgiacomo.travaglini@arm.com``` 115713481Sgiacomo.travaglini@arm.comusing ::testing::_; 115813481Sgiacomo.travaglini@arm.comusing ::testing::ElementsAre; 115913481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 116013481Sgiacomo.travaglini@arm.com... 116113481Sgiacomo.travaglini@arm.com 116213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Foo, void(const vector<int>& numbers)); 116313481Sgiacomo.travaglini@arm.com... 116413481Sgiacomo.travaglini@arm.com 116513481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5))); 116613481Sgiacomo.travaglini@arm.com``` 116713481Sgiacomo.travaglini@arm.com 116813481Sgiacomo.travaglini@arm.comThe above matcher says that the container must have 4 elements, which 116913481Sgiacomo.travaglini@arm.commust be 1, greater than 0, anything, and 5 respectively. 117013481Sgiacomo.travaglini@arm.com 117113481Sgiacomo.travaglini@arm.com`ElementsAre()` is overloaded to take 0 to 10 arguments. If more are 117213481Sgiacomo.travaglini@arm.comneeded, you can place them in a C-style array and use 117313481Sgiacomo.travaglini@arm.com`ElementsAreArray()` instead: 117413481Sgiacomo.travaglini@arm.com 117513481Sgiacomo.travaglini@arm.com``` 117613481Sgiacomo.travaglini@arm.comusing ::testing::ElementsAreArray; 117713481Sgiacomo.travaglini@arm.com... 117813481Sgiacomo.travaglini@arm.com 117913481Sgiacomo.travaglini@arm.com // ElementsAreArray accepts an array of element values. 118013481Sgiacomo.travaglini@arm.com const int expected_vector1[] = { 1, 5, 2, 4, ... }; 118113481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1))); 118213481Sgiacomo.travaglini@arm.com 118313481Sgiacomo.travaglini@arm.com // Or, an array of element matchers. 118413481Sgiacomo.travaglini@arm.com Matcher<int> expected_vector2 = { 1, Gt(2), _, 3, ... }; 118513481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2))); 118613481Sgiacomo.travaglini@arm.com``` 118713481Sgiacomo.travaglini@arm.com 118813481Sgiacomo.travaglini@arm.comIn case the array needs to be dynamically created (and therefore the 118913481Sgiacomo.travaglini@arm.comarray size cannot be inferred by the compiler), you can give 119013481Sgiacomo.travaglini@arm.com`ElementsAreArray()` an additional argument to specify the array size: 119113481Sgiacomo.travaglini@arm.com 119213481Sgiacomo.travaglini@arm.com``` 119313481Sgiacomo.travaglini@arm.comusing ::testing::ElementsAreArray; 119413481Sgiacomo.travaglini@arm.com... 119513481Sgiacomo.travaglini@arm.com int* const expected_vector3 = new int[count]; 119613481Sgiacomo.travaglini@arm.com ... fill expected_vector3 with values ... 119713481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count))); 119813481Sgiacomo.travaglini@arm.com``` 119913481Sgiacomo.travaglini@arm.com 120013481Sgiacomo.travaglini@arm.com**Tips:** 120113481Sgiacomo.travaglini@arm.com 120213481Sgiacomo.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. 120313481Sgiacomo.travaglini@arm.com * You can use nested `ElementAre*()` to match nested (multi-dimensional) containers. 120413481Sgiacomo.travaglini@arm.com * If the container is passed by pointer instead of by reference, just write `Pointee(ElementsAre*(...))`. 120513481Sgiacomo.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`). 120613481Sgiacomo.travaglini@arm.com 120713481Sgiacomo.travaglini@arm.com## Sharing Matchers ## 120813481Sgiacomo.travaglini@arm.com 120913481Sgiacomo.travaglini@arm.comUnder the hood, a Google Mock matcher object consists of a pointer to 121013481Sgiacomo.travaglini@arm.coma ref-counted implementation object. Copying matchers is allowed and 121113481Sgiacomo.travaglini@arm.comvery efficient, as only the pointer is copied. When the last matcher 121213481Sgiacomo.travaglini@arm.comthat references the implementation object dies, the implementation 121313481Sgiacomo.travaglini@arm.comobject will be deleted. 121413481Sgiacomo.travaglini@arm.com 121513481Sgiacomo.travaglini@arm.comTherefore, if you have some complex matcher that you want to use again 121613481Sgiacomo.travaglini@arm.comand again, there is no need to build it everytime. Just assign it to a 121713481Sgiacomo.travaglini@arm.commatcher variable and use that variable repeatedly! For example, 121813481Sgiacomo.travaglini@arm.com 121913481Sgiacomo.travaglini@arm.com``` 122013481Sgiacomo.travaglini@arm.com Matcher<int> in_range = AllOf(Gt(5), Le(10)); 122113481Sgiacomo.travaglini@arm.com ... use in_range as a matcher in multiple EXPECT_CALLs ... 122213481Sgiacomo.travaglini@arm.com``` 122313481Sgiacomo.travaglini@arm.com 122413481Sgiacomo.travaglini@arm.com# Setting Expectations # 122513481Sgiacomo.travaglini@arm.com 122613481Sgiacomo.travaglini@arm.com## Ignoring Uninteresting Calls ## 122713481Sgiacomo.travaglini@arm.com 122813481Sgiacomo.travaglini@arm.comIf you are not interested in how a mock method is called, just don't 122913481Sgiacomo.travaglini@arm.comsay anything about it. In this case, if the method is ever called, 123013481Sgiacomo.travaglini@arm.comGoogle Mock will perform its default action to allow the test program 123113481Sgiacomo.travaglini@arm.comto continue. If you are not happy with the default action taken by 123213481Sgiacomo.travaglini@arm.comGoogle Mock, you can override it using `DefaultValue<T>::Set()` 123313481Sgiacomo.travaglini@arm.com(described later in this document) or `ON_CALL()`. 123413481Sgiacomo.travaglini@arm.com 123513481Sgiacomo.travaglini@arm.comPlease note that once you expressed interest in a particular mock 123613481Sgiacomo.travaglini@arm.commethod (via `EXPECT_CALL()`), all invocations to it must match some 123713481Sgiacomo.travaglini@arm.comexpectation. If this function is called but the arguments don't match 123813481Sgiacomo.travaglini@arm.comany `EXPECT_CALL()` statement, it will be an error. 123913481Sgiacomo.travaglini@arm.com 124013481Sgiacomo.travaglini@arm.com## Disallowing Unexpected Calls ## 124113481Sgiacomo.travaglini@arm.com 124213481Sgiacomo.travaglini@arm.comIf a mock method shouldn't be called at all, explicitly say so: 124313481Sgiacomo.travaglini@arm.com 124413481Sgiacomo.travaglini@arm.com``` 124513481Sgiacomo.travaglini@arm.comusing ::testing::_; 124613481Sgiacomo.travaglini@arm.com... 124713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(_)) 124813481Sgiacomo.travaglini@arm.com .Times(0); 124913481Sgiacomo.travaglini@arm.com``` 125013481Sgiacomo.travaglini@arm.com 125113481Sgiacomo.travaglini@arm.comIf some calls to the method are allowed, but the rest are not, just 125213481Sgiacomo.travaglini@arm.comlist all the expected calls: 125313481Sgiacomo.travaglini@arm.com 125413481Sgiacomo.travaglini@arm.com``` 125513481Sgiacomo.travaglini@arm.comusing ::testing::AnyNumber; 125613481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 125713481Sgiacomo.travaglini@arm.com... 125813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(5)); 125913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(Gt(10))) 126013481Sgiacomo.travaglini@arm.com .Times(AnyNumber()); 126113481Sgiacomo.travaglini@arm.com``` 126213481Sgiacomo.travaglini@arm.com 126313481Sgiacomo.travaglini@arm.comA call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` 126413481Sgiacomo.travaglini@arm.comstatements will be an error. 126513481Sgiacomo.travaglini@arm.com 126613481Sgiacomo.travaglini@arm.com## Expecting Ordered Calls ## 126713481Sgiacomo.travaglini@arm.com 126813481Sgiacomo.travaglini@arm.comAlthough an `EXPECT_CALL()` statement defined earlier takes precedence 126913481Sgiacomo.travaglini@arm.comwhen Google Mock tries to match a function call with an expectation, 127013481Sgiacomo.travaglini@arm.comby default calls don't have to happen in the order `EXPECT_CALL()` 127113481Sgiacomo.travaglini@arm.comstatements are written. For example, if the arguments match the 127213481Sgiacomo.travaglini@arm.commatchers in the third `EXPECT_CALL()`, but not those in the first two, 127313481Sgiacomo.travaglini@arm.comthen the third expectation will be used. 127413481Sgiacomo.travaglini@arm.com 127513481Sgiacomo.travaglini@arm.comIf you would rather have all calls occur in the order of the 127613481Sgiacomo.travaglini@arm.comexpectations, put the `EXPECT_CALL()` statements in a block where you 127713481Sgiacomo.travaglini@arm.comdefine a variable of type `InSequence`: 127813481Sgiacomo.travaglini@arm.com 127913481Sgiacomo.travaglini@arm.com``` 128013481Sgiacomo.travaglini@arm.com using ::testing::_; 128113481Sgiacomo.travaglini@arm.com using ::testing::InSequence; 128213481Sgiacomo.travaglini@arm.com 128313481Sgiacomo.travaglini@arm.com { 128413481Sgiacomo.travaglini@arm.com InSequence s; 128513481Sgiacomo.travaglini@arm.com 128613481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(5)); 128713481Sgiacomo.travaglini@arm.com EXPECT_CALL(bar, DoThat(_)) 128813481Sgiacomo.travaglini@arm.com .Times(2); 128913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(6)); 129013481Sgiacomo.travaglini@arm.com } 129113481Sgiacomo.travaglini@arm.com``` 129213481Sgiacomo.travaglini@arm.com 129313481Sgiacomo.travaglini@arm.comIn this example, we expect a call to `foo.DoThis(5)`, followed by two 129413481Sgiacomo.travaglini@arm.comcalls to `bar.DoThat()` where the argument can be anything, which are 129513481Sgiacomo.travaglini@arm.comin turn followed by a call to `foo.DoThis(6)`. If a call occurred 129613481Sgiacomo.travaglini@arm.comout-of-order, Google Mock will report an error. 129713481Sgiacomo.travaglini@arm.com 129813481Sgiacomo.travaglini@arm.com## Expecting Partially Ordered Calls ## 129913481Sgiacomo.travaglini@arm.com 130013481Sgiacomo.travaglini@arm.comSometimes requiring everything to occur in a predetermined order can 130113481Sgiacomo.travaglini@arm.comlead to brittle tests. For example, we may care about `A` occurring 130213481Sgiacomo.travaglini@arm.combefore both `B` and `C`, but aren't interested in the relative order 130313481Sgiacomo.travaglini@arm.comof `B` and `C`. In this case, the test should reflect our real intent, 130413481Sgiacomo.travaglini@arm.cominstead of being overly constraining. 130513481Sgiacomo.travaglini@arm.com 130613481Sgiacomo.travaglini@arm.comGoogle Mock allows you to impose an arbitrary DAG (directed acyclic 130713481Sgiacomo.travaglini@arm.comgraph) on the calls. One way to express the DAG is to use the 130813481Sgiacomo.travaglini@arm.com[After](V1_5_CheatSheet#The_After_Clause.md) clause of `EXPECT_CALL`. 130913481Sgiacomo.travaglini@arm.com 131013481Sgiacomo.travaglini@arm.comAnother way is via the `InSequence()` clause (not the same as the 131113481Sgiacomo.travaglini@arm.com`InSequence` class), which we borrowed from jMock 2. It's less 131213481Sgiacomo.travaglini@arm.comflexible than `After()`, but more convenient when you have long chains 131313481Sgiacomo.travaglini@arm.comof sequential calls, as it doesn't require you to come up with 131413481Sgiacomo.travaglini@arm.comdifferent names for the expectations in the chains. Here's how it 131513481Sgiacomo.travaglini@arm.comworks: 131613481Sgiacomo.travaglini@arm.com 131713481Sgiacomo.travaglini@arm.comIf we view `EXPECT_CALL()` statements as nodes in a graph, and add an 131813481Sgiacomo.travaglini@arm.comedge from node A to node B wherever A must occur before B, we can get 131913481Sgiacomo.travaglini@arm.coma DAG. We use the term "sequence" to mean a directed path in this 132013481Sgiacomo.travaglini@arm.comDAG. Now, if we decompose the DAG into sequences, we just need to know 132113481Sgiacomo.travaglini@arm.comwhich sequences each `EXPECT_CALL()` belongs to in order to be able to 132213481Sgiacomo.travaglini@arm.comreconstruct the orginal DAG. 132313481Sgiacomo.travaglini@arm.com 132413481Sgiacomo.travaglini@arm.comSo, to specify the partial order on the expectations we need to do two 132513481Sgiacomo.travaglini@arm.comthings: first to define some `Sequence` objects, and then for each 132613481Sgiacomo.travaglini@arm.com`EXPECT_CALL()` say which `Sequence` objects it is part 132713481Sgiacomo.travaglini@arm.comof. Expectations in the same sequence must occur in the order they are 132813481Sgiacomo.travaglini@arm.comwritten. For example, 132913481Sgiacomo.travaglini@arm.com 133013481Sgiacomo.travaglini@arm.com``` 133113481Sgiacomo.travaglini@arm.com using ::testing::Sequence; 133213481Sgiacomo.travaglini@arm.com 133313481Sgiacomo.travaglini@arm.com Sequence s1, s2; 133413481Sgiacomo.travaglini@arm.com 133513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, A()) 133613481Sgiacomo.travaglini@arm.com .InSequence(s1, s2); 133713481Sgiacomo.travaglini@arm.com EXPECT_CALL(bar, B()) 133813481Sgiacomo.travaglini@arm.com .InSequence(s1); 133913481Sgiacomo.travaglini@arm.com EXPECT_CALL(bar, C()) 134013481Sgiacomo.travaglini@arm.com .InSequence(s2); 134113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, D()) 134213481Sgiacomo.travaglini@arm.com .InSequence(s2); 134313481Sgiacomo.travaglini@arm.com``` 134413481Sgiacomo.travaglini@arm.com 134513481Sgiacomo.travaglini@arm.comspecifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> 134613481Sgiacomo.travaglini@arm.comC -> D`): 134713481Sgiacomo.travaglini@arm.com 134813481Sgiacomo.travaglini@arm.com``` 134913481Sgiacomo.travaglini@arm.com +---> B 135013481Sgiacomo.travaglini@arm.com | 135113481Sgiacomo.travaglini@arm.com A ---| 135213481Sgiacomo.travaglini@arm.com | 135313481Sgiacomo.travaglini@arm.com +---> C ---> D 135413481Sgiacomo.travaglini@arm.com``` 135513481Sgiacomo.travaglini@arm.com 135613481Sgiacomo.travaglini@arm.comThis means that A must occur before B and C, and C must occur before 135713481Sgiacomo.travaglini@arm.comD. There's no restriction about the order other than these. 135813481Sgiacomo.travaglini@arm.com 135913481Sgiacomo.travaglini@arm.com## Controlling When an Expectation Retires ## 136013481Sgiacomo.travaglini@arm.com 136113481Sgiacomo.travaglini@arm.comWhen a mock method is called, Google Mock only consider expectations 136213481Sgiacomo.travaglini@arm.comthat are still active. An expectation is active when created, and 136313481Sgiacomo.travaglini@arm.combecomes inactive (aka _retires_) when a call that has to occur later 136413481Sgiacomo.travaglini@arm.comhas occurred. For example, in 136513481Sgiacomo.travaglini@arm.com 136613481Sgiacomo.travaglini@arm.com``` 136713481Sgiacomo.travaglini@arm.com using ::testing::_; 136813481Sgiacomo.travaglini@arm.com using ::testing::Sequence; 136913481Sgiacomo.travaglini@arm.com 137013481Sgiacomo.travaglini@arm.com Sequence s1, s2; 137113481Sgiacomo.travaglini@arm.com 137213481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1 137313481Sgiacomo.travaglini@arm.com .Times(AnyNumber()) 137413481Sgiacomo.travaglini@arm.com .InSequence(s1, s2); 137513481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2 137613481Sgiacomo.travaglini@arm.com .InSequence(s1); 137713481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3 137813481Sgiacomo.travaglini@arm.com .InSequence(s2); 137913481Sgiacomo.travaglini@arm.com``` 138013481Sgiacomo.travaglini@arm.com 138113481Sgiacomo.travaglini@arm.comas soon as either #2 or #3 is matched, #1 will retire. If a warning 138213481Sgiacomo.travaglini@arm.com`"File too large."` is logged after this, it will be an error. 138313481Sgiacomo.travaglini@arm.com 138413481Sgiacomo.travaglini@arm.comNote that an expectation doesn't retire automatically when it's 138513481Sgiacomo.travaglini@arm.comsaturated. For example, 138613481Sgiacomo.travaglini@arm.com 138713481Sgiacomo.travaglini@arm.com``` 138813481Sgiacomo.travaglini@arm.comusing ::testing::_; 138913481Sgiacomo.travaglini@arm.com... 139013481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, _)); // #1 139113481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2 139213481Sgiacomo.travaglini@arm.com``` 139313481Sgiacomo.travaglini@arm.com 139413481Sgiacomo.travaglini@arm.comsays that there will be exactly one warning with the message `"File 139513481Sgiacomo.travaglini@arm.comtoo large."`. If the second warning contains this message too, #2 will 139613481Sgiacomo.travaglini@arm.commatch again and result in an upper-bound-violated error. 139713481Sgiacomo.travaglini@arm.com 139813481Sgiacomo.travaglini@arm.comIf this is not what you want, you can ask an expectation to retire as 139913481Sgiacomo.travaglini@arm.comsoon as it becomes saturated: 140013481Sgiacomo.travaglini@arm.com 140113481Sgiacomo.travaglini@arm.com``` 140213481Sgiacomo.travaglini@arm.comusing ::testing::_; 140313481Sgiacomo.travaglini@arm.com... 140413481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, _)); // #1 140513481Sgiacomo.travaglini@arm.com EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2 140613481Sgiacomo.travaglini@arm.com .RetiresOnSaturation(); 140713481Sgiacomo.travaglini@arm.com``` 140813481Sgiacomo.travaglini@arm.com 140913481Sgiacomo.travaglini@arm.comHere #2 can be used only once, so if you have two warnings with the 141013481Sgiacomo.travaglini@arm.commessage `"File too large."`, the first will match #2 and the second 141113481Sgiacomo.travaglini@arm.comwill match #1 - there will be no error. 141213481Sgiacomo.travaglini@arm.com 141313481Sgiacomo.travaglini@arm.com# Using Actions # 141413481Sgiacomo.travaglini@arm.com 141513481Sgiacomo.travaglini@arm.com## Returning References from Mock Methods ## 141613481Sgiacomo.travaglini@arm.com 141713481Sgiacomo.travaglini@arm.comIf a mock function's return type is a reference, you need to use 141813481Sgiacomo.travaglini@arm.com`ReturnRef()` instead of `Return()` to return a result: 141913481Sgiacomo.travaglini@arm.com 142013481Sgiacomo.travaglini@arm.com``` 142113481Sgiacomo.travaglini@arm.comusing ::testing::ReturnRef; 142213481Sgiacomo.travaglini@arm.com 142313481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 142413481Sgiacomo.travaglini@arm.com public: 142513481Sgiacomo.travaglini@arm.com MOCK_METHOD0(GetBar, Bar&()); 142613481Sgiacomo.travaglini@arm.com}; 142713481Sgiacomo.travaglini@arm.com... 142813481Sgiacomo.travaglini@arm.com 142913481Sgiacomo.travaglini@arm.com MockFoo foo; 143013481Sgiacomo.travaglini@arm.com Bar bar; 143113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, GetBar()) 143213481Sgiacomo.travaglini@arm.com .WillOnce(ReturnRef(bar)); 143313481Sgiacomo.travaglini@arm.com``` 143413481Sgiacomo.travaglini@arm.com 143513481Sgiacomo.travaglini@arm.com## Combining Actions ## 143613481Sgiacomo.travaglini@arm.com 143713481Sgiacomo.travaglini@arm.comWant to do more than one thing when a function is called? That's 143813481Sgiacomo.travaglini@arm.comfine. `DoAll()` allow you to do sequence of actions every time. Only 143913481Sgiacomo.travaglini@arm.comthe return value of the last action in the sequence will be used. 144013481Sgiacomo.travaglini@arm.com 144113481Sgiacomo.travaglini@arm.com``` 144213481Sgiacomo.travaglini@arm.comusing ::testing::DoAll; 144313481Sgiacomo.travaglini@arm.com 144413481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 144513481Sgiacomo.travaglini@arm.com public: 144613481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Bar, bool(int n)); 144713481Sgiacomo.travaglini@arm.com}; 144813481Sgiacomo.travaglini@arm.com... 144913481Sgiacomo.travaglini@arm.com 145013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(_)) 145113481Sgiacomo.travaglini@arm.com .WillOnce(DoAll(action_1, 145213481Sgiacomo.travaglini@arm.com action_2, 145313481Sgiacomo.travaglini@arm.com ... 145413481Sgiacomo.travaglini@arm.com action_n)); 145513481Sgiacomo.travaglini@arm.com``` 145613481Sgiacomo.travaglini@arm.com 145713481Sgiacomo.travaglini@arm.com## Mocking Side Effects ## 145813481Sgiacomo.travaglini@arm.com 145913481Sgiacomo.travaglini@arm.comSometimes a method exhibits its effect not via returning a value but 146013481Sgiacomo.travaglini@arm.comvia side effects. For example, it may change some global state or 146113481Sgiacomo.travaglini@arm.commodify an output argument. To mock side effects, in general you can 146213481Sgiacomo.travaglini@arm.comdefine your own action by implementing `::testing::ActionInterface`. 146313481Sgiacomo.travaglini@arm.com 146413481Sgiacomo.travaglini@arm.comIf all you need to do is to change an output argument, the built-in 146513481Sgiacomo.travaglini@arm.com`SetArgumentPointee()` action is convenient: 146613481Sgiacomo.travaglini@arm.com 146713481Sgiacomo.travaglini@arm.com``` 146813481Sgiacomo.travaglini@arm.comusing ::testing::SetArgumentPointee; 146913481Sgiacomo.travaglini@arm.com 147013481Sgiacomo.travaglini@arm.comclass MockMutator : public Mutator { 147113481Sgiacomo.travaglini@arm.com public: 147213481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Mutate, void(bool mutate, int* value)); 147313481Sgiacomo.travaglini@arm.com ... 147413481Sgiacomo.travaglini@arm.com}; 147513481Sgiacomo.travaglini@arm.com... 147613481Sgiacomo.travaglini@arm.com 147713481Sgiacomo.travaglini@arm.com MockMutator mutator; 147813481Sgiacomo.travaglini@arm.com EXPECT_CALL(mutator, Mutate(true, _)) 147913481Sgiacomo.travaglini@arm.com .WillOnce(SetArgumentPointee<1>(5)); 148013481Sgiacomo.travaglini@arm.com``` 148113481Sgiacomo.travaglini@arm.com 148213481Sgiacomo.travaglini@arm.comIn this example, when `mutator.Mutate()` is called, we will assign 5 148313481Sgiacomo.travaglini@arm.comto the `int` variable pointed to by argument #1 148413481Sgiacomo.travaglini@arm.com(0-based). 148513481Sgiacomo.travaglini@arm.com 148613481Sgiacomo.travaglini@arm.com`SetArgumentPointee()` conveniently makes an internal copy of the 148713481Sgiacomo.travaglini@arm.comvalue you pass to it, removing the need to keep the value in scope and 148813481Sgiacomo.travaglini@arm.comalive. The implication however is that the value must have a copy 148913481Sgiacomo.travaglini@arm.comconstructor and assignment operator. 149013481Sgiacomo.travaglini@arm.com 149113481Sgiacomo.travaglini@arm.comIf the mock method also needs to return a value as well, you can chain 149213481Sgiacomo.travaglini@arm.com`SetArgumentPointee()` with `Return()` using `DoAll()`: 149313481Sgiacomo.travaglini@arm.com 149413481Sgiacomo.travaglini@arm.com``` 149513481Sgiacomo.travaglini@arm.comusing ::testing::_; 149613481Sgiacomo.travaglini@arm.comusing ::testing::Return; 149713481Sgiacomo.travaglini@arm.comusing ::testing::SetArgumentPointee; 149813481Sgiacomo.travaglini@arm.com 149913481Sgiacomo.travaglini@arm.comclass MockMutator : public Mutator { 150013481Sgiacomo.travaglini@arm.com public: 150113481Sgiacomo.travaglini@arm.com ... 150213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(MutateInt, bool(int* value)); 150313481Sgiacomo.travaglini@arm.com}; 150413481Sgiacomo.travaglini@arm.com... 150513481Sgiacomo.travaglini@arm.com 150613481Sgiacomo.travaglini@arm.com MockMutator mutator; 150713481Sgiacomo.travaglini@arm.com EXPECT_CALL(mutator, MutateInt(_)) 150813481Sgiacomo.travaglini@arm.com .WillOnce(DoAll(SetArgumentPointee<0>(5), 150913481Sgiacomo.travaglini@arm.com Return(true))); 151013481Sgiacomo.travaglini@arm.com``` 151113481Sgiacomo.travaglini@arm.com 151213481Sgiacomo.travaglini@arm.comIf the output argument is an array, use the 151313481Sgiacomo.travaglini@arm.com`SetArrayArgument<N>(first, last)` action instead. It copies the 151413481Sgiacomo.travaglini@arm.comelements in source range `[first, last)` to the array pointed to by 151513481Sgiacomo.travaglini@arm.comthe `N`-th (0-based) argument: 151613481Sgiacomo.travaglini@arm.com 151713481Sgiacomo.travaglini@arm.com``` 151813481Sgiacomo.travaglini@arm.comusing ::testing::NotNull; 151913481Sgiacomo.travaglini@arm.comusing ::testing::SetArrayArgument; 152013481Sgiacomo.travaglini@arm.com 152113481Sgiacomo.travaglini@arm.comclass MockArrayMutator : public ArrayMutator { 152213481Sgiacomo.travaglini@arm.com public: 152313481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Mutate, void(int* values, int num_values)); 152413481Sgiacomo.travaglini@arm.com ... 152513481Sgiacomo.travaglini@arm.com}; 152613481Sgiacomo.travaglini@arm.com... 152713481Sgiacomo.travaglini@arm.com 152813481Sgiacomo.travaglini@arm.com MockArrayMutator mutator; 152913481Sgiacomo.travaglini@arm.com int values[5] = { 1, 2, 3, 4, 5 }; 153013481Sgiacomo.travaglini@arm.com EXPECT_CALL(mutator, Mutate(NotNull(), 5)) 153113481Sgiacomo.travaglini@arm.com .WillOnce(SetArrayArgument<0>(values, values + 5)); 153213481Sgiacomo.travaglini@arm.com``` 153313481Sgiacomo.travaglini@arm.com 153413481Sgiacomo.travaglini@arm.comThis also works when the argument is an output iterator: 153513481Sgiacomo.travaglini@arm.com 153613481Sgiacomo.travaglini@arm.com``` 153713481Sgiacomo.travaglini@arm.comusing ::testing::_; 153813481Sgiacomo.travaglini@arm.comusing ::testing::SeArrayArgument; 153913481Sgiacomo.travaglini@arm.com 154013481Sgiacomo.travaglini@arm.comclass MockRolodex : public Rolodex { 154113481Sgiacomo.travaglini@arm.com public: 154213481Sgiacomo.travaglini@arm.com MOCK_METHOD1(GetNames, void(std::back_insert_iterator<vector<string> >)); 154313481Sgiacomo.travaglini@arm.com ... 154413481Sgiacomo.travaglini@arm.com}; 154513481Sgiacomo.travaglini@arm.com... 154613481Sgiacomo.travaglini@arm.com 154713481Sgiacomo.travaglini@arm.com MockRolodex rolodex; 154813481Sgiacomo.travaglini@arm.com vector<string> names; 154913481Sgiacomo.travaglini@arm.com names.push_back("George"); 155013481Sgiacomo.travaglini@arm.com names.push_back("John"); 155113481Sgiacomo.travaglini@arm.com names.push_back("Thomas"); 155213481Sgiacomo.travaglini@arm.com EXPECT_CALL(rolodex, GetNames(_)) 155313481Sgiacomo.travaglini@arm.com .WillOnce(SetArrayArgument<0>(names.begin(), names.end())); 155413481Sgiacomo.travaglini@arm.com``` 155513481Sgiacomo.travaglini@arm.com 155613481Sgiacomo.travaglini@arm.com## Changing a Mock Object's Behavior Based on the State ## 155713481Sgiacomo.travaglini@arm.com 155813481Sgiacomo.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: 155913481Sgiacomo.travaglini@arm.com 156013481Sgiacomo.travaglini@arm.com``` 156113481Sgiacomo.travaglini@arm.comusing ::testing::InSequence; 156213481Sgiacomo.travaglini@arm.comusing ::testing::Return; 156313481Sgiacomo.travaglini@arm.com 156413481Sgiacomo.travaglini@arm.com... 156513481Sgiacomo.travaglini@arm.com { 156613481Sgiacomo.travaglini@arm.com InSequence seq; 156713481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, IsDirty()) 156813481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return(true)); 156913481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, Flush()); 157013481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, IsDirty()) 157113481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return(false)); 157213481Sgiacomo.travaglini@arm.com } 157313481Sgiacomo.travaglini@arm.com my_mock.FlushIfDirty(); 157413481Sgiacomo.travaglini@arm.com``` 157513481Sgiacomo.travaglini@arm.com 157613481Sgiacomo.travaglini@arm.comThis makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called and return `false` afterwards. 157713481Sgiacomo.travaglini@arm.com 157813481Sgiacomo.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: 157913481Sgiacomo.travaglini@arm.com 158013481Sgiacomo.travaglini@arm.com``` 158113481Sgiacomo.travaglini@arm.comusing ::testing::_; 158213481Sgiacomo.travaglini@arm.comusing ::testing::SaveArg; 158313481Sgiacomo.travaglini@arm.comusing ::testing::Return; 158413481Sgiacomo.travaglini@arm.com 158513481Sgiacomo.travaglini@arm.comACTION_P(ReturnPointee, p) { return *p; } 158613481Sgiacomo.travaglini@arm.com... 158713481Sgiacomo.travaglini@arm.com int previous_value = 0; 158813481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, GetPrevValue()) 158913481Sgiacomo.travaglini@arm.com .WillRepeatedly(ReturnPointee(&previous_value)); 159013481Sgiacomo.travaglini@arm.com EXPECT_CALL(my_mock, UpdateValue(_)) 159113481Sgiacomo.travaglini@arm.com .WillRepeatedly(SaveArg<0>(&previous_value)); 159213481Sgiacomo.travaglini@arm.com my_mock.DoSomethingToUpdateValue(); 159313481Sgiacomo.travaglini@arm.com``` 159413481Sgiacomo.travaglini@arm.com 159513481Sgiacomo.travaglini@arm.comHere `my_mock.GetPrevValue()` will always return the argument of the last `UpdateValue()` call. 159613481Sgiacomo.travaglini@arm.com 159713481Sgiacomo.travaglini@arm.com## Setting the Default Value for a Return Type ## 159813481Sgiacomo.travaglini@arm.com 159913481Sgiacomo.travaglini@arm.comIf a mock method's return type is a built-in C++ type or pointer, by 160013481Sgiacomo.travaglini@arm.comdefault it will return 0 when invoked. You only need to specify an 160113481Sgiacomo.travaglini@arm.comaction if this default value doesn't work for you. 160213481Sgiacomo.travaglini@arm.com 160313481Sgiacomo.travaglini@arm.comSometimes, you may want to change this default value, or you may want 160413481Sgiacomo.travaglini@arm.comto specify a default value for types Google Mock doesn't know 160513481Sgiacomo.travaglini@arm.comabout. You can do this using the `::testing::DefaultValue` class 160613481Sgiacomo.travaglini@arm.comtemplate: 160713481Sgiacomo.travaglini@arm.com 160813481Sgiacomo.travaglini@arm.com``` 160913481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 161013481Sgiacomo.travaglini@arm.com public: 161113481Sgiacomo.travaglini@arm.com MOCK_METHOD0(CalculateBar, Bar()); 161213481Sgiacomo.travaglini@arm.com}; 161313481Sgiacomo.travaglini@arm.com... 161413481Sgiacomo.travaglini@arm.com 161513481Sgiacomo.travaglini@arm.com Bar default_bar; 161613481Sgiacomo.travaglini@arm.com // Sets the default return value for type Bar. 161713481Sgiacomo.travaglini@arm.com DefaultValue<Bar>::Set(default_bar); 161813481Sgiacomo.travaglini@arm.com 161913481Sgiacomo.travaglini@arm.com MockFoo foo; 162013481Sgiacomo.travaglini@arm.com 162113481Sgiacomo.travaglini@arm.com // We don't need to specify an action here, as the default 162213481Sgiacomo.travaglini@arm.com // return value works for us. 162313481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, CalculateBar()); 162413481Sgiacomo.travaglini@arm.com 162513481Sgiacomo.travaglini@arm.com foo.CalculateBar(); // This should return default_bar. 162613481Sgiacomo.travaglini@arm.com 162713481Sgiacomo.travaglini@arm.com // Unsets the default return value. 162813481Sgiacomo.travaglini@arm.com DefaultValue<Bar>::Clear(); 162913481Sgiacomo.travaglini@arm.com``` 163013481Sgiacomo.travaglini@arm.com 163113481Sgiacomo.travaglini@arm.comPlease note that changing the default value for a type can make you 163213481Sgiacomo.travaglini@arm.comtests hard to understand. We recommend you to use this feature 163313481Sgiacomo.travaglini@arm.comjudiciously. For example, you may want to make sure the `Set()` and 163413481Sgiacomo.travaglini@arm.com`Clear()` calls are right next to the code that uses your mock. 163513481Sgiacomo.travaglini@arm.com 163613481Sgiacomo.travaglini@arm.com## Setting the Default Actions for a Mock Method ## 163713481Sgiacomo.travaglini@arm.com 163813481Sgiacomo.travaglini@arm.comYou've learned how to change the default value of a given 163913481Sgiacomo.travaglini@arm.comtype. However, this may be too coarse for your purpose: perhaps you 164013481Sgiacomo.travaglini@arm.comhave two mock methods with the same return type and you want them to 164113481Sgiacomo.travaglini@arm.comhave different behaviors. The `ON_CALL()` macro allows you to 164213481Sgiacomo.travaglini@arm.comcustomize your mock's behavior at the method level: 164313481Sgiacomo.travaglini@arm.com 164413481Sgiacomo.travaglini@arm.com``` 164513481Sgiacomo.travaglini@arm.comusing ::testing::_; 164613481Sgiacomo.travaglini@arm.comusing ::testing::AnyNumber; 164713481Sgiacomo.travaglini@arm.comusing ::testing::Gt; 164813481Sgiacomo.travaglini@arm.comusing ::testing::Return; 164913481Sgiacomo.travaglini@arm.com... 165013481Sgiacomo.travaglini@arm.com ON_CALL(foo, Sign(_)) 165113481Sgiacomo.travaglini@arm.com .WillByDefault(Return(-1)); 165213481Sgiacomo.travaglini@arm.com ON_CALL(foo, Sign(0)) 165313481Sgiacomo.travaglini@arm.com .WillByDefault(Return(0)); 165413481Sgiacomo.travaglini@arm.com ON_CALL(foo, Sign(Gt(0))) 165513481Sgiacomo.travaglini@arm.com .WillByDefault(Return(1)); 165613481Sgiacomo.travaglini@arm.com 165713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Sign(_)) 165813481Sgiacomo.travaglini@arm.com .Times(AnyNumber()); 165913481Sgiacomo.travaglini@arm.com 166013481Sgiacomo.travaglini@arm.com foo.Sign(5); // This should return 1. 166113481Sgiacomo.travaglini@arm.com foo.Sign(-9); // This should return -1. 166213481Sgiacomo.travaglini@arm.com foo.Sign(0); // This should return 0. 166313481Sgiacomo.travaglini@arm.com``` 166413481Sgiacomo.travaglini@arm.com 166513481Sgiacomo.travaglini@arm.comAs you may have guessed, when there are more than one `ON_CALL()` 166613481Sgiacomo.travaglini@arm.comstatements, the news order take precedence over the older ones. In 166713481Sgiacomo.travaglini@arm.comother words, the **last** one that matches the function arguments will 166813481Sgiacomo.travaglini@arm.combe used. This matching order allows you to set up the common behavior 166913481Sgiacomo.travaglini@arm.comin a mock object's constructor or the test fixture's set-up phase and 167013481Sgiacomo.travaglini@arm.comspecialize the mock's behavior later. 167113481Sgiacomo.travaglini@arm.com 167213481Sgiacomo.travaglini@arm.com## Using Functions/Methods/Functors as Actions ## 167313481Sgiacomo.travaglini@arm.com 167413481Sgiacomo.travaglini@arm.comIf the built-in actions don't suit you, you can easily use an existing 167513481Sgiacomo.travaglini@arm.comfunction, method, or functor as an action: 167613481Sgiacomo.travaglini@arm.com 167713481Sgiacomo.travaglini@arm.com``` 167813481Sgiacomo.travaglini@arm.comusing ::testing::_; 167913481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 168013481Sgiacomo.travaglini@arm.com 168113481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 168213481Sgiacomo.travaglini@arm.com public: 168313481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Sum, int(int x, int y)); 168413481Sgiacomo.travaglini@arm.com MOCK_METHOD1(ComplexJob, bool(int x)); 168513481Sgiacomo.travaglini@arm.com}; 168613481Sgiacomo.travaglini@arm.com 168713481Sgiacomo.travaglini@arm.comint CalculateSum(int x, int y) { return x + y; } 168813481Sgiacomo.travaglini@arm.com 168913481Sgiacomo.travaglini@arm.comclass Helper { 169013481Sgiacomo.travaglini@arm.com public: 169113481Sgiacomo.travaglini@arm.com bool ComplexJob(int x); 169213481Sgiacomo.travaglini@arm.com}; 169313481Sgiacomo.travaglini@arm.com... 169413481Sgiacomo.travaglini@arm.com 169513481Sgiacomo.travaglini@arm.com MockFoo foo; 169613481Sgiacomo.travaglini@arm.com Helper helper; 169713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Sum(_, _)) 169813481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(CalculateSum)); 169913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, ComplexJob(_)) 170013481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(&helper, &Helper::ComplexJob)); 170113481Sgiacomo.travaglini@arm.com 170213481Sgiacomo.travaglini@arm.com foo.Sum(5, 6); // Invokes CalculateSum(5, 6). 170313481Sgiacomo.travaglini@arm.com foo.ComplexJob(10); // Invokes helper.ComplexJob(10); 170413481Sgiacomo.travaglini@arm.com``` 170513481Sgiacomo.travaglini@arm.com 170613481Sgiacomo.travaglini@arm.comThe only requirement is that the type of the function, etc must be 170713481Sgiacomo.travaglini@arm.com_compatible_ with the signature of the mock function, meaning that the 170813481Sgiacomo.travaglini@arm.comlatter's arguments can be implicitly converted to the corresponding 170913481Sgiacomo.travaglini@arm.comarguments of the former, and the former's return type can be 171013481Sgiacomo.travaglini@arm.comimplicitly converted to that of the latter. So, you can invoke 171113481Sgiacomo.travaglini@arm.comsomething whose type is _not_ exactly the same as the mock function, 171213481Sgiacomo.travaglini@arm.comas long as it's safe to do so - nice, huh? 171313481Sgiacomo.travaglini@arm.com 171413481Sgiacomo.travaglini@arm.com## Invoking a Function/Method/Functor Without Arguments ## 171513481Sgiacomo.travaglini@arm.com 171613481Sgiacomo.travaglini@arm.com`Invoke()` is very useful for doing actions that are more complex. It 171713481Sgiacomo.travaglini@arm.compasses the mock function's arguments to the function or functor being 171813481Sgiacomo.travaglini@arm.cominvoked such that the callee has the full context of the call to work 171913481Sgiacomo.travaglini@arm.comwith. If the invoked function is not interested in some or all of the 172013481Sgiacomo.travaglini@arm.comarguments, it can simply ignore them. 172113481Sgiacomo.travaglini@arm.com 172213481Sgiacomo.travaglini@arm.comYet, a common pattern is that a test author wants to invoke a function 172313481Sgiacomo.travaglini@arm.comwithout the arguments of the mock function. `Invoke()` allows her to 172413481Sgiacomo.travaglini@arm.comdo that using a wrapper function that throws away the arguments before 172513481Sgiacomo.travaglini@arm.cominvoking an underlining nullary function. Needless to say, this can be 172613481Sgiacomo.travaglini@arm.comtedious and obscures the intent of the test. 172713481Sgiacomo.travaglini@arm.com 172813481Sgiacomo.travaglini@arm.com`InvokeWithoutArgs()` solves this problem. It's like `Invoke()` except 172913481Sgiacomo.travaglini@arm.comthat it doesn't pass the mock function's arguments to the 173013481Sgiacomo.travaglini@arm.comcallee. Here's an example: 173113481Sgiacomo.travaglini@arm.com 173213481Sgiacomo.travaglini@arm.com``` 173313481Sgiacomo.travaglini@arm.comusing ::testing::_; 173413481Sgiacomo.travaglini@arm.comusing ::testing::InvokeWithoutArgs; 173513481Sgiacomo.travaglini@arm.com 173613481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 173713481Sgiacomo.travaglini@arm.com public: 173813481Sgiacomo.travaglini@arm.com MOCK_METHOD1(ComplexJob, bool(int n)); 173913481Sgiacomo.travaglini@arm.com}; 174013481Sgiacomo.travaglini@arm.com 174113481Sgiacomo.travaglini@arm.combool Job1() { ... } 174213481Sgiacomo.travaglini@arm.com... 174313481Sgiacomo.travaglini@arm.com 174413481Sgiacomo.travaglini@arm.com MockFoo foo; 174513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, ComplexJob(_)) 174613481Sgiacomo.travaglini@arm.com .WillOnce(InvokeWithoutArgs(Job1)); 174713481Sgiacomo.travaglini@arm.com 174813481Sgiacomo.travaglini@arm.com foo.ComplexJob(10); // Invokes Job1(). 174913481Sgiacomo.travaglini@arm.com``` 175013481Sgiacomo.travaglini@arm.com 175113481Sgiacomo.travaglini@arm.com## Invoking an Argument of the Mock Function ## 175213481Sgiacomo.travaglini@arm.com 175313481Sgiacomo.travaglini@arm.comSometimes a mock function will receive a function pointer or a functor 175413481Sgiacomo.travaglini@arm.com(in other words, a "callable") as an argument, e.g. 175513481Sgiacomo.travaglini@arm.com 175613481Sgiacomo.travaglini@arm.com``` 175713481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 175813481Sgiacomo.travaglini@arm.com public: 175913481Sgiacomo.travaglini@arm.com MOCK_METHOD2(DoThis, bool(int n, bool (*fp)(int))); 176013481Sgiacomo.travaglini@arm.com}; 176113481Sgiacomo.travaglini@arm.com``` 176213481Sgiacomo.travaglini@arm.com 176313481Sgiacomo.travaglini@arm.comand you may want to invoke this callable argument: 176413481Sgiacomo.travaglini@arm.com 176513481Sgiacomo.travaglini@arm.com``` 176613481Sgiacomo.travaglini@arm.comusing ::testing::_; 176713481Sgiacomo.travaglini@arm.com... 176813481Sgiacomo.travaglini@arm.com MockFoo foo; 176913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(_, _)) 177013481Sgiacomo.travaglini@arm.com .WillOnce(...); 177113481Sgiacomo.travaglini@arm.com // Will execute (*fp)(5), where fp is the 177213481Sgiacomo.travaglini@arm.com // second argument DoThis() receives. 177313481Sgiacomo.travaglini@arm.com``` 177413481Sgiacomo.travaglini@arm.com 177513481Sgiacomo.travaglini@arm.comArghh, you need to refer to a mock function argument but C++ has no 177613481Sgiacomo.travaglini@arm.comlambda (yet), so you have to define your own action. :-( Or do you 177713481Sgiacomo.travaglini@arm.comreally? 177813481Sgiacomo.travaglini@arm.com 177913481Sgiacomo.travaglini@arm.comWell, Google Mock has an action to solve _exactly_ this problem: 178013481Sgiacomo.travaglini@arm.com 178113481Sgiacomo.travaglini@arm.com``` 178213481Sgiacomo.travaglini@arm.com InvokeArgument<N>(arg_1, arg_2, ..., arg_m) 178313481Sgiacomo.travaglini@arm.com``` 178413481Sgiacomo.travaglini@arm.com 178513481Sgiacomo.travaglini@arm.comwill invoke the `N`-th (0-based) argument the mock function receives, 178613481Sgiacomo.travaglini@arm.comwith `arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is 178713481Sgiacomo.travaglini@arm.coma function pointer or a functor, Google Mock handles them both. 178813481Sgiacomo.travaglini@arm.com 178913481Sgiacomo.travaglini@arm.comWith that, you could write: 179013481Sgiacomo.travaglini@arm.com 179113481Sgiacomo.travaglini@arm.com``` 179213481Sgiacomo.travaglini@arm.comusing ::testing::_; 179313481Sgiacomo.travaglini@arm.comusing ::testing::InvokeArgument; 179413481Sgiacomo.travaglini@arm.com... 179513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(_, _)) 179613481Sgiacomo.travaglini@arm.com .WillOnce(InvokeArgument<1>(5)); 179713481Sgiacomo.travaglini@arm.com // Will execute (*fp)(5), where fp is the 179813481Sgiacomo.travaglini@arm.com // second argument DoThis() receives. 179913481Sgiacomo.travaglini@arm.com``` 180013481Sgiacomo.travaglini@arm.com 180113481Sgiacomo.travaglini@arm.comWhat if the callable takes an argument by reference? No problem - just 180213481Sgiacomo.travaglini@arm.comwrap it inside `ByRef()`: 180313481Sgiacomo.travaglini@arm.com 180413481Sgiacomo.travaglini@arm.com``` 180513481Sgiacomo.travaglini@arm.com... 180613481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Bar, bool(bool (*fp)(int, const Helper&))); 180713481Sgiacomo.travaglini@arm.com... 180813481Sgiacomo.travaglini@arm.comusing ::testing::_; 180913481Sgiacomo.travaglini@arm.comusing ::testing::ByRef; 181013481Sgiacomo.travaglini@arm.comusing ::testing::InvokeArgument; 181113481Sgiacomo.travaglini@arm.com... 181213481Sgiacomo.travaglini@arm.com 181313481Sgiacomo.travaglini@arm.com MockFoo foo; 181413481Sgiacomo.travaglini@arm.com Helper helper; 181513481Sgiacomo.travaglini@arm.com ... 181613481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(_)) 181713481Sgiacomo.travaglini@arm.com .WillOnce(InvokeArgument<0>(5, ByRef(helper))); 181813481Sgiacomo.travaglini@arm.com // ByRef(helper) guarantees that a reference to helper, not a copy of it, 181913481Sgiacomo.travaglini@arm.com // will be passed to the callable. 182013481Sgiacomo.travaglini@arm.com``` 182113481Sgiacomo.travaglini@arm.com 182213481Sgiacomo.travaglini@arm.comWhat if the callable takes an argument by reference and we do **not** 182313481Sgiacomo.travaglini@arm.comwrap the argument in `ByRef()`? Then `InvokeArgument()` will _make a 182413481Sgiacomo.travaglini@arm.comcopy_ of the argument, and pass a _reference to the copy_, instead of 182513481Sgiacomo.travaglini@arm.coma reference to the original value, to the callable. This is especially 182613481Sgiacomo.travaglini@arm.comhandy when the argument is a temporary value: 182713481Sgiacomo.travaglini@arm.com 182813481Sgiacomo.travaglini@arm.com``` 182913481Sgiacomo.travaglini@arm.com... 183013481Sgiacomo.travaglini@arm.com MOCK_METHOD1(DoThat, bool(bool (*f)(const double& x, const string& s))); 183113481Sgiacomo.travaglini@arm.com... 183213481Sgiacomo.travaglini@arm.comusing ::testing::_; 183313481Sgiacomo.travaglini@arm.comusing ::testing::InvokeArgument; 183413481Sgiacomo.travaglini@arm.com... 183513481Sgiacomo.travaglini@arm.com 183613481Sgiacomo.travaglini@arm.com MockFoo foo; 183713481Sgiacomo.travaglini@arm.com ... 183813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat(_)) 183913481Sgiacomo.travaglini@arm.com .WillOnce(InvokeArgument<0>(5.0, string("Hi"))); 184013481Sgiacomo.travaglini@arm.com // Will execute (*f)(5.0, string("Hi")), where f is the function pointer 184113481Sgiacomo.travaglini@arm.com // DoThat() receives. Note that the values 5.0 and string("Hi") are 184213481Sgiacomo.travaglini@arm.com // temporary and dead once the EXPECT_CALL() statement finishes. Yet 184313481Sgiacomo.travaglini@arm.com // it's fine to perform this action later, since a copy of the values 184413481Sgiacomo.travaglini@arm.com // are kept inside the InvokeArgument action. 184513481Sgiacomo.travaglini@arm.com``` 184613481Sgiacomo.travaglini@arm.com 184713481Sgiacomo.travaglini@arm.com## Ignoring an Action's Result ## 184813481Sgiacomo.travaglini@arm.com 184913481Sgiacomo.travaglini@arm.comSometimes you have an action that returns _something_, but you need an 185013481Sgiacomo.travaglini@arm.comaction that returns `void` (perhaps you want to use it in a mock 185113481Sgiacomo.travaglini@arm.comfunction that returns `void`, or perhaps it needs to be used in 185213481Sgiacomo.travaglini@arm.com`DoAll()` and it's not the last in the list). `IgnoreResult()` lets 185313481Sgiacomo.travaglini@arm.comyou do that. For example: 185413481Sgiacomo.travaglini@arm.com 185513481Sgiacomo.travaglini@arm.com``` 185613481Sgiacomo.travaglini@arm.comusing ::testing::_; 185713481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 185813481Sgiacomo.travaglini@arm.comusing ::testing::Return; 185913481Sgiacomo.travaglini@arm.com 186013481Sgiacomo.travaglini@arm.comint Process(const MyData& data); 186113481Sgiacomo.travaglini@arm.comstring DoSomething(); 186213481Sgiacomo.travaglini@arm.com 186313481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 186413481Sgiacomo.travaglini@arm.com public: 186513481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Abc, void(const MyData& data)); 186613481Sgiacomo.travaglini@arm.com MOCK_METHOD0(Xyz, bool()); 186713481Sgiacomo.travaglini@arm.com}; 186813481Sgiacomo.travaglini@arm.com... 186913481Sgiacomo.travaglini@arm.com 187013481Sgiacomo.travaglini@arm.com MockFoo foo; 187113481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Abc(_)) 187213481Sgiacomo.travaglini@arm.com // .WillOnce(Invoke(Process)); 187313481Sgiacomo.travaglini@arm.com // The above line won't compile as Process() returns int but Abc() needs 187413481Sgiacomo.travaglini@arm.com // to return void. 187513481Sgiacomo.travaglini@arm.com .WillOnce(IgnoreResult(Invoke(Process))); 187613481Sgiacomo.travaglini@arm.com 187713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Xyz()) 187813481Sgiacomo.travaglini@arm.com .WillOnce(DoAll(IgnoreResult(Invoke(DoSomething)), 187913481Sgiacomo.travaglini@arm.com // Ignores the string DoSomething() returns. 188013481Sgiacomo.travaglini@arm.com Return(true))); 188113481Sgiacomo.travaglini@arm.com``` 188213481Sgiacomo.travaglini@arm.com 188313481Sgiacomo.travaglini@arm.comNote that you **cannot** use `IgnoreResult()` on an action that already 188413481Sgiacomo.travaglini@arm.comreturns `void`. Doing so will lead to ugly compiler errors. 188513481Sgiacomo.travaglini@arm.com 188613481Sgiacomo.travaglini@arm.com## Selecting an Action's Arguments ## 188713481Sgiacomo.travaglini@arm.com 188813481Sgiacomo.travaglini@arm.comSay you have a mock function `Foo()` that takes seven arguments, and 188913481Sgiacomo.travaglini@arm.comyou have a custom action that you want to invoke when `Foo()` is 189013481Sgiacomo.travaglini@arm.comcalled. Trouble is, the custom action only wants three arguments: 189113481Sgiacomo.travaglini@arm.com 189213481Sgiacomo.travaglini@arm.com``` 189313481Sgiacomo.travaglini@arm.comusing ::testing::_; 189413481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 189513481Sgiacomo.travaglini@arm.com... 189613481Sgiacomo.travaglini@arm.com MOCK_METHOD7(Foo, bool(bool visible, const string& name, int x, int y, 189713481Sgiacomo.travaglini@arm.com const map<pair<int, int>, double>& weight, 189813481Sgiacomo.travaglini@arm.com double min_weight, double max_wight)); 189913481Sgiacomo.travaglini@arm.com... 190013481Sgiacomo.travaglini@arm.com 190113481Sgiacomo.travaglini@arm.combool IsVisibleInQuadrant1(bool visible, int x, int y) { 190213481Sgiacomo.travaglini@arm.com return visible && x >= 0 && y >= 0; 190313481Sgiacomo.travaglini@arm.com} 190413481Sgiacomo.travaglini@arm.com... 190513481Sgiacomo.travaglini@arm.com 190613481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _)) 190713481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-( 190813481Sgiacomo.travaglini@arm.com``` 190913481Sgiacomo.travaglini@arm.com 191013481Sgiacomo.travaglini@arm.comTo please the compiler God, you can to define an "adaptor" that has 191113481Sgiacomo.travaglini@arm.comthe same signature as `Foo()` and calls the custom action with the 191213481Sgiacomo.travaglini@arm.comright arguments: 191313481Sgiacomo.travaglini@arm.com 191413481Sgiacomo.travaglini@arm.com``` 191513481Sgiacomo.travaglini@arm.comusing ::testing::_; 191613481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 191713481Sgiacomo.travaglini@arm.com 191813481Sgiacomo.travaglini@arm.combool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y, 191913481Sgiacomo.travaglini@arm.com const map<pair<int, int>, double>& weight, 192013481Sgiacomo.travaglini@arm.com double min_weight, double max_wight) { 192113481Sgiacomo.travaglini@arm.com return IsVisibleInQuadrant1(visible, x, y); 192213481Sgiacomo.travaglini@arm.com} 192313481Sgiacomo.travaglini@arm.com... 192413481Sgiacomo.travaglini@arm.com 192513481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _)) 192613481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works. 192713481Sgiacomo.travaglini@arm.com``` 192813481Sgiacomo.travaglini@arm.com 192913481Sgiacomo.travaglini@arm.comBut isn't this awkward? 193013481Sgiacomo.travaglini@arm.com 193113481Sgiacomo.travaglini@arm.comGoogle Mock provides a generic _action adaptor_, so you can spend your 193213481Sgiacomo.travaglini@arm.comtime minding more important business than writing your own 193313481Sgiacomo.travaglini@arm.comadaptors. Here's the syntax: 193413481Sgiacomo.travaglini@arm.com 193513481Sgiacomo.travaglini@arm.com``` 193613481Sgiacomo.travaglini@arm.com WithArgs<N1, N2, ..., Nk>(action) 193713481Sgiacomo.travaglini@arm.com``` 193813481Sgiacomo.travaglini@arm.com 193913481Sgiacomo.travaglini@arm.comcreates an action that passes the arguments of the mock function at 194013481Sgiacomo.travaglini@arm.comthe given indices (0-based) to the inner `action` and performs 194113481Sgiacomo.travaglini@arm.comit. Using `WithArgs`, our original example can be written as: 194213481Sgiacomo.travaglini@arm.com 194313481Sgiacomo.travaglini@arm.com``` 194413481Sgiacomo.travaglini@arm.comusing ::testing::_; 194513481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 194613481Sgiacomo.travaglini@arm.comusing ::testing::WithArgs; 194713481Sgiacomo.travaglini@arm.com... 194813481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _, _, _, _, _, _)) 194913481Sgiacomo.travaglini@arm.com .WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); 195013481Sgiacomo.travaglini@arm.com // No need to define your own adaptor. 195113481Sgiacomo.travaglini@arm.com``` 195213481Sgiacomo.travaglini@arm.com 195313481Sgiacomo.travaglini@arm.comFor better readability, Google Mock also gives you: 195413481Sgiacomo.travaglini@arm.com 195513481Sgiacomo.travaglini@arm.com * `WithoutArgs(action)` when the inner `action` takes _no_ argument, and 195613481Sgiacomo.travaglini@arm.com * `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes _one_ argument. 195713481Sgiacomo.travaglini@arm.com 195813481Sgiacomo.travaglini@arm.comAs you may have realized, `InvokeWithoutArgs(...)` is just syntactic 195913481Sgiacomo.travaglini@arm.comsugar for `WithoutArgs(Inovke(...))`. 196013481Sgiacomo.travaglini@arm.com 196113481Sgiacomo.travaglini@arm.comHere are more tips: 196213481Sgiacomo.travaglini@arm.com 196313481Sgiacomo.travaglini@arm.com * The inner action used in `WithArgs` and friends does not have to be `Invoke()` -- it can be anything. 196413481Sgiacomo.travaglini@arm.com * You can repeat an argument in the argument list if necessary, e.g. `WithArgs<2, 3, 3, 5>(...)`. 196513481Sgiacomo.travaglini@arm.com * You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`. 196613481Sgiacomo.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. 196713481Sgiacomo.travaglini@arm.com 196813481Sgiacomo.travaglini@arm.com## Ignoring Arguments in Action Functions ## 196913481Sgiacomo.travaglini@arm.com 197013481Sgiacomo.travaglini@arm.comThe selecting-an-action's-arguments recipe showed us one way to make a 197113481Sgiacomo.travaglini@arm.commock function and an action with incompatible argument lists fit 197213481Sgiacomo.travaglini@arm.comtogether. The downside is that wrapping the action in 197313481Sgiacomo.travaglini@arm.com`WithArgs<...>()` can get tedious for people writing the tests. 197413481Sgiacomo.travaglini@arm.com 197513481Sgiacomo.travaglini@arm.comIf you are defining a function, method, or functor to be used with 197613481Sgiacomo.travaglini@arm.com`Invoke*()`, and you are not interested in some of its arguments, an 197713481Sgiacomo.travaglini@arm.comalternative to `WithArgs` is to declare the uninteresting arguments as 197813481Sgiacomo.travaglini@arm.com`Unused`. This makes the definition less cluttered and less fragile in 197913481Sgiacomo.travaglini@arm.comcase the types of the uninteresting arguments change. It could also 198013481Sgiacomo.travaglini@arm.comincrease the chance the action function can be reused. For example, 198113481Sgiacomo.travaglini@arm.comgiven 198213481Sgiacomo.travaglini@arm.com 198313481Sgiacomo.travaglini@arm.com``` 198413481Sgiacomo.travaglini@arm.com MOCK_METHOD3(Foo, double(const string& label, double x, double y)); 198513481Sgiacomo.travaglini@arm.com MOCK_METHOD3(Bar, double(int index, double x, double y)); 198613481Sgiacomo.travaglini@arm.com``` 198713481Sgiacomo.travaglini@arm.com 198813481Sgiacomo.travaglini@arm.cominstead of 198913481Sgiacomo.travaglini@arm.com 199013481Sgiacomo.travaglini@arm.com``` 199113481Sgiacomo.travaglini@arm.comusing ::testing::_; 199213481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 199313481Sgiacomo.travaglini@arm.com 199413481Sgiacomo.travaglini@arm.comdouble DistanceToOriginWithLabel(const string& label, double x, double y) { 199513481Sgiacomo.travaglini@arm.com return sqrt(x*x + y*y); 199613481Sgiacomo.travaglini@arm.com} 199713481Sgiacomo.travaglini@arm.com 199813481Sgiacomo.travaglini@arm.comdouble DistanceToOriginWithIndex(int index, double x, double y) { 199913481Sgiacomo.travaglini@arm.com return sqrt(x*x + y*y); 200013481Sgiacomo.travaglini@arm.com} 200113481Sgiacomo.travaglini@arm.com... 200213481Sgiacomo.travaglini@arm.com 200313481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Foo("abc", _, _)) 200413481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOriginWithLabel)); 200513481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Bar(5, _, _)) 200613481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOriginWithIndex)); 200713481Sgiacomo.travaglini@arm.com``` 200813481Sgiacomo.travaglini@arm.com 200913481Sgiacomo.travaglini@arm.comyou could write 201013481Sgiacomo.travaglini@arm.com 201113481Sgiacomo.travaglini@arm.com``` 201213481Sgiacomo.travaglini@arm.comusing ::testing::_; 201313481Sgiacomo.travaglini@arm.comusing ::testing::Invoke; 201413481Sgiacomo.travaglini@arm.comusing ::testing::Unused; 201513481Sgiacomo.travaglini@arm.com 201613481Sgiacomo.travaglini@arm.comdouble DistanceToOrigin(Unused, double x, double y) { 201713481Sgiacomo.travaglini@arm.com return sqrt(x*x + y*y); 201813481Sgiacomo.travaglini@arm.com} 201913481Sgiacomo.travaglini@arm.com... 202013481Sgiacomo.travaglini@arm.com 202113481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Foo("abc", _, _)) 202213481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOrigin)); 202313481Sgiacomo.travaglini@arm.com EXEPCT_CALL(mock, Bar(5, _, _)) 202413481Sgiacomo.travaglini@arm.com .WillOnce(Invoke(DistanceToOrigin)); 202513481Sgiacomo.travaglini@arm.com``` 202613481Sgiacomo.travaglini@arm.com 202713481Sgiacomo.travaglini@arm.com## Sharing Actions ## 202813481Sgiacomo.travaglini@arm.com 202913481Sgiacomo.travaglini@arm.comJust like matchers, a Google Mock action object consists of a pointer 203013481Sgiacomo.travaglini@arm.comto a ref-counted implementation object. Therefore copying actions is 203113481Sgiacomo.travaglini@arm.comalso allowed and very efficient. When the last action that references 203213481Sgiacomo.travaglini@arm.comthe implementation object dies, the implementation object will be 203313481Sgiacomo.travaglini@arm.comdeleted. 203413481Sgiacomo.travaglini@arm.com 203513481Sgiacomo.travaglini@arm.comIf you have some complex action that you want to use again and again, 203613481Sgiacomo.travaglini@arm.comyou may not have to build it from scratch everytime. If the action 203713481Sgiacomo.travaglini@arm.comdoesn't have an internal state (i.e. if it always does the same thing 203813481Sgiacomo.travaglini@arm.comno matter how many times it has been called), you can assign it to an 203913481Sgiacomo.travaglini@arm.comaction variable and use that variable repeatedly. For example: 204013481Sgiacomo.travaglini@arm.com 204113481Sgiacomo.travaglini@arm.com``` 204213481Sgiacomo.travaglini@arm.com Action<bool(int*)> set_flag = DoAll(SetArgumentPointee<0>(5), 204313481Sgiacomo.travaglini@arm.com Return(true)); 204413481Sgiacomo.travaglini@arm.com ... use set_flag in .WillOnce() and .WillRepeatedly() ... 204513481Sgiacomo.travaglini@arm.com``` 204613481Sgiacomo.travaglini@arm.com 204713481Sgiacomo.travaglini@arm.comHowever, if the action has its own state, you may be surprised if you 204813481Sgiacomo.travaglini@arm.comshare the action object. Suppose you have an action factory 204913481Sgiacomo.travaglini@arm.com`IncrementCounter(init)` which creates an action that increments and 205013481Sgiacomo.travaglini@arm.comreturns a counter whose initial value is `init`, using two actions 205113481Sgiacomo.travaglini@arm.comcreated from the same expression and using a shared action will 205213481Sgiacomo.travaglini@arm.comexihibit different behaviors. Example: 205313481Sgiacomo.travaglini@arm.com 205413481Sgiacomo.travaglini@arm.com``` 205513481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis()) 205613481Sgiacomo.travaglini@arm.com .WillRepeatedly(IncrementCounter(0)); 205713481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat()) 205813481Sgiacomo.travaglini@arm.com .WillRepeatedly(IncrementCounter(0)); 205913481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 1. 206013481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 2. 206113481Sgiacomo.travaglini@arm.com foo.DoThat(); // Returns 1 - Blah() uses a different 206213481Sgiacomo.travaglini@arm.com // counter than Bar()'s. 206313481Sgiacomo.travaglini@arm.com``` 206413481Sgiacomo.travaglini@arm.com 206513481Sgiacomo.travaglini@arm.comversus 206613481Sgiacomo.travaglini@arm.com 206713481Sgiacomo.travaglini@arm.com``` 206813481Sgiacomo.travaglini@arm.com Action<int()> increment = IncrementCounter(0); 206913481Sgiacomo.travaglini@arm.com 207013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis()) 207113481Sgiacomo.travaglini@arm.com .WillRepeatedly(increment); 207213481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat()) 207313481Sgiacomo.travaglini@arm.com .WillRepeatedly(increment); 207413481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 1. 207513481Sgiacomo.travaglini@arm.com foo.DoThis(); // Returns 2. 207613481Sgiacomo.travaglini@arm.com foo.DoThat(); // Returns 3 - the counter is shared. 207713481Sgiacomo.travaglini@arm.com``` 207813481Sgiacomo.travaglini@arm.com 207913481Sgiacomo.travaglini@arm.com# Misc Recipes on Using Google Mock # 208013481Sgiacomo.travaglini@arm.com 208113481Sgiacomo.travaglini@arm.com## Forcing a Verification ## 208213481Sgiacomo.travaglini@arm.com 208313481Sgiacomo.travaglini@arm.comWhen it's being destoyed, your friendly mock object will automatically 208413481Sgiacomo.travaglini@arm.comverify that all expectations on it have been satisfied, and will 208513481Sgiacomo.travaglini@arm.comgenerate [Google Test](http://code.google.com/p/googletest/) failures 208613481Sgiacomo.travaglini@arm.comif not. This is convenient as it leaves you with one less thing to 208713481Sgiacomo.travaglini@arm.comworry about. That is, unless you are not sure if your mock object will 208813481Sgiacomo.travaglini@arm.combe destoyed. 208913481Sgiacomo.travaglini@arm.com 209013481Sgiacomo.travaglini@arm.comHow could it be that your mock object won't eventually be destroyed? 209113481Sgiacomo.travaglini@arm.comWell, it might be created on the heap and owned by the code you are 209213481Sgiacomo.travaglini@arm.comtesting. Suppose there's a bug in that code and it doesn't delete the 209313481Sgiacomo.travaglini@arm.commock object properly - you could end up with a passing test when 209413481Sgiacomo.travaglini@arm.comthere's actually a bug. 209513481Sgiacomo.travaglini@arm.com 209613481Sgiacomo.travaglini@arm.comUsing a heap checker is a good idea and can alleviate the concern, but 209713481Sgiacomo.travaglini@arm.comits implementation may not be 100% reliable. So, sometimes you do want 209813481Sgiacomo.travaglini@arm.comto _force_ Google Mock to verify a mock object before it is 209913481Sgiacomo.travaglini@arm.com(hopefully) destructed. You can do this with 210013481Sgiacomo.travaglini@arm.com`Mock::VerifyAndClearExpectations(&mock_object)`: 210113481Sgiacomo.travaglini@arm.com 210213481Sgiacomo.travaglini@arm.com``` 210313481Sgiacomo.travaglini@arm.comTEST(MyServerTest, ProcessesRequest) { 210413481Sgiacomo.travaglini@arm.com using ::testing::Mock; 210513481Sgiacomo.travaglini@arm.com 210613481Sgiacomo.travaglini@arm.com MockFoo* const foo = new MockFoo; 210713481Sgiacomo.travaglini@arm.com EXPECT_CALL(*foo, ...)...; 210813481Sgiacomo.travaglini@arm.com // ... other expectations ... 210913481Sgiacomo.travaglini@arm.com 211013481Sgiacomo.travaglini@arm.com // server now owns foo. 211113481Sgiacomo.travaglini@arm.com MyServer server(foo); 211213481Sgiacomo.travaglini@arm.com server.ProcessRequest(...); 211313481Sgiacomo.travaglini@arm.com 211413481Sgiacomo.travaglini@arm.com // In case that server's destructor will forget to delete foo, 211513481Sgiacomo.travaglini@arm.com // this will verify the expectations anyway. 211613481Sgiacomo.travaglini@arm.com Mock::VerifyAndClearExpectations(foo); 211713481Sgiacomo.travaglini@arm.com} // server is destroyed when it goes out of scope here. 211813481Sgiacomo.travaglini@arm.com``` 211913481Sgiacomo.travaglini@arm.com 212013481Sgiacomo.travaglini@arm.com**Tip:** The `Mock::VerifyAndClearExpectations()` function returns a 212113481Sgiacomo.travaglini@arm.com`bool` to indicate whether the verification was successful (`true` for 212213481Sgiacomo.travaglini@arm.comyes), so you can wrap that function call inside a `ASSERT_TRUE()` if 212313481Sgiacomo.travaglini@arm.comthere is no point going further when the verification has failed. 212413481Sgiacomo.travaglini@arm.com 212513481Sgiacomo.travaglini@arm.com## Using Check Points ## 212613481Sgiacomo.travaglini@arm.com 212713481Sgiacomo.travaglini@arm.comSometimes you may want to "reset" a mock object at various check 212813481Sgiacomo.travaglini@arm.compoints in your test: at each check point, you verify that all existing 212913481Sgiacomo.travaglini@arm.comexpectations on the mock object have been satisfied, and then you set 213013481Sgiacomo.travaglini@arm.comsome new expectations on it as if it's newly created. This allows you 213113481Sgiacomo.travaglini@arm.comto work with a mock object in "phases" whose sizes are each 213213481Sgiacomo.travaglini@arm.commanageable. 213313481Sgiacomo.travaglini@arm.com 213413481Sgiacomo.travaglini@arm.comOne such scenario is that in your test's `SetUp()` function, you may 213513481Sgiacomo.travaglini@arm.comwant to put the object you are testing into a certain state, with the 213613481Sgiacomo.travaglini@arm.comhelp from a mock object. Once in the desired state, you want to clear 213713481Sgiacomo.travaglini@arm.comall expectations on the mock, such that in the `TEST_F` body you can 213813481Sgiacomo.travaglini@arm.comset fresh expectations on it. 213913481Sgiacomo.travaglini@arm.com 214013481Sgiacomo.travaglini@arm.comAs you may have figured out, the `Mock::VerifyAndClearExpectations()` 214113481Sgiacomo.travaglini@arm.comfunction we saw in the previous recipe can help you here. Or, if you 214213481Sgiacomo.travaglini@arm.comare using `ON_CALL()` to set default actions on the mock object and 214313481Sgiacomo.travaglini@arm.comwant to clear the default actions as well, use 214413481Sgiacomo.travaglini@arm.com`Mock::VerifyAndClear(&mock_object)` instead. This function does what 214513481Sgiacomo.travaglini@arm.com`Mock::VerifyAndClearExpectations(&mock_object)` does and returns the 214613481Sgiacomo.travaglini@arm.comsame `bool`, **plus** it clears the `ON_CALL()` statements on 214713481Sgiacomo.travaglini@arm.com`mock_object` too. 214813481Sgiacomo.travaglini@arm.com 214913481Sgiacomo.travaglini@arm.comAnother trick you can use to achieve the same effect is to put the 215013481Sgiacomo.travaglini@arm.comexpectations in sequences and insert calls to a dummy "check-point" 215113481Sgiacomo.travaglini@arm.comfunction at specific places. Then you can verify that the mock 215213481Sgiacomo.travaglini@arm.comfunction calls do happen at the right time. For example, if you are 215313481Sgiacomo.travaglini@arm.comexercising code: 215413481Sgiacomo.travaglini@arm.com 215513481Sgiacomo.travaglini@arm.com``` 215613481Sgiacomo.travaglini@arm.comFoo(1); 215713481Sgiacomo.travaglini@arm.comFoo(2); 215813481Sgiacomo.travaglini@arm.comFoo(3); 215913481Sgiacomo.travaglini@arm.com``` 216013481Sgiacomo.travaglini@arm.com 216113481Sgiacomo.travaglini@arm.comand want to verify that `Foo(1)` and `Foo(3)` both invoke 216213481Sgiacomo.travaglini@arm.com`mock.Bar("a")`, but `Foo(2)` doesn't invoke anything. You can write: 216313481Sgiacomo.travaglini@arm.com 216413481Sgiacomo.travaglini@arm.com``` 216513481Sgiacomo.travaglini@arm.comusing ::testing::MockFunction; 216613481Sgiacomo.travaglini@arm.com 216713481Sgiacomo.travaglini@arm.comTEST(FooTest, InvokesBarCorrectly) { 216813481Sgiacomo.travaglini@arm.com MyMock mock; 216913481Sgiacomo.travaglini@arm.com // Class MockFunction<F> has exactly one mock method. It is named 217013481Sgiacomo.travaglini@arm.com // Call() and has type F. 217113481Sgiacomo.travaglini@arm.com MockFunction<void(string check_point_name)> check; 217213481Sgiacomo.travaglini@arm.com { 217313481Sgiacomo.travaglini@arm.com InSequence s; 217413481Sgiacomo.travaglini@arm.com 217513481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Bar("a")); 217613481Sgiacomo.travaglini@arm.com EXPECT_CALL(check, Call("1")); 217713481Sgiacomo.travaglini@arm.com EXPECT_CALL(check, Call("2")); 217813481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Bar("a")); 217913481Sgiacomo.travaglini@arm.com } 218013481Sgiacomo.travaglini@arm.com Foo(1); 218113481Sgiacomo.travaglini@arm.com check.Call("1"); 218213481Sgiacomo.travaglini@arm.com Foo(2); 218313481Sgiacomo.travaglini@arm.com check.Call("2"); 218413481Sgiacomo.travaglini@arm.com Foo(3); 218513481Sgiacomo.travaglini@arm.com} 218613481Sgiacomo.travaglini@arm.com``` 218713481Sgiacomo.travaglini@arm.com 218813481Sgiacomo.travaglini@arm.comThe expectation spec says that the first `Bar("a")` must happen before 218913481Sgiacomo.travaglini@arm.comcheck point "1", the second `Bar("a")` must happen after check point "2", 219013481Sgiacomo.travaglini@arm.comand nothing should happen between the two check points. The explicit 219113481Sgiacomo.travaglini@arm.comcheck points make it easy to tell which `Bar("a")` is called by which 219213481Sgiacomo.travaglini@arm.comcall to `Foo()`. 219313481Sgiacomo.travaglini@arm.com 219413481Sgiacomo.travaglini@arm.com## Mocking Destructors ## 219513481Sgiacomo.travaglini@arm.com 219613481Sgiacomo.travaglini@arm.comSometimes you want to make sure a mock object is destructed at the 219713481Sgiacomo.travaglini@arm.comright time, e.g. after `bar->A()` is called but before `bar->B()` is 219813481Sgiacomo.travaglini@arm.comcalled. We already know that you can specify constraints on the order 219913481Sgiacomo.travaglini@arm.comof mock function calls, so all we need to do is to mock the destructor 220013481Sgiacomo.travaglini@arm.comof the mock function. 220113481Sgiacomo.travaglini@arm.com 220213481Sgiacomo.travaglini@arm.comThis sounds simple, except for one problem: a destructor is a special 220313481Sgiacomo.travaglini@arm.comfunction with special syntax and special semantics, and the 220413481Sgiacomo.travaglini@arm.com`MOCK_METHOD0` macro doesn't work for it: 220513481Sgiacomo.travaglini@arm.com 220613481Sgiacomo.travaglini@arm.com``` 220713481Sgiacomo.travaglini@arm.com MOCK_METHOD0(~MockFoo, void()); // Won't compile! 220813481Sgiacomo.travaglini@arm.com``` 220913481Sgiacomo.travaglini@arm.com 221013481Sgiacomo.travaglini@arm.comThe good news is that you can use a simple pattern to achieve the same 221113481Sgiacomo.travaglini@arm.comeffect. First, add a mock function `Die()` to your mock class and call 221213481Sgiacomo.travaglini@arm.comit in the destructor, like this: 221313481Sgiacomo.travaglini@arm.com 221413481Sgiacomo.travaglini@arm.com``` 221513481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 221613481Sgiacomo.travaglini@arm.com ... 221713481Sgiacomo.travaglini@arm.com // Add the following two lines to the mock class. 221813481Sgiacomo.travaglini@arm.com MOCK_METHOD0(Die, void()); 221913481Sgiacomo.travaglini@arm.com virtual ~MockFoo() { Die(); } 222013481Sgiacomo.travaglini@arm.com}; 222113481Sgiacomo.travaglini@arm.com``` 222213481Sgiacomo.travaglini@arm.com 222313481Sgiacomo.travaglini@arm.com(If the name `Die()` clashes with an existing symbol, choose another 222413481Sgiacomo.travaglini@arm.comname.) Now, we have translated the problem of testing when a `MockFoo` 222513481Sgiacomo.travaglini@arm.comobject dies to testing when its `Die()` method is called: 222613481Sgiacomo.travaglini@arm.com 222713481Sgiacomo.travaglini@arm.com``` 222813481Sgiacomo.travaglini@arm.com MockFoo* foo = new MockFoo; 222913481Sgiacomo.travaglini@arm.com MockBar* bar = new MockBar; 223013481Sgiacomo.travaglini@arm.com ... 223113481Sgiacomo.travaglini@arm.com { 223213481Sgiacomo.travaglini@arm.com InSequence s; 223313481Sgiacomo.travaglini@arm.com 223413481Sgiacomo.travaglini@arm.com // Expects *foo to die after bar->A() and before bar->B(). 223513481Sgiacomo.travaglini@arm.com EXPECT_CALL(*bar, A()); 223613481Sgiacomo.travaglini@arm.com EXPECT_CALL(*foo, Die()); 223713481Sgiacomo.travaglini@arm.com EXPECT_CALL(*bar, B()); 223813481Sgiacomo.travaglini@arm.com } 223913481Sgiacomo.travaglini@arm.com``` 224013481Sgiacomo.travaglini@arm.com 224113481Sgiacomo.travaglini@arm.comAnd that's that. 224213481Sgiacomo.travaglini@arm.com 224313481Sgiacomo.travaglini@arm.com## Using Google Mock and Threads ## 224413481Sgiacomo.travaglini@arm.com 224513481Sgiacomo.travaglini@arm.com**IMPORTANT NOTE:** What we describe in this recipe is **NOT** true yet, 224613481Sgiacomo.travaglini@arm.comas Google Mock is not currently thread-safe. However, all we need to 224713481Sgiacomo.travaglini@arm.commake it thread-safe is to implement some synchronization operations in 224813481Sgiacomo.travaglini@arm.com`<gtest/internal/gtest-port.h>` - and then the information below will 224913481Sgiacomo.travaglini@arm.combecome true. 225013481Sgiacomo.travaglini@arm.com 225113481Sgiacomo.travaglini@arm.comIn a **unit** test, it's best if you could isolate and test a piece of 225213481Sgiacomo.travaglini@arm.comcode in a single-threaded context. That avoids race conditions and 225313481Sgiacomo.travaglini@arm.comdead locks, and makes debugging your test much easier. 225413481Sgiacomo.travaglini@arm.com 225513481Sgiacomo.travaglini@arm.comYet many programs are multi-threaded, and sometimes to test something 225613481Sgiacomo.travaglini@arm.comwe need to pound on it from more than one thread. Google Mock works 225713481Sgiacomo.travaglini@arm.comfor this purpose too. 225813481Sgiacomo.travaglini@arm.com 225913481Sgiacomo.travaglini@arm.comRemember the steps for using a mock: 226013481Sgiacomo.travaglini@arm.com 226113481Sgiacomo.travaglini@arm.com 1. Create a mock object `foo`. 226213481Sgiacomo.travaglini@arm.com 1. Set its default actions and expectations using `ON_CALL()` and `EXPECT_CALL()`. 226313481Sgiacomo.travaglini@arm.com 1. The code under test calls methods of `foo`. 226413481Sgiacomo.travaglini@arm.com 1. Optionally, verify and reset the mock. 226513481Sgiacomo.travaglini@arm.com 1. Destroy the mock yourself, or let the code under test destroy it. The destructor will automatically verify it. 226613481Sgiacomo.travaglini@arm.com 226713481Sgiacomo.travaglini@arm.comIf you follow the following simple rules, your mocks and threads can 226813481Sgiacomo.travaglini@arm.comlive happily togeter: 226913481Sgiacomo.travaglini@arm.com 227013481Sgiacomo.travaglini@arm.com * Execute your _test code_ (as opposed to the code being tested) in _one_ thread. This makes your test easy to follow. 227113481Sgiacomo.travaglini@arm.com * Obviously, you can do step #1 without locking. 227213481Sgiacomo.travaglini@arm.com * When doing step #2 and #5, make sure no other thread is accessing `foo`. Obvious too, huh? 227313481Sgiacomo.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. 227413481Sgiacomo.travaglini@arm.com 227513481Sgiacomo.travaglini@arm.comIf you violate the rules (for example, if you set expectations on a 227613481Sgiacomo.travaglini@arm.commock while another thread is calling its methods), you get undefined 227713481Sgiacomo.travaglini@arm.combehavior. That's not fun, so don't do it. 227813481Sgiacomo.travaglini@arm.com 227913481Sgiacomo.travaglini@arm.comGoogle Mock guarantees that the action for a mock function is done in 228013481Sgiacomo.travaglini@arm.comthe same thread that called the mock function. For example, in 228113481Sgiacomo.travaglini@arm.com 228213481Sgiacomo.travaglini@arm.com``` 228313481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(1)) 228413481Sgiacomo.travaglini@arm.com .WillOnce(action1); 228513481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(2)) 228613481Sgiacomo.travaglini@arm.com .WillOnce(action2); 228713481Sgiacomo.travaglini@arm.com``` 228813481Sgiacomo.travaglini@arm.com 228913481Sgiacomo.travaglini@arm.comif `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, 229013481Sgiacomo.travaglini@arm.comGoogle Mock will execute `action1` in thread 1 and `action2` in thread 229113481Sgiacomo.travaglini@arm.com2. 229213481Sgiacomo.travaglini@arm.com 229313481Sgiacomo.travaglini@arm.comGoogle Mock does _not_ impose a sequence on actions performed in 229413481Sgiacomo.travaglini@arm.comdifferent threads (doing so may create deadlocks as the actions may 229513481Sgiacomo.travaglini@arm.comneed to cooperate). This means that the execution of `action1` and 229613481Sgiacomo.travaglini@arm.com`action2` in the above example _may_ interleave. If this is a problem, 229713481Sgiacomo.travaglini@arm.comyou should add proper synchronization logic to `action1` and `action2` 229813481Sgiacomo.travaglini@arm.comto make the test thread-safe. 229913481Sgiacomo.travaglini@arm.com 230013481Sgiacomo.travaglini@arm.com 230113481Sgiacomo.travaglini@arm.comAlso, remember that `DefaultValue<T>` is a global resource that 230213481Sgiacomo.travaglini@arm.compotentially affects _all_ living mock objects in your 230313481Sgiacomo.travaglini@arm.comprogram. Naturally, you won't want to mess with it from multiple 230413481Sgiacomo.travaglini@arm.comthreads or when there still are mocks in action. 230513481Sgiacomo.travaglini@arm.com 230613481Sgiacomo.travaglini@arm.com## Controlling How Much Information Google Mock Prints ## 230713481Sgiacomo.travaglini@arm.com 230813481Sgiacomo.travaglini@arm.comWhen Google Mock sees something that has the potential of being an 230913481Sgiacomo.travaglini@arm.comerror (e.g. a mock function with no expectation is called, a.k.a. an 231013481Sgiacomo.travaglini@arm.comuninteresting call, which is allowed but perhaps you forgot to 231113481Sgiacomo.travaglini@arm.comexplicitly ban the call), it prints some warning messages, including 231213481Sgiacomo.travaglini@arm.comthe arguments of the function and the return value. Hopefully this 231313481Sgiacomo.travaglini@arm.comwill remind you to take a look and see if there is indeed a problem. 231413481Sgiacomo.travaglini@arm.com 231513481Sgiacomo.travaglini@arm.comSometimes you are confident that your tests are correct and may not 231613481Sgiacomo.travaglini@arm.comappreciate such friendly messages. Some other times, you are debugging 231713481Sgiacomo.travaglini@arm.comyour tests or learning about the behavior of the code you are testing, 231813481Sgiacomo.travaglini@arm.comand wish you could observe every mock call that happens (including 231913481Sgiacomo.travaglini@arm.comargument values and the return value). Clearly, one size doesn't fit 232013481Sgiacomo.travaglini@arm.comall. 232113481Sgiacomo.travaglini@arm.com 232213481Sgiacomo.travaglini@arm.comYou can control how much Google Mock tells you using the 232313481Sgiacomo.travaglini@arm.com`--gmock_verbose=LEVEL` command-line flag, where `LEVEL` is a string 232413481Sgiacomo.travaglini@arm.comwith three possible values: 232513481Sgiacomo.travaglini@arm.com 232613481Sgiacomo.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. 232713481Sgiacomo.travaglini@arm.com * `warning`: Google Mock will print both warnings and errors (less verbose). This is the default. 232813481Sgiacomo.travaglini@arm.com * `error`: Google Mock will print errors only (least verbose). 232913481Sgiacomo.travaglini@arm.com 233013481Sgiacomo.travaglini@arm.comAlternatively, you can adjust the value of that flag from within your 233113481Sgiacomo.travaglini@arm.comtests like so: 233213481Sgiacomo.travaglini@arm.com 233313481Sgiacomo.travaglini@arm.com``` 233413481Sgiacomo.travaglini@arm.com ::testing::FLAGS_gmock_verbose = "error"; 233513481Sgiacomo.travaglini@arm.com``` 233613481Sgiacomo.travaglini@arm.com 233713481Sgiacomo.travaglini@arm.comNow, judiciously use the right flag to enable Google Mock serve you better! 233813481Sgiacomo.travaglini@arm.com 233913481Sgiacomo.travaglini@arm.com## Running Tests in Emacs ## 234013481Sgiacomo.travaglini@arm.com 234113481Sgiacomo.travaglini@arm.comIf you build and run your tests in Emacs, the source file locations of 234213481Sgiacomo.travaglini@arm.comGoogle Mock and [Google Test](http://code.google.com/p/googletest/) 234313481Sgiacomo.travaglini@arm.comerrors will be highlighted. Just press `<Enter>` on one of them and 234413481Sgiacomo.travaglini@arm.comyou'll be taken to the offending line. Or, you can just type `C-x `` 234513481Sgiacomo.travaglini@arm.comto jump to the next error. 234613481Sgiacomo.travaglini@arm.com 234713481Sgiacomo.travaglini@arm.comTo make it even easier, you can add the following lines to your 234813481Sgiacomo.travaglini@arm.com`~/.emacs` file: 234913481Sgiacomo.travaglini@arm.com 235013481Sgiacomo.travaglini@arm.com``` 235113481Sgiacomo.travaglini@arm.com(global-set-key "\M-m" 'compile) ; m is for make 235213481Sgiacomo.travaglini@arm.com(global-set-key [M-down] 'next-error) 235313481Sgiacomo.travaglini@arm.com(global-set-key [M-up] '(lambda () (interactive) (next-error -1))) 235413481Sgiacomo.travaglini@arm.com``` 235513481Sgiacomo.travaglini@arm.com 235613481Sgiacomo.travaglini@arm.comThen you can type `M-m` to start a build, or `M-up`/`M-down` to move 235713481Sgiacomo.travaglini@arm.comback and forth between errors. 235813481Sgiacomo.travaglini@arm.com 235913481Sgiacomo.travaglini@arm.com## Fusing Google Mock Source Files ## 236013481Sgiacomo.travaglini@arm.com 236113481Sgiacomo.travaglini@arm.comGoogle Mock's implementation consists of dozens of files (excluding 236213481Sgiacomo.travaglini@arm.comits own tests). Sometimes you may want them to be packaged up in 236313481Sgiacomo.travaglini@arm.comfewer files instead, such that you can easily copy them to a new 236413481Sgiacomo.travaglini@arm.commachine and start hacking there. For this we provide an experimental 236513481Sgiacomo.travaglini@arm.comPython script `fuse_gmock_files.py` in the `scripts/` directory 236613481Sgiacomo.travaglini@arm.com(starting with release 1.2.0). Assuming you have Python 2.4 or above 236713481Sgiacomo.travaglini@arm.cominstalled on your machine, just go to that directory and run 236813481Sgiacomo.travaglini@arm.com``` 236913481Sgiacomo.travaglini@arm.compython fuse_gmock_files.py OUTPUT_DIR 237013481Sgiacomo.travaglini@arm.com``` 237113481Sgiacomo.travaglini@arm.com 237213481Sgiacomo.travaglini@arm.comand you should see an `OUTPUT_DIR` directory being created with files 237313481Sgiacomo.travaglini@arm.com`gtest/gtest.h`, `gmock/gmock.h`, and `gmock-gtest-all.cc` in it. 237413481Sgiacomo.travaglini@arm.comThese three files contain everything you need to use Google Mock (and 237513481Sgiacomo.travaglini@arm.comGoogle Test). Just copy them to anywhere you want and you are ready 237613481Sgiacomo.travaglini@arm.comto write tests and use mocks. You can use the 237713481Sgiacomo.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 237813481Sgiacomo.travaglini@arm.comagainst them. 237913481Sgiacomo.travaglini@arm.com 238013481Sgiacomo.travaglini@arm.com# Extending Google Mock # 238113481Sgiacomo.travaglini@arm.com 238213481Sgiacomo.travaglini@arm.com## Writing New Matchers Quickly ## 238313481Sgiacomo.travaglini@arm.com 238413481Sgiacomo.travaglini@arm.comThe `MATCHER*` family of macros can be used to define custom matchers 238513481Sgiacomo.travaglini@arm.comeasily. The syntax: 238613481Sgiacomo.travaglini@arm.com 238713481Sgiacomo.travaglini@arm.com``` 238813481Sgiacomo.travaglini@arm.comMATCHER(name, "description string") { statements; } 238913481Sgiacomo.travaglini@arm.com``` 239013481Sgiacomo.travaglini@arm.com 239113481Sgiacomo.travaglini@arm.comwill define a matcher with the given name that executes the 239213481Sgiacomo.travaglini@arm.comstatements, which must return a `bool` to indicate if the match 239313481Sgiacomo.travaglini@arm.comsucceeds. Inside the statements, you can refer to the value being 239413481Sgiacomo.travaglini@arm.commatched by `arg`, and refer to its type by `arg_type`. 239513481Sgiacomo.travaglini@arm.com 239613481Sgiacomo.travaglini@arm.comThe description string documents what the matcher does, and is used to 239713481Sgiacomo.travaglini@arm.comgenerate the failure message when the match fails. Since a 239813481Sgiacomo.travaglini@arm.com`MATCHER()` is usually defined in a header file shared by multiple C++ 239913481Sgiacomo.travaglini@arm.comsource files, we require the description to be a C-string _literal_ to 240013481Sgiacomo.travaglini@arm.comavoid possible side effects. It can be empty (`""`), in which case 240113481Sgiacomo.travaglini@arm.comGoogle Mock will use the sequence of words in the matcher name as the 240213481Sgiacomo.travaglini@arm.comdescription. 240313481Sgiacomo.travaglini@arm.com 240413481Sgiacomo.travaglini@arm.comFor example: 240513481Sgiacomo.travaglini@arm.com``` 240613481Sgiacomo.travaglini@arm.comMATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; } 240713481Sgiacomo.travaglini@arm.com``` 240813481Sgiacomo.travaglini@arm.comallows you to write 240913481Sgiacomo.travaglini@arm.com``` 241013481Sgiacomo.travaglini@arm.com // Expects mock_foo.Bar(n) to be called where n is divisible by 7. 241113481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7())); 241213481Sgiacomo.travaglini@arm.com``` 241313481Sgiacomo.travaglini@arm.comor, 241413481Sgiacomo.travaglini@arm.com``` 241513481Sgiacomo.travaglini@arm.com // Verifies that the value of some_expression is divisible by 7. 241613481Sgiacomo.travaglini@arm.com EXPECT_THAT(some_expression, IsDivisibleBy7()); 241713481Sgiacomo.travaglini@arm.com``` 241813481Sgiacomo.travaglini@arm.comIf the above assertion fails, it will print something like: 241913481Sgiacomo.travaglini@arm.com``` 242013481Sgiacomo.travaglini@arm.com Value of: some_expression 242113481Sgiacomo.travaglini@arm.com Expected: is divisible by 7 242213481Sgiacomo.travaglini@arm.com Actual: 27 242313481Sgiacomo.travaglini@arm.com``` 242413481Sgiacomo.travaglini@arm.comwhere the description `"is divisible by 7"` is automatically calculated from the 242513481Sgiacomo.travaglini@arm.commatcher name `IsDivisibleBy7`. 242613481Sgiacomo.travaglini@arm.com 242713481Sgiacomo.travaglini@arm.comOptionally, you can stream additional information to a hidden argument 242813481Sgiacomo.travaglini@arm.comnamed `result_listener` to explain the match result. For example, a 242913481Sgiacomo.travaglini@arm.combetter definition of `IsDivisibleBy7` is: 243013481Sgiacomo.travaglini@arm.com``` 243113481Sgiacomo.travaglini@arm.comMATCHER(IsDivisibleBy7, "") { 243213481Sgiacomo.travaglini@arm.com if ((arg % 7) == 0) 243313481Sgiacomo.travaglini@arm.com return true; 243413481Sgiacomo.travaglini@arm.com 243513481Sgiacomo.travaglini@arm.com *result_listener << "the remainder is " << (arg % 7); 243613481Sgiacomo.travaglini@arm.com return false; 243713481Sgiacomo.travaglini@arm.com} 243813481Sgiacomo.travaglini@arm.com``` 243913481Sgiacomo.travaglini@arm.com 244013481Sgiacomo.travaglini@arm.comWith this definition, the above assertion will give a better message: 244113481Sgiacomo.travaglini@arm.com``` 244213481Sgiacomo.travaglini@arm.com Value of: some_expression 244313481Sgiacomo.travaglini@arm.com Expected: is divisible by 7 244413481Sgiacomo.travaglini@arm.com Actual: 27 (the remainder is 6) 244513481Sgiacomo.travaglini@arm.com``` 244613481Sgiacomo.travaglini@arm.com 244713481Sgiacomo.travaglini@arm.comYou should let `MatchAndExplain()` print _any additional information_ 244813481Sgiacomo.travaglini@arm.comthat can help a user understand the match result. Note that it should 244913481Sgiacomo.travaglini@arm.comexplain why the match succeeds in case of a success (unless it's 245013481Sgiacomo.travaglini@arm.comobvious) - this is useful when the matcher is used inside 245113481Sgiacomo.travaglini@arm.com`Not()`. There is no need to print the argument value itself, as 245213481Sgiacomo.travaglini@arm.comGoogle Mock already prints it for you. 245313481Sgiacomo.travaglini@arm.com 245413481Sgiacomo.travaglini@arm.com**Notes:** 245513481Sgiacomo.travaglini@arm.com 245613481Sgiacomo.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. 245713481Sgiacomo.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. 245813481Sgiacomo.travaglini@arm.com 245913481Sgiacomo.travaglini@arm.com## Writing New Parameterized Matchers Quickly ## 246013481Sgiacomo.travaglini@arm.com 246113481Sgiacomo.travaglini@arm.comSometimes you'll want to define a matcher that has parameters. For that you 246213481Sgiacomo.travaglini@arm.comcan use the macro: 246313481Sgiacomo.travaglini@arm.com``` 246413481Sgiacomo.travaglini@arm.comMATCHER_P(name, param_name, "description string") { statements; } 246513481Sgiacomo.travaglini@arm.com``` 246613481Sgiacomo.travaglini@arm.com 246713481Sgiacomo.travaglini@arm.comFor example: 246813481Sgiacomo.travaglini@arm.com``` 246913481Sgiacomo.travaglini@arm.comMATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; } 247013481Sgiacomo.travaglini@arm.com``` 247113481Sgiacomo.travaglini@arm.comwill allow you to write: 247213481Sgiacomo.travaglini@arm.com``` 247313481Sgiacomo.travaglini@arm.com EXPECT_THAT(Blah("a"), HasAbsoluteValue(n)); 247413481Sgiacomo.travaglini@arm.com``` 247513481Sgiacomo.travaglini@arm.comwhich may lead to this message (assuming `n` is 10): 247613481Sgiacomo.travaglini@arm.com``` 247713481Sgiacomo.travaglini@arm.com Value of: Blah("a") 247813481Sgiacomo.travaglini@arm.com Expected: has absolute value 10 247913481Sgiacomo.travaglini@arm.com Actual: -9 248013481Sgiacomo.travaglini@arm.com``` 248113481Sgiacomo.travaglini@arm.com 248213481Sgiacomo.travaglini@arm.comNote that both the matcher description and its parameter are 248313481Sgiacomo.travaglini@arm.comprinted, making the message human-friendly. 248413481Sgiacomo.travaglini@arm.com 248513481Sgiacomo.travaglini@arm.comIn the matcher definition body, you can write `foo_type` to 248613481Sgiacomo.travaglini@arm.comreference the type of a parameter named `foo`. For example, in the 248713481Sgiacomo.travaglini@arm.combody of `MATCHER_P(HasAbsoluteValue, value)` above, you can write 248813481Sgiacomo.travaglini@arm.com`value_type` to refer to the type of `value`. 248913481Sgiacomo.travaglini@arm.com 249013481Sgiacomo.travaglini@arm.comGoogle Mock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to 249113481Sgiacomo.travaglini@arm.com`MATCHER_P10` to support multi-parameter matchers: 249213481Sgiacomo.travaglini@arm.com``` 249313481Sgiacomo.travaglini@arm.comMATCHER_Pk(name, param_1, ..., param_k, "description string") { statements; } 249413481Sgiacomo.travaglini@arm.com``` 249513481Sgiacomo.travaglini@arm.com 249613481Sgiacomo.travaglini@arm.comPlease note that the custom description string is for a particular 249713481Sgiacomo.travaglini@arm.com**instance** of the matcher, where the parameters have been bound to 249813481Sgiacomo.travaglini@arm.comactual values. Therefore usually you'll want the parameter values to 249913481Sgiacomo.travaglini@arm.combe part of the description. Google Mock lets you do that using 250013481Sgiacomo.travaglini@arm.comPython-style interpolations. The following syntaxes are supported 250113481Sgiacomo.travaglini@arm.comcurrently: 250213481Sgiacomo.travaglini@arm.com 250313481Sgiacomo.travaglini@arm.com| `%%` | a single `%` character | 250413481Sgiacomo.travaglini@arm.com|:-----|:-----------------------| 250513481Sgiacomo.travaglini@arm.com| `%(*)s` | all parameters of the matcher printed as a tuple | 250613481Sgiacomo.travaglini@arm.com| `%(foo)s` | value of the matcher parameter named `foo` | 250713481Sgiacomo.travaglini@arm.com 250813481Sgiacomo.travaglini@arm.comFor example, 250913481Sgiacomo.travaglini@arm.com``` 251013481Sgiacomo.travaglini@arm.com MATCHER_P2(InClosedRange, low, hi, "is in range [%(low)s, %(hi)s]") { 251113481Sgiacomo.travaglini@arm.com return low <= arg && arg <= hi; 251213481Sgiacomo.travaglini@arm.com } 251313481Sgiacomo.travaglini@arm.com ... 251413481Sgiacomo.travaglini@arm.com EXPECT_THAT(3, InClosedRange(4, 6)); 251513481Sgiacomo.travaglini@arm.com``` 251613481Sgiacomo.travaglini@arm.comwould generate a failure that contains the message: 251713481Sgiacomo.travaglini@arm.com``` 251813481Sgiacomo.travaglini@arm.com Expected: is in range [4, 6] 251913481Sgiacomo.travaglini@arm.com``` 252013481Sgiacomo.travaglini@arm.com 252113481Sgiacomo.travaglini@arm.comIf you specify `""` as the description, the failure message will 252213481Sgiacomo.travaglini@arm.comcontain the sequence of words in the matcher name followed by the 252313481Sgiacomo.travaglini@arm.comparameter values printed as a tuple. For example, 252413481Sgiacomo.travaglini@arm.com``` 252513481Sgiacomo.travaglini@arm.com MATCHER_P2(InClosedRange, low, hi, "") { ... } 252613481Sgiacomo.travaglini@arm.com ... 252713481Sgiacomo.travaglini@arm.com EXPECT_THAT(3, InClosedRange(4, 6)); 252813481Sgiacomo.travaglini@arm.com``` 252913481Sgiacomo.travaglini@arm.comwould generate a failure that contains the text: 253013481Sgiacomo.travaglini@arm.com``` 253113481Sgiacomo.travaglini@arm.com Expected: in closed range (4, 6) 253213481Sgiacomo.travaglini@arm.com``` 253313481Sgiacomo.travaglini@arm.com 253413481Sgiacomo.travaglini@arm.comFor the purpose of typing, you can view 253513481Sgiacomo.travaglini@arm.com``` 253613481Sgiacomo.travaglini@arm.comMATCHER_Pk(Foo, p1, ..., pk, "description string") { ... } 253713481Sgiacomo.travaglini@arm.com``` 253813481Sgiacomo.travaglini@arm.comas shorthand for 253913481Sgiacomo.travaglini@arm.com``` 254013481Sgiacomo.travaglini@arm.comtemplate <typename p1_type, ..., typename pk_type> 254113481Sgiacomo.travaglini@arm.comFooMatcherPk<p1_type, ..., pk_type> 254213481Sgiacomo.travaglini@arm.comFoo(p1_type p1, ..., pk_type pk) { ... } 254313481Sgiacomo.travaglini@arm.com``` 254413481Sgiacomo.travaglini@arm.com 254513481Sgiacomo.travaglini@arm.comWhen you write `Foo(v1, ..., vk)`, the compiler infers the types of 254613481Sgiacomo.travaglini@arm.comthe parameters `v1`, ..., and `vk` for you. If you are not happy with 254713481Sgiacomo.travaglini@arm.comthe result of the type inference, you can specify the types by 254813481Sgiacomo.travaglini@arm.comexplicitly instantiating the template, as in `Foo<long, bool>(5, false)`. 254913481Sgiacomo.travaglini@arm.comAs said earlier, you don't get to (or need to) specify 255013481Sgiacomo.travaglini@arm.com`arg_type` as that's determined by the context in which the matcher 255113481Sgiacomo.travaglini@arm.comis used. 255213481Sgiacomo.travaglini@arm.com 255313481Sgiacomo.travaglini@arm.comYou can assign the result of expression `Foo(p1, ..., pk)` to a 255413481Sgiacomo.travaglini@arm.comvariable of type `FooMatcherPk<p1_type, ..., pk_type>`. This can be 255513481Sgiacomo.travaglini@arm.comuseful when composing matchers. Matchers that don't have a parameter 255613481Sgiacomo.travaglini@arm.comor have only one parameter have special types: you can assign `Foo()` 255713481Sgiacomo.travaglini@arm.comto a `FooMatcher`-typed variable, and assign `Foo(p)` to a 255813481Sgiacomo.travaglini@arm.com`FooMatcherP<p_type>`-typed variable. 255913481Sgiacomo.travaglini@arm.com 256013481Sgiacomo.travaglini@arm.comWhile you can instantiate a matcher template with reference types, 256113481Sgiacomo.travaglini@arm.compassing the parameters by pointer usually makes your code more 256213481Sgiacomo.travaglini@arm.comreadable. If, however, you still want to pass a parameter by 256313481Sgiacomo.travaglini@arm.comreference, be aware that in the failure message generated by the 256413481Sgiacomo.travaglini@arm.commatcher you will see the value of the referenced object but not its 256513481Sgiacomo.travaglini@arm.comaddress. 256613481Sgiacomo.travaglini@arm.com 256713481Sgiacomo.travaglini@arm.comYou can overload matchers with different numbers of parameters: 256813481Sgiacomo.travaglini@arm.com``` 256913481Sgiacomo.travaglini@arm.comMATCHER_P(Blah, a, "description string 1") { ... } 257013481Sgiacomo.travaglini@arm.comMATCHER_P2(Blah, a, b, "description string 2") { ... } 257113481Sgiacomo.travaglini@arm.com``` 257213481Sgiacomo.travaglini@arm.com 257313481Sgiacomo.travaglini@arm.comWhile it's tempting to always use the `MATCHER*` macros when defining 257413481Sgiacomo.travaglini@arm.coma new matcher, you should also consider implementing 257513481Sgiacomo.travaglini@arm.com`MatcherInterface` or using `MakePolymorphicMatcher()` instead (see 257613481Sgiacomo.travaglini@arm.comthe recipes that follow), especially if you need to use the matcher a 257713481Sgiacomo.travaglini@arm.comlot. While these approaches require more work, they give you more 257813481Sgiacomo.travaglini@arm.comcontrol on the types of the value being matched and the matcher 257913481Sgiacomo.travaglini@arm.comparameters, which in general leads to better compiler error messages 258013481Sgiacomo.travaglini@arm.comthat pay off in the long run. They also allow overloading matchers 258113481Sgiacomo.travaglini@arm.combased on parameter types (as opposed to just based on the number of 258213481Sgiacomo.travaglini@arm.comparameters). 258313481Sgiacomo.travaglini@arm.com 258413481Sgiacomo.travaglini@arm.com## Writing New Monomorphic Matchers ## 258513481Sgiacomo.travaglini@arm.com 258613481Sgiacomo.travaglini@arm.comA matcher of argument type `T` implements 258713481Sgiacomo.travaglini@arm.com`::testing::MatcherInterface<T>` and does two things: it tests whether a 258813481Sgiacomo.travaglini@arm.comvalue of type `T` matches the matcher, and can describe what kind of 258913481Sgiacomo.travaglini@arm.comvalues it matches. The latter ability is used for generating readable 259013481Sgiacomo.travaglini@arm.comerror messages when expectations are violated. 259113481Sgiacomo.travaglini@arm.com 259213481Sgiacomo.travaglini@arm.comThe interface looks like this: 259313481Sgiacomo.travaglini@arm.com 259413481Sgiacomo.travaglini@arm.com``` 259513481Sgiacomo.travaglini@arm.comclass MatchResultListener { 259613481Sgiacomo.travaglini@arm.com public: 259713481Sgiacomo.travaglini@arm.com ... 259813481Sgiacomo.travaglini@arm.com // Streams x to the underlying ostream; does nothing if the ostream 259913481Sgiacomo.travaglini@arm.com // is NULL. 260013481Sgiacomo.travaglini@arm.com template <typename T> 260113481Sgiacomo.travaglini@arm.com MatchResultListener& operator<<(const T& x); 260213481Sgiacomo.travaglini@arm.com 260313481Sgiacomo.travaglini@arm.com // Returns the underlying ostream. 260413481Sgiacomo.travaglini@arm.com ::std::ostream* stream(); 260513481Sgiacomo.travaglini@arm.com}; 260613481Sgiacomo.travaglini@arm.com 260713481Sgiacomo.travaglini@arm.comtemplate <typename T> 260813481Sgiacomo.travaglini@arm.comclass MatcherInterface { 260913481Sgiacomo.travaglini@arm.com public: 261013481Sgiacomo.travaglini@arm.com virtual ~MatcherInterface(); 261113481Sgiacomo.travaglini@arm.com 261213481Sgiacomo.travaglini@arm.com // Returns true iff the matcher matches x; also explains the match 261313481Sgiacomo.travaglini@arm.com // result to 'listener'. 261413481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0; 261513481Sgiacomo.travaglini@arm.com 261613481Sgiacomo.travaglini@arm.com // Describes this matcher to an ostream. 261713481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const = 0; 261813481Sgiacomo.travaglini@arm.com 261913481Sgiacomo.travaglini@arm.com // Describes the negation of this matcher to an ostream. 262013481Sgiacomo.travaglini@arm.com virtual void DescribeNegationTo(::std::ostream* os) const; 262113481Sgiacomo.travaglini@arm.com}; 262213481Sgiacomo.travaglini@arm.com``` 262313481Sgiacomo.travaglini@arm.com 262413481Sgiacomo.travaglini@arm.comIf you need a custom matcher but `Truly()` is not a good option (for 262513481Sgiacomo.travaglini@arm.comexample, you may not be happy with the way `Truly(predicate)` 262613481Sgiacomo.travaglini@arm.comdescribes itself, or you may want your matcher to be polymorphic as 262713481Sgiacomo.travaglini@arm.com`Eq(value)` is), you can define a matcher to do whatever you want in 262813481Sgiacomo.travaglini@arm.comtwo steps: first implement the matcher interface, and then define a 262913481Sgiacomo.travaglini@arm.comfactory function to create a matcher instance. The second step is not 263013481Sgiacomo.travaglini@arm.comstrictly needed but it makes the syntax of using the matcher nicer. 263113481Sgiacomo.travaglini@arm.com 263213481Sgiacomo.travaglini@arm.comFor example, you can define a matcher to test whether an `int` is 263313481Sgiacomo.travaglini@arm.comdivisible by 7 and then use it like this: 263413481Sgiacomo.travaglini@arm.com``` 263513481Sgiacomo.travaglini@arm.comusing ::testing::MakeMatcher; 263613481Sgiacomo.travaglini@arm.comusing ::testing::Matcher; 263713481Sgiacomo.travaglini@arm.comusing ::testing::MatcherInterface; 263813481Sgiacomo.travaglini@arm.comusing ::testing::MatchResultListener; 263913481Sgiacomo.travaglini@arm.com 264013481Sgiacomo.travaglini@arm.comclass DivisibleBy7Matcher : public MatcherInterface<int> { 264113481Sgiacomo.travaglini@arm.com public: 264213481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(int n, MatchResultListener* listener) const { 264313481Sgiacomo.travaglini@arm.com return (n % 7) == 0; 264413481Sgiacomo.travaglini@arm.com } 264513481Sgiacomo.travaglini@arm.com 264613481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const { 264713481Sgiacomo.travaglini@arm.com *os << "is divisible by 7"; 264813481Sgiacomo.travaglini@arm.com } 264913481Sgiacomo.travaglini@arm.com 265013481Sgiacomo.travaglini@arm.com virtual void DescribeNegationTo(::std::ostream* os) const { 265113481Sgiacomo.travaglini@arm.com *os << "is not divisible by 7"; 265213481Sgiacomo.travaglini@arm.com } 265313481Sgiacomo.travaglini@arm.com}; 265413481Sgiacomo.travaglini@arm.com 265513481Sgiacomo.travaglini@arm.cominline Matcher<int> DivisibleBy7() { 265613481Sgiacomo.travaglini@arm.com return MakeMatcher(new DivisibleBy7Matcher); 265713481Sgiacomo.travaglini@arm.com} 265813481Sgiacomo.travaglini@arm.com... 265913481Sgiacomo.travaglini@arm.com 266013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(DivisibleBy7())); 266113481Sgiacomo.travaglini@arm.com``` 266213481Sgiacomo.travaglini@arm.com 266313481Sgiacomo.travaglini@arm.comYou may improve the matcher message by streaming additional 266413481Sgiacomo.travaglini@arm.cominformation to the `listener` argument in `MatchAndExplain()`: 266513481Sgiacomo.travaglini@arm.com 266613481Sgiacomo.travaglini@arm.com``` 266713481Sgiacomo.travaglini@arm.comclass DivisibleBy7Matcher : public MatcherInterface<int> { 266813481Sgiacomo.travaglini@arm.com public: 266913481Sgiacomo.travaglini@arm.com virtual bool MatchAndExplain(int n, 267013481Sgiacomo.travaglini@arm.com MatchResultListener* listener) const { 267113481Sgiacomo.travaglini@arm.com const int remainder = n % 7; 267213481Sgiacomo.travaglini@arm.com if (remainder != 0) { 267313481Sgiacomo.travaglini@arm.com *listener << "the remainder is " << remainder; 267413481Sgiacomo.travaglini@arm.com } 267513481Sgiacomo.travaglini@arm.com return remainder == 0; 267613481Sgiacomo.travaglini@arm.com } 267713481Sgiacomo.travaglini@arm.com ... 267813481Sgiacomo.travaglini@arm.com}; 267913481Sgiacomo.travaglini@arm.com``` 268013481Sgiacomo.travaglini@arm.com 268113481Sgiacomo.travaglini@arm.comThen, `EXPECT_THAT(x, DivisibleBy7());` may general a message like this: 268213481Sgiacomo.travaglini@arm.com``` 268313481Sgiacomo.travaglini@arm.comValue of: x 268413481Sgiacomo.travaglini@arm.comExpected: is divisible by 7 268513481Sgiacomo.travaglini@arm.com Actual: 23 (the remainder is 2) 268613481Sgiacomo.travaglini@arm.com``` 268713481Sgiacomo.travaglini@arm.com 268813481Sgiacomo.travaglini@arm.com## Writing New Polymorphic Matchers ## 268913481Sgiacomo.travaglini@arm.com 269013481Sgiacomo.travaglini@arm.comYou've learned how to write your own matchers in the previous 269113481Sgiacomo.travaglini@arm.comrecipe. Just one problem: a matcher created using `MakeMatcher()` only 269213481Sgiacomo.travaglini@arm.comworks for one particular type of arguments. If you want a 269313481Sgiacomo.travaglini@arm.com_polymorphic_ matcher that works with arguments of several types (for 269413481Sgiacomo.travaglini@arm.cominstance, `Eq(x)` can be used to match a `value` as long as `value` == 269513481Sgiacomo.travaglini@arm.com`x` compiles -- `value` and `x` don't have to share the same type), 269613481Sgiacomo.travaglini@arm.comyou can learn the trick from `<gmock/gmock-matchers.h>` but it's a bit 269713481Sgiacomo.travaglini@arm.cominvolved. 269813481Sgiacomo.travaglini@arm.com 269913481Sgiacomo.travaglini@arm.comFortunately, most of the time you can define a polymorphic matcher 270013481Sgiacomo.travaglini@arm.comeasily with the help of `MakePolymorphicMatcher()`. Here's how you can 270113481Sgiacomo.travaglini@arm.comdefine `NotNull()` as an example: 270213481Sgiacomo.travaglini@arm.com 270313481Sgiacomo.travaglini@arm.com``` 270413481Sgiacomo.travaglini@arm.comusing ::testing::MakePolymorphicMatcher; 270513481Sgiacomo.travaglini@arm.comusing ::testing::MatchResultListener; 270613481Sgiacomo.travaglini@arm.comusing ::testing::NotNull; 270713481Sgiacomo.travaglini@arm.comusing ::testing::PolymorphicMatcher; 270813481Sgiacomo.travaglini@arm.com 270913481Sgiacomo.travaglini@arm.comclass NotNullMatcher { 271013481Sgiacomo.travaglini@arm.com public: 271113481Sgiacomo.travaglini@arm.com // To implement a polymorphic matcher, first define a COPYABLE class 271213481Sgiacomo.travaglini@arm.com // that has three members MatchAndExplain(), DescribeTo(), and 271313481Sgiacomo.travaglini@arm.com // DescribeNegationTo(), like the following. 271413481Sgiacomo.travaglini@arm.com 271513481Sgiacomo.travaglini@arm.com // In this example, we want to use NotNull() with any pointer, so 271613481Sgiacomo.travaglini@arm.com // MatchAndExplain() accepts a pointer of any type as its first argument. 271713481Sgiacomo.travaglini@arm.com // In general, you can define MatchAndExplain() as an ordinary method or 271813481Sgiacomo.travaglini@arm.com // a method template, or even overload it. 271913481Sgiacomo.travaglini@arm.com template <typename T> 272013481Sgiacomo.travaglini@arm.com bool MatchAndExplain(T* p, 272113481Sgiacomo.travaglini@arm.com MatchResultListener* /* listener */) const { 272213481Sgiacomo.travaglini@arm.com return p != NULL; 272313481Sgiacomo.travaglini@arm.com } 272413481Sgiacomo.travaglini@arm.com 272513481Sgiacomo.travaglini@arm.com // Describes the property of a value matching this matcher. 272613481Sgiacomo.travaglini@arm.com void DescribeTo(::std::ostream* os) const { *os << "is not NULL"; } 272713481Sgiacomo.travaglini@arm.com 272813481Sgiacomo.travaglini@arm.com // Describes the property of a value NOT matching this matcher. 272913481Sgiacomo.travaglini@arm.com void DescribeNegationTo(::std::ostream* os) const { *os << "is NULL"; } 273013481Sgiacomo.travaglini@arm.com}; 273113481Sgiacomo.travaglini@arm.com 273213481Sgiacomo.travaglini@arm.com// To construct a polymorphic matcher, pass an instance of the class 273313481Sgiacomo.travaglini@arm.com// to MakePolymorphicMatcher(). Note the return type. 273413481Sgiacomo.travaglini@arm.cominline PolymorphicMatcher<NotNullMatcher> NotNull() { 273513481Sgiacomo.travaglini@arm.com return MakePolymorphicMatcher(NotNullMatcher()); 273613481Sgiacomo.travaglini@arm.com} 273713481Sgiacomo.travaglini@arm.com... 273813481Sgiacomo.travaglini@arm.com 273913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer. 274013481Sgiacomo.travaglini@arm.com``` 274113481Sgiacomo.travaglini@arm.com 274213481Sgiacomo.travaglini@arm.com**Note:** Your polymorphic matcher class does **not** need to inherit from 274313481Sgiacomo.travaglini@arm.com`MatcherInterface` or any other class, and its methods do **not** need 274413481Sgiacomo.travaglini@arm.comto be virtual. 274513481Sgiacomo.travaglini@arm.com 274613481Sgiacomo.travaglini@arm.comLike in a monomorphic matcher, you may explain the match result by 274713481Sgiacomo.travaglini@arm.comstreaming additional information to the `listener` argument in 274813481Sgiacomo.travaglini@arm.com`MatchAndExplain()`. 274913481Sgiacomo.travaglini@arm.com 275013481Sgiacomo.travaglini@arm.com## Writing New Cardinalities ## 275113481Sgiacomo.travaglini@arm.com 275213481Sgiacomo.travaglini@arm.comA cardinality is used in `Times()` to tell Google Mock how many times 275313481Sgiacomo.travaglini@arm.comyou expect a call to occur. It doesn't have to be exact. For example, 275413481Sgiacomo.travaglini@arm.comyou can say `AtLeast(5)` or `Between(2, 4)`. 275513481Sgiacomo.travaglini@arm.com 275613481Sgiacomo.travaglini@arm.comIf the built-in set of cardinalities doesn't suit you, you are free to 275713481Sgiacomo.travaglini@arm.comdefine your own by implementing the following interface (in namespace 275813481Sgiacomo.travaglini@arm.com`testing`): 275913481Sgiacomo.travaglini@arm.com 276013481Sgiacomo.travaglini@arm.com``` 276113481Sgiacomo.travaglini@arm.comclass CardinalityInterface { 276213481Sgiacomo.travaglini@arm.com public: 276313481Sgiacomo.travaglini@arm.com virtual ~CardinalityInterface(); 276413481Sgiacomo.travaglini@arm.com 276513481Sgiacomo.travaglini@arm.com // Returns true iff call_count calls will satisfy this cardinality. 276613481Sgiacomo.travaglini@arm.com virtual bool IsSatisfiedByCallCount(int call_count) const = 0; 276713481Sgiacomo.travaglini@arm.com 276813481Sgiacomo.travaglini@arm.com // Returns true iff call_count calls will saturate this cardinality. 276913481Sgiacomo.travaglini@arm.com virtual bool IsSaturatedByCallCount(int call_count) const = 0; 277013481Sgiacomo.travaglini@arm.com 277113481Sgiacomo.travaglini@arm.com // Describes self to an ostream. 277213481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const = 0; 277313481Sgiacomo.travaglini@arm.com}; 277413481Sgiacomo.travaglini@arm.com``` 277513481Sgiacomo.travaglini@arm.com 277613481Sgiacomo.travaglini@arm.comFor example, to specify that a call must occur even number of times, 277713481Sgiacomo.travaglini@arm.comyou can write 277813481Sgiacomo.travaglini@arm.com 277913481Sgiacomo.travaglini@arm.com``` 278013481Sgiacomo.travaglini@arm.comusing ::testing::Cardinality; 278113481Sgiacomo.travaglini@arm.comusing ::testing::CardinalityInterface; 278213481Sgiacomo.travaglini@arm.comusing ::testing::MakeCardinality; 278313481Sgiacomo.travaglini@arm.com 278413481Sgiacomo.travaglini@arm.comclass EvenNumberCardinality : public CardinalityInterface { 278513481Sgiacomo.travaglini@arm.com public: 278613481Sgiacomo.travaglini@arm.com virtual bool IsSatisfiedByCallCount(int call_count) const { 278713481Sgiacomo.travaglini@arm.com return (call_count % 2) == 0; 278813481Sgiacomo.travaglini@arm.com } 278913481Sgiacomo.travaglini@arm.com 279013481Sgiacomo.travaglini@arm.com virtual bool IsSaturatedByCallCount(int call_count) const { 279113481Sgiacomo.travaglini@arm.com return false; 279213481Sgiacomo.travaglini@arm.com } 279313481Sgiacomo.travaglini@arm.com 279413481Sgiacomo.travaglini@arm.com virtual void DescribeTo(::std::ostream* os) const { 279513481Sgiacomo.travaglini@arm.com *os << "called even number of times"; 279613481Sgiacomo.travaglini@arm.com } 279713481Sgiacomo.travaglini@arm.com}; 279813481Sgiacomo.travaglini@arm.com 279913481Sgiacomo.travaglini@arm.comCardinality EvenNumber() { 280013481Sgiacomo.travaglini@arm.com return MakeCardinality(new EvenNumberCardinality); 280113481Sgiacomo.travaglini@arm.com} 280213481Sgiacomo.travaglini@arm.com... 280313481Sgiacomo.travaglini@arm.com 280413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Bar(3)) 280513481Sgiacomo.travaglini@arm.com .Times(EvenNumber()); 280613481Sgiacomo.travaglini@arm.com``` 280713481Sgiacomo.travaglini@arm.com 280813481Sgiacomo.travaglini@arm.com## Writing New Actions Quickly ## 280913481Sgiacomo.travaglini@arm.com 281013481Sgiacomo.travaglini@arm.comIf the built-in actions don't work for you, and you find it 281113481Sgiacomo.travaglini@arm.cominconvenient to use `Invoke()`, you can use a macro from the `ACTION*` 281213481Sgiacomo.travaglini@arm.comfamily to quickly define a new action that can be used in your code as 281313481Sgiacomo.travaglini@arm.comif it's a built-in action. 281413481Sgiacomo.travaglini@arm.com 281513481Sgiacomo.travaglini@arm.comBy writing 281613481Sgiacomo.travaglini@arm.com``` 281713481Sgiacomo.travaglini@arm.comACTION(name) { statements; } 281813481Sgiacomo.travaglini@arm.com``` 281913481Sgiacomo.travaglini@arm.comin a namespace scope (i.e. not inside a class or function), you will 282013481Sgiacomo.travaglini@arm.comdefine an action with the given name that executes the statements. 282113481Sgiacomo.travaglini@arm.comThe value returned by `statements` will be used as the return value of 282213481Sgiacomo.travaglini@arm.comthe action. Inside the statements, you can refer to the K-th 282313481Sgiacomo.travaglini@arm.com(0-based) argument of the mock function as `argK`. For example: 282413481Sgiacomo.travaglini@arm.com``` 282513481Sgiacomo.travaglini@arm.comACTION(IncrementArg1) { return ++(*arg1); } 282613481Sgiacomo.travaglini@arm.com``` 282713481Sgiacomo.travaglini@arm.comallows you to write 282813481Sgiacomo.travaglini@arm.com``` 282913481Sgiacomo.travaglini@arm.com... WillOnce(IncrementArg1()); 283013481Sgiacomo.travaglini@arm.com``` 283113481Sgiacomo.travaglini@arm.com 283213481Sgiacomo.travaglini@arm.comNote that you don't need to specify the types of the mock function 283313481Sgiacomo.travaglini@arm.comarguments. Rest assured that your code is type-safe though: 283413481Sgiacomo.travaglini@arm.comyou'll get a compiler error if `*arg1` doesn't support the `++` 283513481Sgiacomo.travaglini@arm.comoperator, or if the type of `++(*arg1)` isn't compatible with the mock 283613481Sgiacomo.travaglini@arm.comfunction's return type. 283713481Sgiacomo.travaglini@arm.com 283813481Sgiacomo.travaglini@arm.comAnother example: 283913481Sgiacomo.travaglini@arm.com``` 284013481Sgiacomo.travaglini@arm.comACTION(Foo) { 284113481Sgiacomo.travaglini@arm.com (*arg2)(5); 284213481Sgiacomo.travaglini@arm.com Blah(); 284313481Sgiacomo.travaglini@arm.com *arg1 = 0; 284413481Sgiacomo.travaglini@arm.com return arg0; 284513481Sgiacomo.travaglini@arm.com} 284613481Sgiacomo.travaglini@arm.com``` 284713481Sgiacomo.travaglini@arm.comdefines an action `Foo()` that invokes argument #2 (a function pointer) 284813481Sgiacomo.travaglini@arm.comwith 5, calls function `Blah()`, sets the value pointed to by argument 284913481Sgiacomo.travaglini@arm.com#1 to 0, and returns argument #0. 285013481Sgiacomo.travaglini@arm.com 285113481Sgiacomo.travaglini@arm.comFor more convenience and flexibility, you can also use the following 285213481Sgiacomo.travaglini@arm.compre-defined symbols in the body of `ACTION`: 285313481Sgiacomo.travaglini@arm.com 285413481Sgiacomo.travaglini@arm.com| `argK_type` | The type of the K-th (0-based) argument of the mock function | 285513481Sgiacomo.travaglini@arm.com|:------------|:-------------------------------------------------------------| 285613481Sgiacomo.travaglini@arm.com| `args` | All arguments of the mock function as a tuple | 285713481Sgiacomo.travaglini@arm.com| `args_type` | The type of all arguments of the mock function as a tuple | 285813481Sgiacomo.travaglini@arm.com| `return_type` | The return type of the mock function | 285913481Sgiacomo.travaglini@arm.com| `function_type` | The type of the mock function | 286013481Sgiacomo.travaglini@arm.com 286113481Sgiacomo.travaglini@arm.comFor example, when using an `ACTION` as a stub action for mock function: 286213481Sgiacomo.travaglini@arm.com``` 286313481Sgiacomo.travaglini@arm.comint DoSomething(bool flag, int* ptr); 286413481Sgiacomo.travaglini@arm.com``` 286513481Sgiacomo.travaglini@arm.comwe have: 286613481Sgiacomo.travaglini@arm.com| **Pre-defined Symbol** | **Is Bound To** | 286713481Sgiacomo.travaglini@arm.com|:-----------------------|:----------------| 286813481Sgiacomo.travaglini@arm.com| `arg0` | the value of `flag` | 286913481Sgiacomo.travaglini@arm.com| `arg0_type` | the type `bool` | 287013481Sgiacomo.travaglini@arm.com| `arg1` | the value of `ptr` | 287113481Sgiacomo.travaglini@arm.com| `arg1_type` | the type `int*` | 287213481Sgiacomo.travaglini@arm.com| `args` | the tuple `(flag, ptr)` | 287313481Sgiacomo.travaglini@arm.com| `args_type` | the type `std::tr1::tuple<bool, int*>` | 287413481Sgiacomo.travaglini@arm.com| `return_type` | the type `int` | 287513481Sgiacomo.travaglini@arm.com| `function_type` | the type `int(bool, int*)` | 287613481Sgiacomo.travaglini@arm.com 287713481Sgiacomo.travaglini@arm.com## Writing New Parameterized Actions Quickly ## 287813481Sgiacomo.travaglini@arm.com 287913481Sgiacomo.travaglini@arm.comSometimes you'll want to parameterize an action you define. For that 288013481Sgiacomo.travaglini@arm.comwe have another macro 288113481Sgiacomo.travaglini@arm.com``` 288213481Sgiacomo.travaglini@arm.comACTION_P(name, param) { statements; } 288313481Sgiacomo.travaglini@arm.com``` 288413481Sgiacomo.travaglini@arm.com 288513481Sgiacomo.travaglini@arm.comFor example, 288613481Sgiacomo.travaglini@arm.com``` 288713481Sgiacomo.travaglini@arm.comACTION_P(Add, n) { return arg0 + n; } 288813481Sgiacomo.travaglini@arm.com``` 288913481Sgiacomo.travaglini@arm.comwill allow you to write 289013481Sgiacomo.travaglini@arm.com``` 289113481Sgiacomo.travaglini@arm.com// Returns argument #0 + 5. 289213481Sgiacomo.travaglini@arm.com... WillOnce(Add(5)); 289313481Sgiacomo.travaglini@arm.com``` 289413481Sgiacomo.travaglini@arm.com 289513481Sgiacomo.travaglini@arm.comFor convenience, we use the term _arguments_ for the values used to 289613481Sgiacomo.travaglini@arm.cominvoke the mock function, and the term _parameters_ for the values 289713481Sgiacomo.travaglini@arm.comused to instantiate an action. 289813481Sgiacomo.travaglini@arm.com 289913481Sgiacomo.travaglini@arm.comNote that you don't need to provide the type of the parameter either. 290013481Sgiacomo.travaglini@arm.comSuppose the parameter is named `param`, you can also use the 290113481Sgiacomo.travaglini@arm.comGoogle-Mock-defined symbol `param_type` to refer to the type of the 290213481Sgiacomo.travaglini@arm.comparameter as inferred by the compiler. For example, in the body of 290313481Sgiacomo.travaglini@arm.com`ACTION_P(Add, n)` above, you can write `n_type` for the type of `n`. 290413481Sgiacomo.travaglini@arm.com 290513481Sgiacomo.travaglini@arm.comGoogle Mock also provides `ACTION_P2`, `ACTION_P3`, and etc to support 290613481Sgiacomo.travaglini@arm.commulti-parameter actions. For example, 290713481Sgiacomo.travaglini@arm.com``` 290813481Sgiacomo.travaglini@arm.comACTION_P2(ReturnDistanceTo, x, y) { 290913481Sgiacomo.travaglini@arm.com double dx = arg0 - x; 291013481Sgiacomo.travaglini@arm.com double dy = arg1 - y; 291113481Sgiacomo.travaglini@arm.com return sqrt(dx*dx + dy*dy); 291213481Sgiacomo.travaglini@arm.com} 291313481Sgiacomo.travaglini@arm.com``` 291413481Sgiacomo.travaglini@arm.comlets you write 291513481Sgiacomo.travaglini@arm.com``` 291613481Sgiacomo.travaglini@arm.com... WillOnce(ReturnDistanceTo(5.0, 26.5)); 291713481Sgiacomo.travaglini@arm.com``` 291813481Sgiacomo.travaglini@arm.com 291913481Sgiacomo.travaglini@arm.comYou can view `ACTION` as a degenerated parameterized action where the 292013481Sgiacomo.travaglini@arm.comnumber of parameters is 0. 292113481Sgiacomo.travaglini@arm.com 292213481Sgiacomo.travaglini@arm.comYou can also easily define actions overloaded on the number of parameters: 292313481Sgiacomo.travaglini@arm.com``` 292413481Sgiacomo.travaglini@arm.comACTION_P(Plus, a) { ... } 292513481Sgiacomo.travaglini@arm.comACTION_P2(Plus, a, b) { ... } 292613481Sgiacomo.travaglini@arm.com``` 292713481Sgiacomo.travaglini@arm.com 292813481Sgiacomo.travaglini@arm.com## Restricting the Type of an Argument or Parameter in an ACTION ## 292913481Sgiacomo.travaglini@arm.com 293013481Sgiacomo.travaglini@arm.comFor maximum brevity and reusability, the `ACTION*` macros don't ask 293113481Sgiacomo.travaglini@arm.comyou to provide the types of the mock function arguments and the action 293213481Sgiacomo.travaglini@arm.comparameters. Instead, we let the compiler infer the types for us. 293313481Sgiacomo.travaglini@arm.com 293413481Sgiacomo.travaglini@arm.comSometimes, however, we may want to be more explicit about the types. 293513481Sgiacomo.travaglini@arm.comThere are several tricks to do that. For example: 293613481Sgiacomo.travaglini@arm.com``` 293713481Sgiacomo.travaglini@arm.comACTION(Foo) { 293813481Sgiacomo.travaglini@arm.com // Makes sure arg0 can be converted to int. 293913481Sgiacomo.travaglini@arm.com int n = arg0; 294013481Sgiacomo.travaglini@arm.com ... use n instead of arg0 here ... 294113481Sgiacomo.travaglini@arm.com} 294213481Sgiacomo.travaglini@arm.com 294313481Sgiacomo.travaglini@arm.comACTION_P(Bar, param) { 294413481Sgiacomo.travaglini@arm.com // Makes sure the type of arg1 is const char*. 294513481Sgiacomo.travaglini@arm.com ::testing::StaticAssertTypeEq<const char*, arg1_type>(); 294613481Sgiacomo.travaglini@arm.com 294713481Sgiacomo.travaglini@arm.com // Makes sure param can be converted to bool. 294813481Sgiacomo.travaglini@arm.com bool flag = param; 294913481Sgiacomo.travaglini@arm.com} 295013481Sgiacomo.travaglini@arm.com``` 295113481Sgiacomo.travaglini@arm.comwhere `StaticAssertTypeEq` is a compile-time assertion in Google Test 295213481Sgiacomo.travaglini@arm.comthat verifies two types are the same. 295313481Sgiacomo.travaglini@arm.com 295413481Sgiacomo.travaglini@arm.com## Writing New Action Templates Quickly ## 295513481Sgiacomo.travaglini@arm.com 295613481Sgiacomo.travaglini@arm.comSometimes you want to give an action explicit template parameters that 295713481Sgiacomo.travaglini@arm.comcannot be inferred from its value parameters. `ACTION_TEMPLATE()` 295813481Sgiacomo.travaglini@arm.comsupports that and can be viewed as an extension to `ACTION()` and 295913481Sgiacomo.travaglini@arm.com`ACTION_P*()`. 296013481Sgiacomo.travaglini@arm.com 296113481Sgiacomo.travaglini@arm.comThe syntax: 296213481Sgiacomo.travaglini@arm.com``` 296313481Sgiacomo.travaglini@arm.comACTION_TEMPLATE(ActionName, 296413481Sgiacomo.travaglini@arm.com HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m), 296513481Sgiacomo.travaglini@arm.com AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; } 296613481Sgiacomo.travaglini@arm.com``` 296713481Sgiacomo.travaglini@arm.com 296813481Sgiacomo.travaglini@arm.comdefines an action template that takes _m_ explicit template parameters 296913481Sgiacomo.travaglini@arm.comand _n_ value parameters, where _m_ is between 1 and 10, and _n_ is 297013481Sgiacomo.travaglini@arm.combetween 0 and 10. `name_i` is the name of the i-th template 297113481Sgiacomo.travaglini@arm.comparameter, and `kind_i` specifies whether it's a `typename`, an 297213481Sgiacomo.travaglini@arm.comintegral constant, or a template. `p_i` is the name of the i-th value 297313481Sgiacomo.travaglini@arm.comparameter. 297413481Sgiacomo.travaglini@arm.com 297513481Sgiacomo.travaglini@arm.comExample: 297613481Sgiacomo.travaglini@arm.com``` 297713481Sgiacomo.travaglini@arm.com// DuplicateArg<k, T>(output) converts the k-th argument of the mock 297813481Sgiacomo.travaglini@arm.com// function to type T and copies it to *output. 297913481Sgiacomo.travaglini@arm.comACTION_TEMPLATE(DuplicateArg, 298013481Sgiacomo.travaglini@arm.com // Note the comma between int and k: 298113481Sgiacomo.travaglini@arm.com HAS_2_TEMPLATE_PARAMS(int, k, typename, T), 298213481Sgiacomo.travaglini@arm.com AND_1_VALUE_PARAMS(output)) { 298313481Sgiacomo.travaglini@arm.com *output = T(std::tr1::get<k>(args)); 298413481Sgiacomo.travaglini@arm.com} 298513481Sgiacomo.travaglini@arm.com``` 298613481Sgiacomo.travaglini@arm.com 298713481Sgiacomo.travaglini@arm.comTo create an instance of an action template, write: 298813481Sgiacomo.travaglini@arm.com``` 298913481Sgiacomo.travaglini@arm.com ActionName<t1, ..., t_m>(v1, ..., v_n) 299013481Sgiacomo.travaglini@arm.com``` 299113481Sgiacomo.travaglini@arm.comwhere the `t`s are the template arguments and the 299213481Sgiacomo.travaglini@arm.com`v`s are the value arguments. The value argument 299313481Sgiacomo.travaglini@arm.comtypes are inferred by the compiler. For example: 299413481Sgiacomo.travaglini@arm.com``` 299513481Sgiacomo.travaglini@arm.comusing ::testing::_; 299613481Sgiacomo.travaglini@arm.com... 299713481Sgiacomo.travaglini@arm.com int n; 299813481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo(_, _)) 299913481Sgiacomo.travaglini@arm.com .WillOnce(DuplicateArg<1, unsigned char>(&n)); 300013481Sgiacomo.travaglini@arm.com``` 300113481Sgiacomo.travaglini@arm.com 300213481Sgiacomo.travaglini@arm.comIf you want to explicitly specify the value argument types, you can 300313481Sgiacomo.travaglini@arm.comprovide additional template arguments: 300413481Sgiacomo.travaglini@arm.com``` 300513481Sgiacomo.travaglini@arm.com ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n) 300613481Sgiacomo.travaglini@arm.com``` 300713481Sgiacomo.travaglini@arm.comwhere `u_i` is the desired type of `v_i`. 300813481Sgiacomo.travaglini@arm.com 300913481Sgiacomo.travaglini@arm.com`ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the 301013481Sgiacomo.travaglini@arm.comnumber of value parameters, but not on the number of template 301113481Sgiacomo.travaglini@arm.comparameters. Without the restriction, the meaning of the following is 301213481Sgiacomo.travaglini@arm.comunclear: 301313481Sgiacomo.travaglini@arm.com 301413481Sgiacomo.travaglini@arm.com``` 301513481Sgiacomo.travaglini@arm.com OverloadedAction<int, bool>(x); 301613481Sgiacomo.travaglini@arm.com``` 301713481Sgiacomo.travaglini@arm.com 301813481Sgiacomo.travaglini@arm.comAre we using a single-template-parameter action where `bool` refers to 301913481Sgiacomo.travaglini@arm.comthe type of `x`, or a two-template-parameter action where the compiler 302013481Sgiacomo.travaglini@arm.comis asked to infer the type of `x`? 302113481Sgiacomo.travaglini@arm.com 302213481Sgiacomo.travaglini@arm.com## Using the ACTION Object's Type ## 302313481Sgiacomo.travaglini@arm.com 302413481Sgiacomo.travaglini@arm.comIf you are writing a function that returns an `ACTION` object, you'll 302513481Sgiacomo.travaglini@arm.comneed to know its type. The type depends on the macro used to define 302613481Sgiacomo.travaglini@arm.comthe action and the parameter types. The rule is relatively simple: 302713481Sgiacomo.travaglini@arm.com| **Given Definition** | **Expression** | **Has Type** | 302813481Sgiacomo.travaglini@arm.com|:---------------------|:---------------|:-------------| 302913481Sgiacomo.travaglini@arm.com| `ACTION(Foo)` | `Foo()` | `FooAction` | 303013481Sgiacomo.travaglini@arm.com| `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` | 303113481Sgiacomo.travaglini@arm.com| `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` | 303213481Sgiacomo.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>` | 303313481Sgiacomo.travaglini@arm.com| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` | 303413481Sgiacomo.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>` | 303513481Sgiacomo.travaglini@arm.com| ... | ... | ... | 303613481Sgiacomo.travaglini@arm.com 303713481Sgiacomo.travaglini@arm.comNote that we have to pick different suffixes (`Action`, `ActionP`, 303813481Sgiacomo.travaglini@arm.com`ActionP2`, and etc) for actions with different numbers of value 303913481Sgiacomo.travaglini@arm.comparameters, or the action definitions cannot be overloaded on the 304013481Sgiacomo.travaglini@arm.comnumber of them. 304113481Sgiacomo.travaglini@arm.com 304213481Sgiacomo.travaglini@arm.com## Writing New Monomorphic Actions ## 304313481Sgiacomo.travaglini@arm.com 304413481Sgiacomo.travaglini@arm.comWhile the `ACTION*` macros are very convenient, sometimes they are 304513481Sgiacomo.travaglini@arm.cominappropriate. For example, despite the tricks shown in the previous 304613481Sgiacomo.travaglini@arm.comrecipes, they don't let you directly specify the types of the mock 304713481Sgiacomo.travaglini@arm.comfunction arguments and the action parameters, which in general leads 304813481Sgiacomo.travaglini@arm.comto unoptimized compiler error messages that can baffle unfamiliar 304913481Sgiacomo.travaglini@arm.comusers. They also don't allow overloading actions based on parameter 305013481Sgiacomo.travaglini@arm.comtypes without jumping through some hoops. 305113481Sgiacomo.travaglini@arm.com 305213481Sgiacomo.travaglini@arm.comAn alternative to the `ACTION*` macros is to implement 305313481Sgiacomo.travaglini@arm.com`::testing::ActionInterface<F>`, where `F` is the type of the mock 305413481Sgiacomo.travaglini@arm.comfunction in which the action will be used. For example: 305513481Sgiacomo.travaglini@arm.com 305613481Sgiacomo.travaglini@arm.com``` 305713481Sgiacomo.travaglini@arm.comtemplate <typename F>class ActionInterface { 305813481Sgiacomo.travaglini@arm.com public: 305913481Sgiacomo.travaglini@arm.com virtual ~ActionInterface(); 306013481Sgiacomo.travaglini@arm.com 306113481Sgiacomo.travaglini@arm.com // Performs the action. Result is the return type of function type 306213481Sgiacomo.travaglini@arm.com // F, and ArgumentTuple is the tuple of arguments of F. 306313481Sgiacomo.travaglini@arm.com // 306413481Sgiacomo.travaglini@arm.com // For example, if F is int(bool, const string&), then Result would 306513481Sgiacomo.travaglini@arm.com // be int, and ArgumentTuple would be tr1::tuple<bool, const string&>. 306613481Sgiacomo.travaglini@arm.com virtual Result Perform(const ArgumentTuple& args) = 0; 306713481Sgiacomo.travaglini@arm.com}; 306813481Sgiacomo.travaglini@arm.com 306913481Sgiacomo.travaglini@arm.comusing ::testing::_; 307013481Sgiacomo.travaglini@arm.comusing ::testing::Action; 307113481Sgiacomo.travaglini@arm.comusing ::testing::ActionInterface; 307213481Sgiacomo.travaglini@arm.comusing ::testing::MakeAction; 307313481Sgiacomo.travaglini@arm.com 307413481Sgiacomo.travaglini@arm.comtypedef int IncrementMethod(int*); 307513481Sgiacomo.travaglini@arm.com 307613481Sgiacomo.travaglini@arm.comclass IncrementArgumentAction : public ActionInterface<IncrementMethod> { 307713481Sgiacomo.travaglini@arm.com public: 307813481Sgiacomo.travaglini@arm.com virtual int Perform(const tr1::tuple<int*>& args) { 307913481Sgiacomo.travaglini@arm.com int* p = tr1::get<0>(args); // Grabs the first argument. 308013481Sgiacomo.travaglini@arm.com return *p++; 308113481Sgiacomo.travaglini@arm.com } 308213481Sgiacomo.travaglini@arm.com}; 308313481Sgiacomo.travaglini@arm.com 308413481Sgiacomo.travaglini@arm.comAction<IncrementMethod> IncrementArgument() { 308513481Sgiacomo.travaglini@arm.com return MakeAction(new IncrementArgumentAction); 308613481Sgiacomo.travaglini@arm.com} 308713481Sgiacomo.travaglini@arm.com... 308813481Sgiacomo.travaglini@arm.com 308913481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Baz(_)) 309013481Sgiacomo.travaglini@arm.com .WillOnce(IncrementArgument()); 309113481Sgiacomo.travaglini@arm.com 309213481Sgiacomo.travaglini@arm.com int n = 5; 309313481Sgiacomo.travaglini@arm.com foo.Baz(&n); // Should return 5 and change n to 6. 309413481Sgiacomo.travaglini@arm.com``` 309513481Sgiacomo.travaglini@arm.com 309613481Sgiacomo.travaglini@arm.com## Writing New Polymorphic Actions ## 309713481Sgiacomo.travaglini@arm.com 309813481Sgiacomo.travaglini@arm.comThe previous recipe showed you how to define your own action. This is 309913481Sgiacomo.travaglini@arm.comall good, except that you need to know the type of the function in 310013481Sgiacomo.travaglini@arm.comwhich the action will be used. Sometimes that can be a problem. For 310113481Sgiacomo.travaglini@arm.comexample, if you want to use the action in functions with _different_ 310213481Sgiacomo.travaglini@arm.comtypes (e.g. like `Return()` and `SetArgumentPointee()`). 310313481Sgiacomo.travaglini@arm.com 310413481Sgiacomo.travaglini@arm.comIf an action can be used in several types of mock functions, we say 310513481Sgiacomo.travaglini@arm.comit's _polymorphic_. The `MakePolymorphicAction()` function template 310613481Sgiacomo.travaglini@arm.commakes it easy to define such an action: 310713481Sgiacomo.travaglini@arm.com 310813481Sgiacomo.travaglini@arm.com``` 310913481Sgiacomo.travaglini@arm.comnamespace testing { 311013481Sgiacomo.travaglini@arm.com 311113481Sgiacomo.travaglini@arm.comtemplate <typename Impl> 311213481Sgiacomo.travaglini@arm.comPolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl); 311313481Sgiacomo.travaglini@arm.com 311413481Sgiacomo.travaglini@arm.com} // namespace testing 311513481Sgiacomo.travaglini@arm.com``` 311613481Sgiacomo.travaglini@arm.com 311713481Sgiacomo.travaglini@arm.comAs an example, let's define an action that returns the second argument 311813481Sgiacomo.travaglini@arm.comin the mock function's argument list. The first step is to define an 311913481Sgiacomo.travaglini@arm.comimplementation class: 312013481Sgiacomo.travaglini@arm.com 312113481Sgiacomo.travaglini@arm.com``` 312213481Sgiacomo.travaglini@arm.comclass ReturnSecondArgumentAction { 312313481Sgiacomo.travaglini@arm.com public: 312413481Sgiacomo.travaglini@arm.com template <typename Result, typename ArgumentTuple> 312513481Sgiacomo.travaglini@arm.com Result Perform(const ArgumentTuple& args) const { 312613481Sgiacomo.travaglini@arm.com // To get the i-th (0-based) argument, use tr1::get<i>(args). 312713481Sgiacomo.travaglini@arm.com return tr1::get<1>(args); 312813481Sgiacomo.travaglini@arm.com } 312913481Sgiacomo.travaglini@arm.com}; 313013481Sgiacomo.travaglini@arm.com``` 313113481Sgiacomo.travaglini@arm.com 313213481Sgiacomo.travaglini@arm.comThis implementation class does _not_ need to inherit from any 313313481Sgiacomo.travaglini@arm.comparticular class. What matters is that it must have a `Perform()` 313413481Sgiacomo.travaglini@arm.commethod template. This method template takes the mock function's 313513481Sgiacomo.travaglini@arm.comarguments as a tuple in a **single** argument, and returns the result of 313613481Sgiacomo.travaglini@arm.comthe action. It can be either `const` or not, but must be invokable 313713481Sgiacomo.travaglini@arm.comwith exactly one template argument, which is the result type. In other 313813481Sgiacomo.travaglini@arm.comwords, you must be able to call `Perform<R>(args)` where `R` is the 313913481Sgiacomo.travaglini@arm.commock function's return type and `args` is its arguments in a tuple. 314013481Sgiacomo.travaglini@arm.com 314113481Sgiacomo.travaglini@arm.comNext, we use `MakePolymorphicAction()` to turn an instance of the 314213481Sgiacomo.travaglini@arm.comimplementation class into the polymorphic action we need. It will be 314313481Sgiacomo.travaglini@arm.comconvenient to have a wrapper for this: 314413481Sgiacomo.travaglini@arm.com 314513481Sgiacomo.travaglini@arm.com``` 314613481Sgiacomo.travaglini@arm.comusing ::testing::MakePolymorphicAction; 314713481Sgiacomo.travaglini@arm.comusing ::testing::PolymorphicAction; 314813481Sgiacomo.travaglini@arm.com 314913481Sgiacomo.travaglini@arm.comPolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() { 315013481Sgiacomo.travaglini@arm.com return MakePolymorphicAction(ReturnSecondArgumentAction()); 315113481Sgiacomo.travaglini@arm.com} 315213481Sgiacomo.travaglini@arm.com``` 315313481Sgiacomo.travaglini@arm.com 315413481Sgiacomo.travaglini@arm.comNow, you can use this polymorphic action the same way you use the 315513481Sgiacomo.travaglini@arm.combuilt-in ones: 315613481Sgiacomo.travaglini@arm.com 315713481Sgiacomo.travaglini@arm.com``` 315813481Sgiacomo.travaglini@arm.comusing ::testing::_; 315913481Sgiacomo.travaglini@arm.com 316013481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 316113481Sgiacomo.travaglini@arm.com public: 316213481Sgiacomo.travaglini@arm.com MOCK_METHOD2(DoThis, int(bool flag, int n)); 316313481Sgiacomo.travaglini@arm.com MOCK_METHOD3(DoThat, string(int x, const char* str1, const char* str2)); 316413481Sgiacomo.travaglini@arm.com}; 316513481Sgiacomo.travaglini@arm.com... 316613481Sgiacomo.travaglini@arm.com 316713481Sgiacomo.travaglini@arm.com MockFoo foo; 316813481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThis(_, _)) 316913481Sgiacomo.travaglini@arm.com .WillOnce(ReturnSecondArgument()); 317013481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, DoThat(_, _, _)) 317113481Sgiacomo.travaglini@arm.com .WillOnce(ReturnSecondArgument()); 317213481Sgiacomo.travaglini@arm.com ... 317313481Sgiacomo.travaglini@arm.com foo.DoThis(true, 5); // Will return 5. 317413481Sgiacomo.travaglini@arm.com foo.DoThat(1, "Hi", "Bye"); // Will return "Hi". 317513481Sgiacomo.travaglini@arm.com``` 317613481Sgiacomo.travaglini@arm.com 317713481Sgiacomo.travaglini@arm.com## Teaching Google Mock How to Print Your Values ## 317813481Sgiacomo.travaglini@arm.com 317913481Sgiacomo.travaglini@arm.comWhen an uninteresting or unexpected call occurs, Google Mock prints 318013481Sgiacomo.travaglini@arm.comthe argument values to help you debug. The `EXPECT_THAT` and 318113481Sgiacomo.travaglini@arm.com`ASSERT_THAT` assertions also print the value being validated when the 318213481Sgiacomo.travaglini@arm.comtest fails. Google Mock does this using the user-extensible value 318313481Sgiacomo.travaglini@arm.comprinter defined in `<gmock/gmock-printers.h>`. 318413481Sgiacomo.travaglini@arm.com 318513481Sgiacomo.travaglini@arm.comThis printer knows how to print the built-in C++ types, native arrays, 318613481Sgiacomo.travaglini@arm.comSTL containers, and any type that supports the `<<` operator. For 318713481Sgiacomo.travaglini@arm.comother types, it prints the raw bytes in the value and hope you the 318813481Sgiacomo.travaglini@arm.comuser can figure it out. 318913481Sgiacomo.travaglini@arm.com 319013481Sgiacomo.travaglini@arm.comDid I say that the printer is `extensible`? That means you can teach 319113481Sgiacomo.travaglini@arm.comit to do a better job at printing your particular type than to dump 319213481Sgiacomo.travaglini@arm.comthe bytes. To do that, you just need to define `<<` for your type: 319313481Sgiacomo.travaglini@arm.com 319413481Sgiacomo.travaglini@arm.com``` 319513481Sgiacomo.travaglini@arm.com#include <iostream> 319613481Sgiacomo.travaglini@arm.com 319713481Sgiacomo.travaglini@arm.comnamespace foo { 319813481Sgiacomo.travaglini@arm.com 319913481Sgiacomo.travaglini@arm.comclass Foo { ... }; 320013481Sgiacomo.travaglini@arm.com 320113481Sgiacomo.travaglini@arm.com// It's important that the << operator is defined in the SAME 320213481Sgiacomo.travaglini@arm.com// namespace that defines Foo. C++'s look-up rules rely on that. 320313481Sgiacomo.travaglini@arm.com::std::ostream& operator<<(::std::ostream& os, const Foo& foo) { 320413481Sgiacomo.travaglini@arm.com return os << foo.DebugString(); // Whatever needed to print foo to os. 320513481Sgiacomo.travaglini@arm.com} 320613481Sgiacomo.travaglini@arm.com 320713481Sgiacomo.travaglini@arm.com} // namespace foo 320813481Sgiacomo.travaglini@arm.com``` 320913481Sgiacomo.travaglini@arm.com 321013481Sgiacomo.travaglini@arm.comSometimes, this might not be an option. For example, your team may 321113481Sgiacomo.travaglini@arm.comconsider it dangerous or bad style to have a `<<` operator for `Foo`, 321213481Sgiacomo.travaglini@arm.comor `Foo` may already have a `<<` operator that doesn't do what you 321313481Sgiacomo.travaglini@arm.comwant (and you cannot change it). Don't despair though - Google Mock 321413481Sgiacomo.travaglini@arm.comgives you a second chance to get it right. Namely, you can define a 321513481Sgiacomo.travaglini@arm.com`PrintTo()` function like this: 321613481Sgiacomo.travaglini@arm.com 321713481Sgiacomo.travaglini@arm.com``` 321813481Sgiacomo.travaglini@arm.com#include <iostream> 321913481Sgiacomo.travaglini@arm.com 322013481Sgiacomo.travaglini@arm.comnamespace foo { 322113481Sgiacomo.travaglini@arm.com 322213481Sgiacomo.travaglini@arm.comclass Foo { ... }; 322313481Sgiacomo.travaglini@arm.com 322413481Sgiacomo.travaglini@arm.com// It's important that PrintTo() is defined in the SAME 322513481Sgiacomo.travaglini@arm.com// namespace that defines Foo. C++'s look-up rules rely on that. 322613481Sgiacomo.travaglini@arm.comvoid PrintTo(const Foo& foo, ::std::ostream* os) { 322713481Sgiacomo.travaglini@arm.com *os << foo.DebugString(); // Whatever needed to print foo to os. 322813481Sgiacomo.travaglini@arm.com} 322913481Sgiacomo.travaglini@arm.com 323013481Sgiacomo.travaglini@arm.com} // namespace foo 323113481Sgiacomo.travaglini@arm.com``` 323213481Sgiacomo.travaglini@arm.com 323313481Sgiacomo.travaglini@arm.comWhat if you have both `<<` and `PrintTo()`? In this case, the latter 323413481Sgiacomo.travaglini@arm.comwill override the former when Google Mock is concerned. This allows 323513481Sgiacomo.travaglini@arm.comyou to customize how the value should appear in Google Mock's output 323613481Sgiacomo.travaglini@arm.comwithout affecting code that relies on the behavior of its `<<` 323713481Sgiacomo.travaglini@arm.comoperator. 323813481Sgiacomo.travaglini@arm.com 323913481Sgiacomo.travaglini@arm.com**Note:** When printing a pointer of type `T*`, Google Mock calls 324013481Sgiacomo.travaglini@arm.com`PrintTo(T*, std::ostream* os)` instead of `operator<<(std::ostream&, T*)`. 324113481Sgiacomo.travaglini@arm.comTherefore the only way to affect how a pointer is printed by Google 324213481Sgiacomo.travaglini@arm.comMock is to define `PrintTo()` for it. Also note that `T*` and `const T*` 324313481Sgiacomo.travaglini@arm.comare different types, so you may need to define `PrintTo()` for both. 324413481Sgiacomo.travaglini@arm.com 324513481Sgiacomo.travaglini@arm.comWhy does Google Mock treat pointers specially? There are several reasons: 324613481Sgiacomo.travaglini@arm.com 324713481Sgiacomo.travaglini@arm.com * We cannot use `operator<<` to print a `signed char*` or `unsigned char*`, since it will print the pointer as a NUL-terminated C string, which likely will cause an access violation. 324813481Sgiacomo.travaglini@arm.com * We want `NULL` pointers to be printed as `"NULL"`, but `operator<<` prints it as `"0"`, `"nullptr"`, or something else, depending on the compiler. 324913481Sgiacomo.travaglini@arm.com * With some compilers, printing a `NULL` `char*` using `operator<<` will segfault. 325013481Sgiacomo.travaglini@arm.com * `operator<<` prints a function pointer as a `bool` (hence it always prints `"1"`), which is not very useful.