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