+

+

+# Defining a Mock Class #

+

+## Mocking a Normal Class ##

+

+Given

+```

+class Foo {

+ ...

+ virtual ~Foo();

+ virtual int GetSize() const = 0;

+ virtual string Describe(const char* name) = 0;

+ virtual string Describe(int type) = 0;

+ virtual bool Process(Bar elem, int count) = 0;

+};

+```

+(note that `~Foo()` **must** be virtual) we can define its mock as

+```

+#include <gmock/gmock.h>

+

+class MockFoo : public Foo {

+ MOCK_CONST_METHOD0(GetSize, int());

+ MOCK_METHOD1(Describe, string(const char* name));

+ MOCK_METHOD1(Describe, string(int type));

+ MOCK_METHOD2(Process, bool(Bar elem, int count));

+};

+```

+

+To create a "nice" mock object which ignores all uninteresting calls,

+or a "strict" mock object, which treats them as failures:

+```

+NiceMock<MockFoo> nice_foo; // The type is a subclass of MockFoo.

+StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo.

+```

+

+## Mocking a Class Template ##

+

+To mock

+```

+template <typename Elem>

+class StackInterface {

+ public:

+ ...

+ virtual ~StackInterface();

+ virtual int GetSize() const = 0;

+ virtual void Push(const Elem& x) = 0;

+};

+```

+(note that `~StackInterface()` **must** be virtual) just append `_T` to the `MOCK_*` macros:

+```

+template <typename Elem>

+class MockStack : public StackInterface<Elem> {

+ public:

+ ...

+ MOCK_CONST_METHOD0_T(GetSize, int());

+ MOCK_METHOD1_T(Push, void(const Elem& x));

+};

+```

+

+## Specifying Calling Conventions for Mock Functions ##

+

+If your mock function doesn't use the default calling convention, you

+can specify it by appending `_WITH_CALLTYPE` to any of the macros

+described in the previous two sections and supplying the calling

+convention as the first argument to the macro. For example,

+```

+ MOCK_METHOD_1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int n));

+ MOCK_CONST_METHOD2_WITH_CALLTYPE(STDMETHODCALLTYPE, Bar, int(double x, double y));

+```

+where `STDMETHODCALLTYPE` is defined by `<objbase.h>` on Windows.

+

+# Using Mocks in Tests #

+

+The typical flow is:

+ 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.

+ 1. Create the mock objects.

+ 1. Optionally, set the default actions of the mock objects.

+ 1. Set your expectations on the mock objects (How will they be called? What wil they do?).

+ 1. Exercise code that uses the mock objects; if necessary, check the result using [Google Test](http://code.google.com/p/googletest/) assertions.

+ 1. When a mock objects is destructed, Google Mock automatically verifies that all expectations on it have been satisfied.

+

+Here is an example:

+```

+using ::testing::Return; // #1

+

+TEST(BarTest, DoesThis) {

+ MockFoo foo; // #2

+

+ ON_CALL(foo, GetSize()) // #3

+ .WillByDefault(Return(1));

+ // ... other default actions ...

+

+ EXPECT_CALL(foo, Describe(5)) // #4

+ .Times(3)

+ .WillRepeatedly(Return("Category 5"));

+ // ... other expectations ...

+

+ EXPECT_EQ("good", MyProductionFunction(&foo)); // #5

+} // #6

+```

+

+# Setting Default Actions #

+

+Google Mock has a **built-in default action** for any function that

+returns `void`, `bool`, a numeric value, or a pointer.

+

+To customize the default action for functions with return type `T` globally:

+```

+using ::testing::DefaultValue;

+

+DefaultValue<T>::Set(value); // Sets the default value to be returned.

+// ... use the mocks ...

+DefaultValue<T>::Clear(); // Resets the default value.

+```

+

+To customize the default action for a particular method, use `ON_CALL()`:

+```

+ON_CALL(mock_object, method(matchers))

+ .With(multi_argument_matcher) ?

+ .WillByDefault(action);

+```

+

+# Setting Expectations #

+

+`EXPECT_CALL()` sets **expectations** on a mock method (How will it be

+called? What will it do?):

+```

+EXPECT_CALL(mock_object, method(matchers))

+ .With(multi_argument_matcher) ?

+ .Times(cardinality) ?

+ .InSequence(sequences) *

+ .After(expectations) *

+ .WillOnce(action) *

+ .WillRepeatedly(action) ?

+ .RetiresOnSaturation(); ?

+```

+

+If `Times()` is omitted, the cardinality is assumed to be:

+

+ * `Times(1)` when there is neither `WillOnce()` nor `WillRepeatedly()`;

+ * `Times(n)` when there are `n WillOnce()`s but no `WillRepeatedly()`, where `n` >= 1; or

+ * `Times(AtLeast(n))` when there are `n WillOnce()`s and a `WillRepeatedly()`, where `n` >= 0.

+

+A method with no `EXPECT_CALL()` is free to be invoked _any number of times_, and the default action will be taken each time.

+

+# Matchers #

+

+A **matcher** matches a _single_ argument. You can use it inside

+`ON_CALL()` or `EXPECT_CALL()`, or use it to validate a value

+directly:

+

+| `EXPECT_THAT(value, matcher)` | Asserts that `value` matches `matcher`. |

+|:------------------------------|:----------------------------------------|

+| `ASSERT_THAT(value, matcher)` | The same as `EXPECT_THAT(value, matcher)`, except that it generates a **fatal** failure. |

+

+Built-in matchers (where `argument` is the function argument) are

+divided into several categories:

+

+## Wildcard ##

+|`_`|`argument` can be any value of the correct type.|

+|:--|:-----------------------------------------------|

+|`A<type>()` or `An<type>()`|`argument` can be any value of type `type`. |

+

+## Generic Comparison ##

+

+|`Eq(value)` or `value`|`argument == value`|

+|:---------------------|:------------------|

+|`Ge(value)` |`argument >= value`|

+|`Gt(value)` |`argument > value` |

+|`Le(value)` |`argument <= value`|

+|`Lt(value)` |`argument < value` |

+|`Ne(value)` |`argument != value`|

+|`IsNull()` |`argument` is a `NULL` pointer (raw or smart).|

+|`NotNull()` |`argument` is a non-null pointer (raw or smart).|

+|`Ref(variable)` |`argument` is a reference to `variable`.|

+|`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.|

+

+Except `Ref()`, these matchers make a _copy_ of `value` in case it's

+modified or destructed later. If the compiler complains that `value`

+doesn't have a public copy constructor, try wrap it in `ByRef()`,

+e.g. `Eq(ByRef(non_copyable_value))`. If you do that, make sure

+`non_copyable_value` is not changed afterwards, or the meaning of your

+matcher will be changed.

+

+## Floating-Point Matchers ##

+

+|`DoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal.|

+|:-------------------|:----------------------------------------------------------------------------------------------|

+|`FloatEq(a_float)` |`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. |

+|`NanSensitiveDoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. |

+|`NanSensitiveFloatEq(a_float)`|`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. |

+

+The above matchers use ULP-based comparison (the same as used in

+[Google Test](http://code.google.com/p/googletest/)). They

+automatically pick a reasonable error bound based on the absolute

+value of the expected value. `DoubleEq()` and `FloatEq()` conform to

+the IEEE standard, which requires comparing two NaNs for equality to

+return false. The `NanSensitive*` version instead treats two NaNs as

+equal, which is often what a user wants.

+

+## String Matchers ##

+

+The `argument` can be either a C string or a C++ string object:

+

+|`ContainsRegex(string)`|`argument` matches the given regular expression.|

+|:----------------------|:-----------------------------------------------|

+|`EndsWith(suffix)` |`argument` ends with string `suffix`. |

+|`HasSubstr(string)` |`argument` contains `string` as a sub-string. |

+|`MatchesRegex(string)` |`argument` matches the given regular expression with the match starting at the first character and ending at the last character.|

+|`StartsWith(prefix)` |`argument` starts with string `prefix`. |

+|`StrCaseEq(string)` |`argument` is equal to `string`, ignoring case. |

+|`StrCaseNe(string)` |`argument` is not equal to `string`, ignoring case.|

+|`StrEq(string)` |`argument` is equal to `string`. |

+|`StrNe(string)` |`argument` is not equal to `string`. |

+

+`StrCaseEq()`, `StrCaseNe()`, `StrEq()`, and `StrNe()` work for wide

+strings as well.

+

+## Container Matchers ##

+

+Most STL-style containers support `==`, so you can use

+`Eq(expected_container)` or simply `expected_container` to match a

+container exactly. If you want to write the elements in-line,

+match them more flexibly, or get more informative messages, you can use:

+

+| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. |

+|:--------------|:-------------------------------------------------------------------------------------------|

+|`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.|

+|`ElementsAreArray(array)` or `ElementsAreArray(array, count)`|The same as `ElementsAre()` except that the expected element values/matchers come from a C-style array.|

+| `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. |

+

+These matchers can also match:

+

+ 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`), and

+ 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)).

+

+where the array may be multi-dimensional (i.e. its elements can be arrays).

+

+## Member Matchers ##

+

+|`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_.|

+|:------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------|

+|`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`.|

+|`Pair(m1, m2)` |`argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. |

+|`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_.|

+

+## Matching the Result of a Function or Functor ##

+

+|`ResultOf(f, m)`|`f(argument)` matches matcher `m`, where `f` is a function or functor.|

+|:---------------|:---------------------------------------------------------------------|

+

+## Pointer Matchers ##

+

+|`Pointee(m)`|`argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`.|

+|:-----------|:-----------------------------------------------------------------------------------------------|

+

+## Multiargument Matchers ##

+

+These are matchers on tuple types. They can be used in

+`.With()`. The following can be used on functions with <i>two<br>

+arguments</i> `x` and `y`:

+

+|`Eq()`|`x == y`|

+|:-----|:-------|

+|`Ge()`|`x >= y`|

+|`Gt()`|`x > y` |

+|`Le()`|`x <= y`|

+|`Lt()`|`x < y` |

+|`Ne()`|`x != y`|

+

+You can use the following selectors to pick a subset of the arguments

+(or reorder them) to participate in the matching:

+

+|`AllArgs(m)`|Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`.|

+|:-----------|:-------------------------------------------------------------------|

+|`Args<N1, N2, ..., Nk>(m)`|The `k` selected (using 0-based indices) arguments match `m`, e.g. `Args<1, 2>(Contains(5))`.|

+

+## Composite Matchers ##

+

+You can make a matcher from one or more other matchers:

+

+|`AllOf(m1, m2, ..., mn)`|`argument` matches all of the matchers `m1` to `mn`.|

+|:-----------------------|:---------------------------------------------------|

+|`AnyOf(m1, m2, ..., mn)`|`argument` matches at least one of the matchers `m1` to `mn`.|

+|`Not(m)` |`argument` doesn't match matcher `m`. |

+

+## Adapters for Matchers ##

+

+|`MatcherCast<T>(m)`|casts matcher `m` to type `Matcher<T>`.|

+|:------------------|:--------------------------------------|

+|`SafeMatcherCast<T>(m)`| [safely casts](V1_5_CookBook#Casting_Matchers.md) matcher `m` to type `Matcher<T>`. |

+|`Truly(predicate)` |`predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor.|

+

+## Matchers as Predicates ##

+

+|`Matches(m)`|a unary functor that returns `true` if the argument matches `m`.|

+|:-----------|:---------------------------------------------------------------|

+|`ExplainMatchResult(m, value, result_listener)`|returns `true` if `value` matches `m`, explaining the result to `result_listener`.|

+|`Value(x, m)`|returns `true` if the value of `x` matches `m`. |

+

+## Defining Matchers ##

+

+| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. |

+|:-------------------------------------------------|:------------------------------------------------------|

+| `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`. |

+| `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`]. |

+

+**Notes:**

+

+ 1. The `MATCHER*` macros cannot be used inside a function or class.

+ 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).

+ 1. You can use `PrintToString(x)` to convert a value `x` of any type to a string.

+

+## Matchers as Test Assertions ##

+

+|`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`.|

+|:---------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------|

+|`EXPECT_THAT(expression, m)`|Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`. |

+

+# Actions #

+

+**Actions** specify what a mock function should do when invoked.

+

+## Returning a Value ##

+

+|`Return()`|Return from a `void` mock function.|

+|:---------|:----------------------------------|

+|`Return(value)`|Return `value`. |

+|`ReturnArg<N>()`|Return the `N`-th (0-based) argument.|

+|`ReturnNew<T>(a1, ..., ak)`|Return `new T(a1, ..., ak)`; a different object is created each time.|

+|`ReturnNull()`|Return a null pointer. |

+|`ReturnRef(variable)`|Return a reference to `variable`. |

+

+## Side Effects ##

+

+|`Assign(&variable, value)`|Assign `value` to variable.|

+|:-------------------------|:--------------------------|

+| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. |

+| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. |

+| `SetArgReferee<N>(value)` | Assign value to the variable referenced by the `N`-th (0-based) argument. |

+|`SetArgumentPointee<N>(value)`|Assign `value` to the variable pointed by the `N`-th (0-based) argument.|

+|`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.|

+|`SetErrnoAndReturn(error, value)`|Set `errno` to `error` and return `value`.|

+|`Throw(exception)` |Throws the given exception, which can be any copyable value. Available since v1.1.0.|

+

+## Using a Function or a Functor as an Action ##

+

+|`Invoke(f)`|Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor.|

+|:----------|:-----------------------------------------------------------------------------------------------------------------|

+|`Invoke(object_pointer, &class::method)`|Invoke the {method on the object with the arguments passed to the mock function. |

+|`InvokeWithoutArgs(f)`|Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. |

+|`InvokeWithoutArgs(object_pointer, &class::method)`|Invoke the method on the object, which takes no arguments. |

+|`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.|

+

+The return value of the invoked function is used as the return value

+of the action.

+

+When defining a function or functor to be used with `Invoke*()`, you can declare any unused parameters as `Unused`:

+```

+ double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); }

+ ...

+ EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance));

+```

+

+In `InvokeArgument<N>(...)`, if an argument needs to be passed by reference, wrap it inside `ByRef()`. For example,

+```

+ InvokeArgument<2>(5, string("Hi"), ByRef(foo))

+```

+calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by value, and `foo` by reference.

+

+## Default Action ##

+

+|`DoDefault()`|Do the default action (specified by `ON_CALL()` or the built-in one).|

+|:------------|:--------------------------------------------------------------------|

+

+**Note:** due to technical reasons, `DoDefault()` cannot be used inside a composite action - trying to do so will result in a run-time error.

+

+## Composite Actions ##

+

+|`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. |

+|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------|

+|`IgnoreResult(a)` |Perform action `a` and ignore its result. `a` must not return void. |

+|`WithArg<N>(a)` |Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. |

+|`WithArgs<N1, N2, ..., Nk>(a)`|Pass the selected (0-based) arguments of the mock function to action `a` and perform it. |

+|`WithoutArgs(a)` |Perform action `a` without any arguments. |

+

+## Defining Actions ##

+

+| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. |

+|:--------------------------------------|:---------------------------------------------------------------------------------------|

+| `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`. |

+| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. |

+

+The `ACTION*` macros cannot be used inside a function or class.

+

+# Cardinalities #

+

+These are used in `Times()` to specify how many times a mock function will be called:

+

+|`AnyNumber()`|The function can be called any number of times.|

+|:------------|:----------------------------------------------|

+|`AtLeast(n)` |The call is expected at least `n` times. |

+|`AtMost(n)` |The call is expected at most `n` times. |

+|`Between(m, n)`|The call is expected between `m` and `n` (inclusive) times.|

+|`Exactly(n) or n`|The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0.|

+

+# Expectation Order #

+

+By default, the expectations can be matched in _any_ order. If some

+or all expectations must be matched in a given order, there are two

+ways to specify it. They can be used either independently or

+together.

+

+## The After Clause ##

+

+```

+using ::testing::Expectation;

+...

+Expectation init_x = EXPECT_CALL(foo, InitX());

+Expectation init_y = EXPECT_CALL(foo, InitY());

+EXPECT_CALL(foo, Bar())

+ .After(init_x, init_y);

+```

+says that `Bar()` can be called only after both `InitX()` and

+`InitY()` have been called.

+

+If you don't know how many pre-requisites an expectation has when you

+write it, you can use an `ExpectationSet` to collect them:

+

+```

+using ::testing::ExpectationSet;

+...

+ExpectationSet all_inits;

+for (int i = 0; i < element_count; i++) {

+ all_inits += EXPECT_CALL(foo, InitElement(i));

+}

+EXPECT_CALL(foo, Bar())

+ .After(all_inits);

+```

+says that `Bar()` can be called only after all elements have been

+initialized (but we don't care about which elements get initialized

+before the others).

+

+Modifying an `ExpectationSet` after using it in an `.After()` doesn't

+affect the meaning of the `.After()`.

+

+## Sequences ##

+

+When you have a long chain of sequential expectations, it's easier to

+specify the order using **sequences**, which don't require you to given

+each expectation in the chain a different name. <i>All expected<br>

+calls</i> in the same sequence must occur in the order they are

+specified.

+

+```

+using ::testing::Sequence;

+Sequence s1, s2;

+...

+EXPECT_CALL(foo, Reset())

+ .InSequence(s1, s2)

+ .WillOnce(Return(true));

+EXPECT_CALL(foo, GetSize())

+ .InSequence(s1)

+ .WillOnce(Return(1));

+EXPECT_CALL(foo, Describe(A<const char*>()))

+ .InSequence(s2)

+ .WillOnce(Return("dummy"));

+```

+says that `Reset()` must be called before _both_ `GetSize()` _and_

+`Describe()`, and the latter two can occur in any order.

+

+To put many expectations in a sequence conveniently:

+```

+using ::testing::InSequence;

+{

+ InSequence dummy;

+

+ EXPECT_CALL(...)...;

+ EXPECT_CALL(...)...;

+ ...

+ EXPECT_CALL(...)...;

+}

+```

+says that all expected calls in the scope of `dummy` must occur in

+strict order. The name `dummy` is irrelevant.)

+

+# Verifying and Resetting a Mock #

+

+Google Mock will verify the expectations on a mock object when it is destructed, or you can do it earlier:

+```

+using ::testing::Mock;

+...

+// Verifies and removes the expectations on mock_obj;

+// returns true iff successful.

+Mock::VerifyAndClearExpectations(&mock_obj);

+...

+// Verifies and removes the expectations on mock_obj;

+// also removes the default actions set by ON_CALL();

+// returns true iff successful.

+Mock::VerifyAndClear(&mock_obj);

+```

+

+You can also tell Google Mock that a mock object can be leaked and doesn't

+need to be verified:

+```

+Mock::AllowLeak(&mock_obj);

+```

+

+# Mock Classes #

+

+Google Mock defines a convenient mock class template

+```

+class MockFunction<R(A1, ..., An)> {

+ public:

+ MOCK_METHODn(Call, R(A1, ..., An));

+};

+```

+See this [recipe](V1_5_CookBook#Using_Check_Points.md) for one application of it.

+

+# Flags #

+

+| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. |

+|:-------------------------------|:----------------------------------------------|

+| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. | \ No newline at end of file