113481Sgiacomo.travaglini@arm.com 213481Sgiacomo.travaglini@arm.com 313481Sgiacomo.travaglini@arm.com# Defining a Mock Class # 413481Sgiacomo.travaglini@arm.com 513481Sgiacomo.travaglini@arm.com## Mocking a Normal Class ## 613481Sgiacomo.travaglini@arm.com 713481Sgiacomo.travaglini@arm.comGiven 813481Sgiacomo.travaglini@arm.com``` 913481Sgiacomo.travaglini@arm.comclass Foo { 1013481Sgiacomo.travaglini@arm.com ... 1113481Sgiacomo.travaglini@arm.com virtual ~Foo(); 1213481Sgiacomo.travaglini@arm.com virtual int GetSize() const = 0; 1313481Sgiacomo.travaglini@arm.com virtual string Describe(const char* name) = 0; 1413481Sgiacomo.travaglini@arm.com virtual string Describe(int type) = 0; 1513481Sgiacomo.travaglini@arm.com virtual bool Process(Bar elem, int count) = 0; 1613481Sgiacomo.travaglini@arm.com}; 1713481Sgiacomo.travaglini@arm.com``` 1813481Sgiacomo.travaglini@arm.com(note that `~Foo()` **must** be virtual) we can define its mock as 1913481Sgiacomo.travaglini@arm.com``` 2013481Sgiacomo.travaglini@arm.com#include <gmock/gmock.h> 2113481Sgiacomo.travaglini@arm.com 2213481Sgiacomo.travaglini@arm.comclass MockFoo : public Foo { 2313481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD0(GetSize, int()); 2413481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Describe, string(const char* name)); 2513481Sgiacomo.travaglini@arm.com MOCK_METHOD1(Describe, string(int type)); 2613481Sgiacomo.travaglini@arm.com MOCK_METHOD2(Process, bool(Bar elem, int count)); 2713481Sgiacomo.travaglini@arm.com}; 2813481Sgiacomo.travaglini@arm.com``` 2913481Sgiacomo.travaglini@arm.com 3013481Sgiacomo.travaglini@arm.comTo create a "nice" mock object which ignores all uninteresting calls, 3113481Sgiacomo.travaglini@arm.comor a "strict" mock object, which treats them as failures: 3213481Sgiacomo.travaglini@arm.com``` 3313481Sgiacomo.travaglini@arm.comNiceMock<MockFoo> nice_foo; // The type is a subclass of MockFoo. 3413481Sgiacomo.travaglini@arm.comStrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo. 3513481Sgiacomo.travaglini@arm.com``` 3613481Sgiacomo.travaglini@arm.com 3713481Sgiacomo.travaglini@arm.com## Mocking a Class Template ## 3813481Sgiacomo.travaglini@arm.com 3913481Sgiacomo.travaglini@arm.comTo mock 4013481Sgiacomo.travaglini@arm.com``` 4113481Sgiacomo.travaglini@arm.comtemplate <typename Elem> 4213481Sgiacomo.travaglini@arm.comclass StackInterface { 4313481Sgiacomo.travaglini@arm.com public: 4413481Sgiacomo.travaglini@arm.com ... 4513481Sgiacomo.travaglini@arm.com virtual ~StackInterface(); 4613481Sgiacomo.travaglini@arm.com virtual int GetSize() const = 0; 4713481Sgiacomo.travaglini@arm.com virtual void Push(const Elem& x) = 0; 4813481Sgiacomo.travaglini@arm.com}; 4913481Sgiacomo.travaglini@arm.com``` 5013481Sgiacomo.travaglini@arm.com(note that `~StackInterface()` **must** be virtual) just append `_T` to the `MOCK_*` macros: 5113481Sgiacomo.travaglini@arm.com``` 5213481Sgiacomo.travaglini@arm.comtemplate <typename Elem> 5313481Sgiacomo.travaglini@arm.comclass MockStack : public StackInterface<Elem> { 5413481Sgiacomo.travaglini@arm.com public: 5513481Sgiacomo.travaglini@arm.com ... 5613481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD0_T(GetSize, int()); 5713481Sgiacomo.travaglini@arm.com MOCK_METHOD1_T(Push, void(const Elem& x)); 5813481Sgiacomo.travaglini@arm.com}; 5913481Sgiacomo.travaglini@arm.com``` 6013481Sgiacomo.travaglini@arm.com 6113481Sgiacomo.travaglini@arm.com## Specifying Calling Conventions for Mock Functions ## 6213481Sgiacomo.travaglini@arm.com 6313481Sgiacomo.travaglini@arm.comIf your mock function doesn't use the default calling convention, you 6413481Sgiacomo.travaglini@arm.comcan specify it by appending `_WITH_CALLTYPE` to any of the macros 6513481Sgiacomo.travaglini@arm.comdescribed in the previous two sections and supplying the calling 6613481Sgiacomo.travaglini@arm.comconvention as the first argument to the macro. For example, 6713481Sgiacomo.travaglini@arm.com``` 6813481Sgiacomo.travaglini@arm.com MOCK_METHOD_1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int n)); 6913481Sgiacomo.travaglini@arm.com MOCK_CONST_METHOD2_WITH_CALLTYPE(STDMETHODCALLTYPE, Bar, int(double x, double y)); 7013481Sgiacomo.travaglini@arm.com``` 7113481Sgiacomo.travaglini@arm.comwhere `STDMETHODCALLTYPE` is defined by `<objbase.h>` on Windows. 7213481Sgiacomo.travaglini@arm.com 7313481Sgiacomo.travaglini@arm.com# Using Mocks in Tests # 7413481Sgiacomo.travaglini@arm.com 7513481Sgiacomo.travaglini@arm.comThe typical flow is: 7613481Sgiacomo.travaglini@arm.com 1. Import the Google Mock names you need to use. All Google Mock names are in the `testing` namespace unless they are macros or otherwise noted. 7713481Sgiacomo.travaglini@arm.com 1. Create the mock objects. 7813481Sgiacomo.travaglini@arm.com 1. Optionally, set the default actions of the mock objects. 7913481Sgiacomo.travaglini@arm.com 1. Set your expectations on the mock objects (How will they be called? What wil they do?). 8013481Sgiacomo.travaglini@arm.com 1. Exercise code that uses the mock objects; if necessary, check the result using [Google Test](http://code.google.com/p/googletest/) assertions. 8113481Sgiacomo.travaglini@arm.com 1. When a mock objects is destructed, Google Mock automatically verifies that all expectations on it have been satisfied. 8213481Sgiacomo.travaglini@arm.com 8313481Sgiacomo.travaglini@arm.comHere is an example: 8413481Sgiacomo.travaglini@arm.com``` 8513481Sgiacomo.travaglini@arm.comusing ::testing::Return; // #1 8613481Sgiacomo.travaglini@arm.com 8713481Sgiacomo.travaglini@arm.comTEST(BarTest, DoesThis) { 8813481Sgiacomo.travaglini@arm.com MockFoo foo; // #2 8913481Sgiacomo.travaglini@arm.com 9013481Sgiacomo.travaglini@arm.com ON_CALL(foo, GetSize()) // #3 9113481Sgiacomo.travaglini@arm.com .WillByDefault(Return(1)); 9213481Sgiacomo.travaglini@arm.com // ... other default actions ... 9313481Sgiacomo.travaglini@arm.com 9413481Sgiacomo.travaglini@arm.com EXPECT_CALL(foo, Describe(5)) // #4 9513481Sgiacomo.travaglini@arm.com .Times(3) 9613481Sgiacomo.travaglini@arm.com .WillRepeatedly(Return("Category 5")); 9713481Sgiacomo.travaglini@arm.com // ... other expectations ... 9813481Sgiacomo.travaglini@arm.com 9913481Sgiacomo.travaglini@arm.com EXPECT_EQ("good", MyProductionFunction(&foo)); // #5 10013481Sgiacomo.travaglini@arm.com} // #6 10113481Sgiacomo.travaglini@arm.com``` 10213481Sgiacomo.travaglini@arm.com 10313481Sgiacomo.travaglini@arm.com# Setting Default Actions # 10413481Sgiacomo.travaglini@arm.com 10513481Sgiacomo.travaglini@arm.comGoogle Mock has a **built-in default action** for any function that 10613481Sgiacomo.travaglini@arm.comreturns `void`, `bool`, a numeric value, or a pointer. 10713481Sgiacomo.travaglini@arm.com 10813481Sgiacomo.travaglini@arm.comTo customize the default action for functions with return type `T` globally: 10913481Sgiacomo.travaglini@arm.com``` 11013481Sgiacomo.travaglini@arm.comusing ::testing::DefaultValue; 11113481Sgiacomo.travaglini@arm.com 11213481Sgiacomo.travaglini@arm.comDefaultValue<T>::Set(value); // Sets the default value to be returned. 11313481Sgiacomo.travaglini@arm.com// ... use the mocks ... 11413481Sgiacomo.travaglini@arm.comDefaultValue<T>::Clear(); // Resets the default value. 11513481Sgiacomo.travaglini@arm.com``` 11613481Sgiacomo.travaglini@arm.com 11713481Sgiacomo.travaglini@arm.comTo customize the default action for a particular method, use `ON_CALL()`: 11813481Sgiacomo.travaglini@arm.com``` 11913481Sgiacomo.travaglini@arm.comON_CALL(mock_object, method(matchers)) 12013481Sgiacomo.travaglini@arm.com .With(multi_argument_matcher) ? 12113481Sgiacomo.travaglini@arm.com .WillByDefault(action); 12213481Sgiacomo.travaglini@arm.com``` 12313481Sgiacomo.travaglini@arm.com 12413481Sgiacomo.travaglini@arm.com# Setting Expectations # 12513481Sgiacomo.travaglini@arm.com 12613481Sgiacomo.travaglini@arm.com`EXPECT_CALL()` sets **expectations** on a mock method (How will it be 12713481Sgiacomo.travaglini@arm.comcalled? What will it do?): 12813481Sgiacomo.travaglini@arm.com``` 12913481Sgiacomo.travaglini@arm.comEXPECT_CALL(mock_object, method(matchers)) 13013481Sgiacomo.travaglini@arm.com .With(multi_argument_matcher) ? 13113481Sgiacomo.travaglini@arm.com .Times(cardinality) ? 13213481Sgiacomo.travaglini@arm.com .InSequence(sequences) * 13313481Sgiacomo.travaglini@arm.com .After(expectations) * 13413481Sgiacomo.travaglini@arm.com .WillOnce(action) * 13513481Sgiacomo.travaglini@arm.com .WillRepeatedly(action) ? 13613481Sgiacomo.travaglini@arm.com .RetiresOnSaturation(); ? 13713481Sgiacomo.travaglini@arm.com``` 13813481Sgiacomo.travaglini@arm.com 13913481Sgiacomo.travaglini@arm.comIf `Times()` is omitted, the cardinality is assumed to be: 14013481Sgiacomo.travaglini@arm.com 14113481Sgiacomo.travaglini@arm.com * `Times(1)` when there is neither `WillOnce()` nor `WillRepeatedly()`; 14213481Sgiacomo.travaglini@arm.com * `Times(n)` when there are `n WillOnce()`s but no `WillRepeatedly()`, where `n` >= 1; or 14313481Sgiacomo.travaglini@arm.com * `Times(AtLeast(n))` when there are `n WillOnce()`s and a `WillRepeatedly()`, where `n` >= 0. 14413481Sgiacomo.travaglini@arm.com 14513481Sgiacomo.travaglini@arm.comA method with no `EXPECT_CALL()` is free to be invoked _any number of times_, and the default action will be taken each time. 14613481Sgiacomo.travaglini@arm.com 14713481Sgiacomo.travaglini@arm.com# Matchers # 14813481Sgiacomo.travaglini@arm.com 14913481Sgiacomo.travaglini@arm.comA **matcher** matches a _single_ argument. You can use it inside 15013481Sgiacomo.travaglini@arm.com`ON_CALL()` or `EXPECT_CALL()`, or use it to validate a value 15113481Sgiacomo.travaglini@arm.comdirectly: 15213481Sgiacomo.travaglini@arm.com 15313481Sgiacomo.travaglini@arm.com| `EXPECT_THAT(value, matcher)` | Asserts that `value` matches `matcher`. | 15413481Sgiacomo.travaglini@arm.com|:------------------------------|:----------------------------------------| 15513481Sgiacomo.travaglini@arm.com| `ASSERT_THAT(value, matcher)` | The same as `EXPECT_THAT(value, matcher)`, except that it generates a **fatal** failure. | 15613481Sgiacomo.travaglini@arm.com 15713481Sgiacomo.travaglini@arm.comBuilt-in matchers (where `argument` is the function argument) are 15813481Sgiacomo.travaglini@arm.comdivided into several categories: 15913481Sgiacomo.travaglini@arm.com 16013481Sgiacomo.travaglini@arm.com## Wildcard ## 16113481Sgiacomo.travaglini@arm.com|`_`|`argument` can be any value of the correct type.| 16213481Sgiacomo.travaglini@arm.com|:--|:-----------------------------------------------| 16313481Sgiacomo.travaglini@arm.com|`A<type>()` or `An<type>()`|`argument` can be any value of type `type`. | 16413481Sgiacomo.travaglini@arm.com 16513481Sgiacomo.travaglini@arm.com## Generic Comparison ## 16613481Sgiacomo.travaglini@arm.com 16713481Sgiacomo.travaglini@arm.com|`Eq(value)` or `value`|`argument == value`| 16813481Sgiacomo.travaglini@arm.com|:---------------------|:------------------| 16913481Sgiacomo.travaglini@arm.com|`Ge(value)` |`argument >= value`| 17013481Sgiacomo.travaglini@arm.com|`Gt(value)` |`argument > value` | 17113481Sgiacomo.travaglini@arm.com|`Le(value)` |`argument <= value`| 17213481Sgiacomo.travaglini@arm.com|`Lt(value)` |`argument < value` | 17313481Sgiacomo.travaglini@arm.com|`Ne(value)` |`argument != value`| 17413481Sgiacomo.travaglini@arm.com|`IsNull()` |`argument` is a `NULL` pointer (raw or smart).| 17513481Sgiacomo.travaglini@arm.com|`NotNull()` |`argument` is a non-null pointer (raw or smart).| 17613481Sgiacomo.travaglini@arm.com|`Ref(variable)` |`argument` is a reference to `variable`.| 17713481Sgiacomo.travaglini@arm.com|`TypedEq<type>(value)`|`argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded.| 17813481Sgiacomo.travaglini@arm.com 17913481Sgiacomo.travaglini@arm.comExcept `Ref()`, these matchers make a _copy_ of `value` in case it's 18013481Sgiacomo.travaglini@arm.commodified or destructed later. If the compiler complains that `value` 18113481Sgiacomo.travaglini@arm.comdoesn't have a public copy constructor, try wrap it in `ByRef()`, 18213481Sgiacomo.travaglini@arm.come.g. `Eq(ByRef(non_copyable_value))`. If you do that, make sure 18313481Sgiacomo.travaglini@arm.com`non_copyable_value` is not changed afterwards, or the meaning of your 18413481Sgiacomo.travaglini@arm.commatcher will be changed. 18513481Sgiacomo.travaglini@arm.com 18613481Sgiacomo.travaglini@arm.com## Floating-Point Matchers ## 18713481Sgiacomo.travaglini@arm.com 18813481Sgiacomo.travaglini@arm.com|`DoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal.| 18913481Sgiacomo.travaglini@arm.com|:-------------------|:----------------------------------------------------------------------------------------------| 19013481Sgiacomo.travaglini@arm.com|`FloatEq(a_float)` |`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. | 19113481Sgiacomo.travaglini@arm.com|`NanSensitiveDoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | 19213481Sgiacomo.travaglini@arm.com|`NanSensitiveFloatEq(a_float)`|`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. | 19313481Sgiacomo.travaglini@arm.com 19413481Sgiacomo.travaglini@arm.comThe above matchers use ULP-based comparison (the same as used in 19513481Sgiacomo.travaglini@arm.com[Google Test](http://code.google.com/p/googletest/)). They 19613481Sgiacomo.travaglini@arm.comautomatically pick a reasonable error bound based on the absolute 19713481Sgiacomo.travaglini@arm.comvalue of the expected value. `DoubleEq()` and `FloatEq()` conform to 19813481Sgiacomo.travaglini@arm.comthe IEEE standard, which requires comparing two NaNs for equality to 19913481Sgiacomo.travaglini@arm.comreturn false. The `NanSensitive*` version instead treats two NaNs as 20013481Sgiacomo.travaglini@arm.comequal, which is often what a user wants. 20113481Sgiacomo.travaglini@arm.com 20213481Sgiacomo.travaglini@arm.com## String Matchers ## 20313481Sgiacomo.travaglini@arm.com 20413481Sgiacomo.travaglini@arm.comThe `argument` can be either a C string or a C++ string object: 20513481Sgiacomo.travaglini@arm.com 20613481Sgiacomo.travaglini@arm.com|`ContainsRegex(string)`|`argument` matches the given regular expression.| 20713481Sgiacomo.travaglini@arm.com|:----------------------|:-----------------------------------------------| 20813481Sgiacomo.travaglini@arm.com|`EndsWith(suffix)` |`argument` ends with string `suffix`. | 20913481Sgiacomo.travaglini@arm.com|`HasSubstr(string)` |`argument` contains `string` as a sub-string. | 21013481Sgiacomo.travaglini@arm.com|`MatchesRegex(string)` |`argument` matches the given regular expression with the match starting at the first character and ending at the last character.| 21113481Sgiacomo.travaglini@arm.com|`StartsWith(prefix)` |`argument` starts with string `prefix`. | 21213481Sgiacomo.travaglini@arm.com|`StrCaseEq(string)` |`argument` is equal to `string`, ignoring case. | 21313481Sgiacomo.travaglini@arm.com|`StrCaseNe(string)` |`argument` is not equal to `string`, ignoring case.| 21413481Sgiacomo.travaglini@arm.com|`StrEq(string)` |`argument` is equal to `string`. | 21513481Sgiacomo.travaglini@arm.com|`StrNe(string)` |`argument` is not equal to `string`. | 21613481Sgiacomo.travaglini@arm.com 21713481Sgiacomo.travaglini@arm.com`StrCaseEq()`, `StrCaseNe()`, `StrEq()`, and `StrNe()` work for wide 21813481Sgiacomo.travaglini@arm.comstrings as well. 21913481Sgiacomo.travaglini@arm.com 22013481Sgiacomo.travaglini@arm.com## Container Matchers ## 22113481Sgiacomo.travaglini@arm.com 22213481Sgiacomo.travaglini@arm.comMost STL-style containers support `==`, so you can use 22313481Sgiacomo.travaglini@arm.com`Eq(expected_container)` or simply `expected_container` to match a 22413481Sgiacomo.travaglini@arm.comcontainer exactly. If you want to write the elements in-line, 22513481Sgiacomo.travaglini@arm.commatch them more flexibly, or get more informative messages, you can use: 22613481Sgiacomo.travaglini@arm.com 22713481Sgiacomo.travaglini@arm.com| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. | 22813481Sgiacomo.travaglini@arm.com|:--------------|:-------------------------------------------------------------------------------------------| 22913481Sgiacomo.travaglini@arm.com|`ElementsAre(e0, e1, ..., en)`|`argument` has `n + 1` elements, where the i-th element matches `ei`, which can be a value or a matcher. 0 to 10 arguments are allowed.| 23013481Sgiacomo.travaglini@arm.com|`ElementsAreArray(array)` or `ElementsAreArray(array, count)`|The same as `ElementsAre()` except that the expected element values/matchers come from a C-style array.| 23113481Sgiacomo.travaglini@arm.com| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. | 23213481Sgiacomo.travaglini@arm.com 23313481Sgiacomo.travaglini@arm.comThese matchers can also match: 23413481Sgiacomo.travaglini@arm.com 23513481Sgiacomo.travaglini@arm.com 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`), and 23613481Sgiacomo.travaglini@arm.com 1. an array passed as a pointer and a count (e.g. in `Bar(const T* buffer, int len)` -- see [Multi-argument Matchers](#Multiargument_Matchers.md)). 23713481Sgiacomo.travaglini@arm.com 23813481Sgiacomo.travaglini@arm.comwhere the array may be multi-dimensional (i.e. its elements can be arrays). 23913481Sgiacomo.travaglini@arm.com 24013481Sgiacomo.travaglini@arm.com## Member Matchers ## 24113481Sgiacomo.travaglini@arm.com 24213481Sgiacomo.travaglini@arm.com|`Field(&class::field, m)`|`argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_.| 24313481Sgiacomo.travaglini@arm.com|:------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------| 24413481Sgiacomo.travaglini@arm.com|`Key(e)` |`argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`.| 24513481Sgiacomo.travaglini@arm.com|`Pair(m1, m2)` |`argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. | 24613481Sgiacomo.travaglini@arm.com|`Property(&class::property, m)`|`argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_.| 24713481Sgiacomo.travaglini@arm.com 24813481Sgiacomo.travaglini@arm.com## Matching the Result of a Function or Functor ## 24913481Sgiacomo.travaglini@arm.com 25013481Sgiacomo.travaglini@arm.com|`ResultOf(f, m)`|`f(argument)` matches matcher `m`, where `f` is a function or functor.| 25113481Sgiacomo.travaglini@arm.com|:---------------|:---------------------------------------------------------------------| 25213481Sgiacomo.travaglini@arm.com 25313481Sgiacomo.travaglini@arm.com## Pointer Matchers ## 25413481Sgiacomo.travaglini@arm.com 25513481Sgiacomo.travaglini@arm.com|`Pointee(m)`|`argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`.| 25613481Sgiacomo.travaglini@arm.com|:-----------|:-----------------------------------------------------------------------------------------------| 25713481Sgiacomo.travaglini@arm.com 25813481Sgiacomo.travaglini@arm.com## Multiargument Matchers ## 25913481Sgiacomo.travaglini@arm.com 26013481Sgiacomo.travaglini@arm.comThese are matchers on tuple types. They can be used in 26113481Sgiacomo.travaglini@arm.com`.With()`. The following can be used on functions with <i>two<br> 26213481Sgiacomo.travaglini@arm.comarguments</i> `x` and `y`: 26313481Sgiacomo.travaglini@arm.com 26413481Sgiacomo.travaglini@arm.com|`Eq()`|`x == y`| 26513481Sgiacomo.travaglini@arm.com|:-----|:-------| 26613481Sgiacomo.travaglini@arm.com|`Ge()`|`x >= y`| 26713481Sgiacomo.travaglini@arm.com|`Gt()`|`x > y` | 26813481Sgiacomo.travaglini@arm.com|`Le()`|`x <= y`| 26913481Sgiacomo.travaglini@arm.com|`Lt()`|`x < y` | 27013481Sgiacomo.travaglini@arm.com|`Ne()`|`x != y`| 27113481Sgiacomo.travaglini@arm.com 27213481Sgiacomo.travaglini@arm.comYou can use the following selectors to pick a subset of the arguments 27313481Sgiacomo.travaglini@arm.com(or reorder them) to participate in the matching: 27413481Sgiacomo.travaglini@arm.com 27513481Sgiacomo.travaglini@arm.com|`AllArgs(m)`|Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`.| 27613481Sgiacomo.travaglini@arm.com|:-----------|:-------------------------------------------------------------------| 27713481Sgiacomo.travaglini@arm.com|`Args<N1, N2, ..., Nk>(m)`|The `k` selected (using 0-based indices) arguments match `m`, e.g. `Args<1, 2>(Contains(5))`.| 27813481Sgiacomo.travaglini@arm.com 27913481Sgiacomo.travaglini@arm.com## Composite Matchers ## 28013481Sgiacomo.travaglini@arm.com 28113481Sgiacomo.travaglini@arm.comYou can make a matcher from one or more other matchers: 28213481Sgiacomo.travaglini@arm.com 28313481Sgiacomo.travaglini@arm.com|`AllOf(m1, m2, ..., mn)`|`argument` matches all of the matchers `m1` to `mn`.| 28413481Sgiacomo.travaglini@arm.com|:-----------------------|:---------------------------------------------------| 28513481Sgiacomo.travaglini@arm.com|`AnyOf(m1, m2, ..., mn)`|`argument` matches at least one of the matchers `m1` to `mn`.| 28613481Sgiacomo.travaglini@arm.com|`Not(m)` |`argument` doesn't match matcher `m`. | 28713481Sgiacomo.travaglini@arm.com 28813481Sgiacomo.travaglini@arm.com## Adapters for Matchers ## 28913481Sgiacomo.travaglini@arm.com 29013481Sgiacomo.travaglini@arm.com|`MatcherCast<T>(m)`|casts matcher `m` to type `Matcher<T>`.| 29113481Sgiacomo.travaglini@arm.com|:------------------|:--------------------------------------| 29213481Sgiacomo.travaglini@arm.com|`SafeMatcherCast<T>(m)`| [safely casts](V1_5_CookBook#Casting_Matchers.md) matcher `m` to type `Matcher<T>`. | 29313481Sgiacomo.travaglini@arm.com|`Truly(predicate)` |`predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor.| 29413481Sgiacomo.travaglini@arm.com 29513481Sgiacomo.travaglini@arm.com## Matchers as Predicates ## 29613481Sgiacomo.travaglini@arm.com 29713481Sgiacomo.travaglini@arm.com|`Matches(m)`|a unary functor that returns `true` if the argument matches `m`.| 29813481Sgiacomo.travaglini@arm.com|:-----------|:---------------------------------------------------------------| 29913481Sgiacomo.travaglini@arm.com|`ExplainMatchResult(m, value, result_listener)`|returns `true` if `value` matches `m`, explaining the result to `result_listener`.| 30013481Sgiacomo.travaglini@arm.com|`Value(x, m)`|returns `true` if the value of `x` matches `m`. | 30113481Sgiacomo.travaglini@arm.com 30213481Sgiacomo.travaglini@arm.com## Defining Matchers ## 30313481Sgiacomo.travaglini@arm.com 30413481Sgiacomo.travaglini@arm.com| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. | 30513481Sgiacomo.travaglini@arm.com|:-------------------------------------------------|:------------------------------------------------------| 30613481Sgiacomo.travaglini@arm.com| `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a macher `IsDivisibleBy(n)` to match a number divisible by `n`. | 30713481Sgiacomo.travaglini@arm.com| `MATCHER_P2(IsBetween, a, b, "is between %(a)s and %(b)s") { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. | 30813481Sgiacomo.travaglini@arm.com 30913481Sgiacomo.travaglini@arm.com**Notes:** 31013481Sgiacomo.travaglini@arm.com 31113481Sgiacomo.travaglini@arm.com 1. The `MATCHER*` macros cannot be used inside a function or class. 31213481Sgiacomo.travaglini@arm.com 1. The matcher body 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). 31313481Sgiacomo.travaglini@arm.com 1. You can use `PrintToString(x)` to convert a value `x` of any type to a string. 31413481Sgiacomo.travaglini@arm.com 31513481Sgiacomo.travaglini@arm.com## Matchers as Test Assertions ## 31613481Sgiacomo.travaglini@arm.com 31713481Sgiacomo.travaglini@arm.com|`ASSERT_THAT(expression, m)`|Generates a [fatal failure](http://code.google.com/p/googletest/wiki/GoogleTestPrimer#Assertions) if the value of `expression` doesn't match matcher `m`.| 31813481Sgiacomo.travaglini@arm.com|:---------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------| 31913481Sgiacomo.travaglini@arm.com|`EXPECT_THAT(expression, m)`|Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`. | 32013481Sgiacomo.travaglini@arm.com 32113481Sgiacomo.travaglini@arm.com# Actions # 32213481Sgiacomo.travaglini@arm.com 32313481Sgiacomo.travaglini@arm.com**Actions** specify what a mock function should do when invoked. 32413481Sgiacomo.travaglini@arm.com 32513481Sgiacomo.travaglini@arm.com## Returning a Value ## 32613481Sgiacomo.travaglini@arm.com 32713481Sgiacomo.travaglini@arm.com|`Return()`|Return from a `void` mock function.| 32813481Sgiacomo.travaglini@arm.com|:---------|:----------------------------------| 32913481Sgiacomo.travaglini@arm.com|`Return(value)`|Return `value`. | 33013481Sgiacomo.travaglini@arm.com|`ReturnArg<N>()`|Return the `N`-th (0-based) argument.| 33113481Sgiacomo.travaglini@arm.com|`ReturnNew<T>(a1, ..., ak)`|Return `new T(a1, ..., ak)`; a different object is created each time.| 33213481Sgiacomo.travaglini@arm.com|`ReturnNull()`|Return a null pointer. | 33313481Sgiacomo.travaglini@arm.com|`ReturnRef(variable)`|Return a reference to `variable`. | 33413481Sgiacomo.travaglini@arm.com 33513481Sgiacomo.travaglini@arm.com## Side Effects ## 33613481Sgiacomo.travaglini@arm.com 33713481Sgiacomo.travaglini@arm.com|`Assign(&variable, value)`|Assign `value` to variable.| 33813481Sgiacomo.travaglini@arm.com|:-------------------------|:--------------------------| 33913481Sgiacomo.travaglini@arm.com| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. | 34013481Sgiacomo.travaglini@arm.com| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. | 34113481Sgiacomo.travaglini@arm.com| `SetArgReferee<N>(value)` | Assign value to the variable referenced by the `N`-th (0-based) argument. | 34213481Sgiacomo.travaglini@arm.com|`SetArgumentPointee<N>(value)`|Assign `value` to the variable pointed by the `N`-th (0-based) argument.| 34313481Sgiacomo.travaglini@arm.com|`SetArrayArgument<N>(first, last)`|Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range.| 34413481Sgiacomo.travaglini@arm.com|`SetErrnoAndReturn(error, value)`|Set `errno` to `error` and return `value`.| 34513481Sgiacomo.travaglini@arm.com|`Throw(exception)` |Throws the given exception, which can be any copyable value. Available since v1.1.0.| 34613481Sgiacomo.travaglini@arm.com 34713481Sgiacomo.travaglini@arm.com## Using a Function or a Functor as an Action ## 34813481Sgiacomo.travaglini@arm.com 34913481Sgiacomo.travaglini@arm.com|`Invoke(f)`|Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor.| 35013481Sgiacomo.travaglini@arm.com|:----------|:-----------------------------------------------------------------------------------------------------------------| 35113481Sgiacomo.travaglini@arm.com|`Invoke(object_pointer, &class::method)`|Invoke the {method on the object with the arguments passed to the mock function. | 35213481Sgiacomo.travaglini@arm.com|`InvokeWithoutArgs(f)`|Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. | 35313481Sgiacomo.travaglini@arm.com|`InvokeWithoutArgs(object_pointer, &class::method)`|Invoke the method on the object, which takes no arguments. | 35413481Sgiacomo.travaglini@arm.com|`InvokeArgument<N>(arg1, arg2, ..., argk)`|Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments.| 35513481Sgiacomo.travaglini@arm.com 35613481Sgiacomo.travaglini@arm.comThe return value of the invoked function is used as the return value 35713481Sgiacomo.travaglini@arm.comof the action. 35813481Sgiacomo.travaglini@arm.com 35913481Sgiacomo.travaglini@arm.comWhen defining a function or functor to be used with `Invoke*()`, you can declare any unused parameters as `Unused`: 36013481Sgiacomo.travaglini@arm.com``` 36113481Sgiacomo.travaglini@arm.com double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); } 36213481Sgiacomo.travaglini@arm.com ... 36313481Sgiacomo.travaglini@arm.com EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance)); 36413481Sgiacomo.travaglini@arm.com``` 36513481Sgiacomo.travaglini@arm.com 36613481Sgiacomo.travaglini@arm.comIn `InvokeArgument<N>(...)`, if an argument needs to be passed by reference, wrap it inside `ByRef()`. For example, 36713481Sgiacomo.travaglini@arm.com``` 36813481Sgiacomo.travaglini@arm.com InvokeArgument<2>(5, string("Hi"), ByRef(foo)) 36913481Sgiacomo.travaglini@arm.com``` 37013481Sgiacomo.travaglini@arm.comcalls the mock function's #2 argument, passing to it `5` and `string("Hi")` by value, and `foo` by reference. 37113481Sgiacomo.travaglini@arm.com 37213481Sgiacomo.travaglini@arm.com## Default Action ## 37313481Sgiacomo.travaglini@arm.com 37413481Sgiacomo.travaglini@arm.com|`DoDefault()`|Do the default action (specified by `ON_CALL()` or the built-in one).| 37513481Sgiacomo.travaglini@arm.com|:------------|:--------------------------------------------------------------------| 37613481Sgiacomo.travaglini@arm.com 37713481Sgiacomo.travaglini@arm.com**Note:** due to technical reasons, `DoDefault()` cannot be used inside a composite action - trying to do so will result in a run-time error. 37813481Sgiacomo.travaglini@arm.com 37913481Sgiacomo.travaglini@arm.com## Composite Actions ## 38013481Sgiacomo.travaglini@arm.com 38113481Sgiacomo.travaglini@arm.com|`DoAll(a1, a2, ..., an)`|Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void. | 38213481Sgiacomo.travaglini@arm.com|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------| 38313481Sgiacomo.travaglini@arm.com|`IgnoreResult(a)` |Perform action `a` and ignore its result. `a` must not return void. | 38413481Sgiacomo.travaglini@arm.com|`WithArg<N>(a)` |Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. | 38513481Sgiacomo.travaglini@arm.com|`WithArgs<N1, N2, ..., Nk>(a)`|Pass the selected (0-based) arguments of the mock function to action `a` and perform it. | 38613481Sgiacomo.travaglini@arm.com|`WithoutArgs(a)` |Perform action `a` without any arguments. | 38713481Sgiacomo.travaglini@arm.com 38813481Sgiacomo.travaglini@arm.com## Defining Actions ## 38913481Sgiacomo.travaglini@arm.com 39013481Sgiacomo.travaglini@arm.com| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. | 39113481Sgiacomo.travaglini@arm.com|:--------------------------------------|:---------------------------------------------------------------------------------------| 39213481Sgiacomo.travaglini@arm.com| `ACTION_P(Plus, n) { return arg0 + n; }` | Defines an action `Plus(n)` to return the sum of the mock function's argument #0 and `n`. | 39313481Sgiacomo.travaglini@arm.com| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. | 39413481Sgiacomo.travaglini@arm.com 39513481Sgiacomo.travaglini@arm.comThe `ACTION*` macros cannot be used inside a function or class. 39613481Sgiacomo.travaglini@arm.com 39713481Sgiacomo.travaglini@arm.com# Cardinalities # 39813481Sgiacomo.travaglini@arm.com 39913481Sgiacomo.travaglini@arm.comThese are used in `Times()` to specify how many times a mock function will be called: 40013481Sgiacomo.travaglini@arm.com 40113481Sgiacomo.travaglini@arm.com|`AnyNumber()`|The function can be called any number of times.| 40213481Sgiacomo.travaglini@arm.com|:------------|:----------------------------------------------| 40313481Sgiacomo.travaglini@arm.com|`AtLeast(n)` |The call is expected at least `n` times. | 40413481Sgiacomo.travaglini@arm.com|`AtMost(n)` |The call is expected at most `n` times. | 40513481Sgiacomo.travaglini@arm.com|`Between(m, n)`|The call is expected between `m` and `n` (inclusive) times.| 40613481Sgiacomo.travaglini@arm.com|`Exactly(n) or n`|The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0.| 40713481Sgiacomo.travaglini@arm.com 40813481Sgiacomo.travaglini@arm.com# Expectation Order # 40913481Sgiacomo.travaglini@arm.com 41013481Sgiacomo.travaglini@arm.comBy default, the expectations can be matched in _any_ order. If some 41113481Sgiacomo.travaglini@arm.comor all expectations must be matched in a given order, there are two 41213481Sgiacomo.travaglini@arm.comways to specify it. They can be used either independently or 41313481Sgiacomo.travaglini@arm.comtogether. 41413481Sgiacomo.travaglini@arm.com 41513481Sgiacomo.travaglini@arm.com## The After Clause ## 41613481Sgiacomo.travaglini@arm.com 41713481Sgiacomo.travaglini@arm.com``` 41813481Sgiacomo.travaglini@arm.comusing ::testing::Expectation; 41913481Sgiacomo.travaglini@arm.com... 42013481Sgiacomo.travaglini@arm.comExpectation init_x = EXPECT_CALL(foo, InitX()); 42113481Sgiacomo.travaglini@arm.comExpectation init_y = EXPECT_CALL(foo, InitY()); 42213481Sgiacomo.travaglini@arm.comEXPECT_CALL(foo, Bar()) 42313481Sgiacomo.travaglini@arm.com .After(init_x, init_y); 42413481Sgiacomo.travaglini@arm.com``` 42513481Sgiacomo.travaglini@arm.comsays that `Bar()` can be called only after both `InitX()` and 42613481Sgiacomo.travaglini@arm.com`InitY()` have been called. 42713481Sgiacomo.travaglini@arm.com 42813481Sgiacomo.travaglini@arm.comIf you don't know how many pre-requisites an expectation has when you 42913481Sgiacomo.travaglini@arm.comwrite it, you can use an `ExpectationSet` to collect them: 43013481Sgiacomo.travaglini@arm.com 43113481Sgiacomo.travaglini@arm.com``` 43213481Sgiacomo.travaglini@arm.comusing ::testing::ExpectationSet; 43313481Sgiacomo.travaglini@arm.com... 43413481Sgiacomo.travaglini@arm.comExpectationSet all_inits; 43513481Sgiacomo.travaglini@arm.comfor (int i = 0; i < element_count; i++) { 43613481Sgiacomo.travaglini@arm.com all_inits += EXPECT_CALL(foo, InitElement(i)); 43713481Sgiacomo.travaglini@arm.com} 43813481Sgiacomo.travaglini@arm.comEXPECT_CALL(foo, Bar()) 43913481Sgiacomo.travaglini@arm.com .After(all_inits); 44013481Sgiacomo.travaglini@arm.com``` 44113481Sgiacomo.travaglini@arm.comsays that `Bar()` can be called only after all elements have been 44213481Sgiacomo.travaglini@arm.cominitialized (but we don't care about which elements get initialized 44313481Sgiacomo.travaglini@arm.combefore the others). 44413481Sgiacomo.travaglini@arm.com 44513481Sgiacomo.travaglini@arm.comModifying an `ExpectationSet` after using it in an `.After()` doesn't 44613481Sgiacomo.travaglini@arm.comaffect the meaning of the `.After()`. 44713481Sgiacomo.travaglini@arm.com 44813481Sgiacomo.travaglini@arm.com## Sequences ## 44913481Sgiacomo.travaglini@arm.com 45013481Sgiacomo.travaglini@arm.comWhen you have a long chain of sequential expectations, it's easier to 45113481Sgiacomo.travaglini@arm.comspecify the order using **sequences**, which don't require you to given 45213481Sgiacomo.travaglini@arm.comeach expectation in the chain a different name. <i>All expected<br> 45313481Sgiacomo.travaglini@arm.comcalls</i> in the same sequence must occur in the order they are 45413481Sgiacomo.travaglini@arm.comspecified. 45513481Sgiacomo.travaglini@arm.com 45613481Sgiacomo.travaglini@arm.com``` 45713481Sgiacomo.travaglini@arm.comusing ::testing::Sequence; 45813481Sgiacomo.travaglini@arm.comSequence s1, s2; 45913481Sgiacomo.travaglini@arm.com... 46013481Sgiacomo.travaglini@arm.comEXPECT_CALL(foo, Reset()) 46113481Sgiacomo.travaglini@arm.com .InSequence(s1, s2) 46213481Sgiacomo.travaglini@arm.com .WillOnce(Return(true)); 46313481Sgiacomo.travaglini@arm.comEXPECT_CALL(foo, GetSize()) 46413481Sgiacomo.travaglini@arm.com .InSequence(s1) 46513481Sgiacomo.travaglini@arm.com .WillOnce(Return(1)); 46613481Sgiacomo.travaglini@arm.comEXPECT_CALL(foo, Describe(A<const char*>())) 46713481Sgiacomo.travaglini@arm.com .InSequence(s2) 46813481Sgiacomo.travaglini@arm.com .WillOnce(Return("dummy")); 46913481Sgiacomo.travaglini@arm.com``` 47013481Sgiacomo.travaglini@arm.comsays that `Reset()` must be called before _both_ `GetSize()` _and_ 47113481Sgiacomo.travaglini@arm.com`Describe()`, and the latter two can occur in any order. 47213481Sgiacomo.travaglini@arm.com 47313481Sgiacomo.travaglini@arm.comTo put many expectations in a sequence conveniently: 47413481Sgiacomo.travaglini@arm.com``` 47513481Sgiacomo.travaglini@arm.comusing ::testing::InSequence; 47613481Sgiacomo.travaglini@arm.com{ 47713481Sgiacomo.travaglini@arm.com InSequence dummy; 47813481Sgiacomo.travaglini@arm.com 47913481Sgiacomo.travaglini@arm.com EXPECT_CALL(...)...; 48013481Sgiacomo.travaglini@arm.com EXPECT_CALL(...)...; 48113481Sgiacomo.travaglini@arm.com ... 48213481Sgiacomo.travaglini@arm.com EXPECT_CALL(...)...; 48313481Sgiacomo.travaglini@arm.com} 48413481Sgiacomo.travaglini@arm.com``` 48513481Sgiacomo.travaglini@arm.comsays that all expected calls in the scope of `dummy` must occur in 48613481Sgiacomo.travaglini@arm.comstrict order. The name `dummy` is irrelevant.) 48713481Sgiacomo.travaglini@arm.com 48813481Sgiacomo.travaglini@arm.com# Verifying and Resetting a Mock # 48913481Sgiacomo.travaglini@arm.com 49013481Sgiacomo.travaglini@arm.comGoogle Mock will verify the expectations on a mock object when it is destructed, or you can do it earlier: 49113481Sgiacomo.travaglini@arm.com``` 49213481Sgiacomo.travaglini@arm.comusing ::testing::Mock; 49313481Sgiacomo.travaglini@arm.com... 49413481Sgiacomo.travaglini@arm.com// Verifies and removes the expectations on mock_obj; 49513481Sgiacomo.travaglini@arm.com// returns true iff successful. 49613481Sgiacomo.travaglini@arm.comMock::VerifyAndClearExpectations(&mock_obj); 49713481Sgiacomo.travaglini@arm.com... 49813481Sgiacomo.travaglini@arm.com// Verifies and removes the expectations on mock_obj; 49913481Sgiacomo.travaglini@arm.com// also removes the default actions set by ON_CALL(); 50013481Sgiacomo.travaglini@arm.com// returns true iff successful. 50113481Sgiacomo.travaglini@arm.comMock::VerifyAndClear(&mock_obj); 50213481Sgiacomo.travaglini@arm.com``` 50313481Sgiacomo.travaglini@arm.com 50413481Sgiacomo.travaglini@arm.comYou can also tell Google Mock that a mock object can be leaked and doesn't 50513481Sgiacomo.travaglini@arm.comneed to be verified: 50613481Sgiacomo.travaglini@arm.com``` 50713481Sgiacomo.travaglini@arm.comMock::AllowLeak(&mock_obj); 50813481Sgiacomo.travaglini@arm.com``` 50913481Sgiacomo.travaglini@arm.com 51013481Sgiacomo.travaglini@arm.com# Mock Classes # 51113481Sgiacomo.travaglini@arm.com 51213481Sgiacomo.travaglini@arm.comGoogle Mock defines a convenient mock class template 51313481Sgiacomo.travaglini@arm.com``` 51413481Sgiacomo.travaglini@arm.comclass MockFunction<R(A1, ..., An)> { 51513481Sgiacomo.travaglini@arm.com public: 51613481Sgiacomo.travaglini@arm.com MOCK_METHODn(Call, R(A1, ..., An)); 51713481Sgiacomo.travaglini@arm.com}; 51813481Sgiacomo.travaglini@arm.com``` 51913481Sgiacomo.travaglini@arm.comSee this [recipe](V1_5_CookBook#Using_Check_Points.md) for one application of it. 52013481Sgiacomo.travaglini@arm.com 52113481Sgiacomo.travaglini@arm.com# Flags # 52213481Sgiacomo.travaglini@arm.com 52313481Sgiacomo.travaglini@arm.com| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. | 52413481Sgiacomo.travaglini@arm.com|:-------------------------------|:----------------------------------------------| 52513481Sgiacomo.travaglini@arm.com| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. |