gMock Cheat Sheet
Defining a Mock Class
Mocking a Normal Class {#MockClass}
Given
cpp
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
```cpp
include "gmock/gmock.h"
class MockFoo : public Foo { ... MOCKMETHOD(int, GetSize, (), (const, override)); MOCKMETHOD(string, Describe, (const char* name), (override)); MOCKMETHOD(string, Describe, (int type), (override)); MOCKMETHOD(bool, Process, (Bar elem, int count), (override)); }; ```
To create a "nice" mock, which ignores all uninteresting calls, a "naggy" mock, which warns on all uninteresting calls, or a "strict" mock, which treats them as failures:
```cpp using ::testing::NiceMock; using ::testing::NaggyMock; using ::testing::StrictMock;
NiceMock
Note: A mock object is currently naggy by default. We may make it nice by default in the future.
Mocking a Class Template {#MockTemplate}
Class templates can be mocked just like any class.
To mock
cpp
template <typename Elem>
class StackInterface {
...
virtual ~StackInterface();
virtual int GetSize() const = 0;
virtual void Push(const Elem& x) = 0;
};
(note that all member functions that are mocked, including ~StackInterface()
must be virtual).
cpp
template <typename Elem>
class MockStack : public StackInterface<Elem> {
...
MOCK_METHOD(int, GetSize, (), (const, override));
MOCK_METHOD(void, Push, (const Elem& x), (override));
};
Specifying Calling Conventions for Mock Functions
If your mock function doesn't use the default calling convention, you can
specify it by adding Calltype(convention) to MOCK_METHOD's 4th parameter.
For example,
cpp
MOCK_METHOD(bool, Foo, (int n), (Calltype(STDMETHODCALLTYPE)));
MOCK_METHOD(int, Bar, (double x, double y),
(const, Calltype(STDMETHODCALLTYPE)));
where STDMETHODCALLTYPE is defined by <objbase.h> on Windows.
Using Mocks in Tests {#UsingMocks}
The typical work flow is:
- Import the gMock names you need to use. All gMock symbols are in the
testingnamespace unless they are macros or otherwise noted. - Create the mock objects.
- Optionally, set the default actions of the mock objects.
- Set your expectations on the mock objects (How will they be called? What will they do?).
- Exercise code that uses the mock objects; if necessary, check the result using googletest assertions.
- When a mock object is destructed, gMock automatically verifies that all expectations on it have been satisfied.
Here's an example:
```cpp 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 {#OnCall}
gMock has a built-in default action for any function that returns void,
bool, a numeric value, or a pointer. In C++11, it will additionally returns
the default-constructed value, if one exists for the given type.
To customize the default action for functions with return type T:
```cpp using ::testing::DefaultValue;
// Sets the default value to be returned. T must be CopyConstructible.
DefaultValue
Example usage:
```cpp
// Sets the default action for return type std::unique_ptr
// When this fires, the default action of MakeBuzz() will run, which // will return a new Buzz object. EXPECTCALL(mockbuzzer_, MakeBuzz("hello")).Times(AnyNumber());
auto buzz1 = mockbuzzer.MakeBuzz("hello"); auto buzz2 = mockbuzzer.MakeBuzz("hello"); EXPECTNE(nullptr, buzz1); EXPECTNE(nullptr, buzz2); EXPECT_NE(buzz1, buzz2);
// Resets the default action for return type std::unique_ptr
To customize the default action for a particular method of a specific mock
object, use ON_CALL(). ON_CALL() has a similar syntax to EXPECT_CALL(),
but it is used for setting default behaviors (when you do not require that the
mock method is called). See here for a more detailed
discussion.
cpp
ON_CALL(mock-object, method(matchers))
.With(multi-argument-matcher) ?
.WillByDefault(action);
Setting Expectations {#ExpectCall}
EXPECT_CALL() sets expectations on a mock method (How will it be called?
What will it do?):
cpp
EXPECT_CALL(mock-object, method (matchers)?)
.With(multi-argument-matcher) ?
.Times(cardinality) ?
.InSequence(sequences) *
.After(expectations) *
.WillOnce(action) *
.WillRepeatedly(action) ?
.RetiresOnSaturation(); ?
For each item above, ? means it can be used at most once, while * means it
can be used any number of times.
In order to pass, EXPECT_CALL must be used before the calls are actually made.
The (matchers) is a comma-separated list of matchers that correspond to each
of the arguments of method, and sets the expectation only for calls of
method that matches all of the matchers.
If (matchers) is omitted, the expectation is the same as if the matchers were
set to anything matchers (for example, (_, _, _, _) for a four-arg method).
If Times() is omitted, the cardinality is assumed to be:
Times(1)when there is neitherWillOnce()norWillRepeatedly();Times(n)when there arenWillOnce()s but noWillRepeatedly(), wheren>= 1; orTimes(AtLeast(n))when there arenWillOnce()s and aWillRepeatedly(), wheren>= 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 {#MatcherList}
A matcher matches a single argument. You can use it inside ON_CALL() or
EXPECT_CALL(), or use it to validate a value directly using two macros:
Built-in matchers (where argument is the function argument, e.g.
actual_value in the example above, or when used in the context of
EXPECT_CALL(mock_object, method(matchers)), the arguments of method) are
divided into several categories:
Wildcard
Matcher | Description
:-------------------------- | :-----------------------------------------------
_ | argument can be any value of the correct type.
A<type>() or An<type>() | argument can be any value of type type.
Generic Comparison
| Matcher | Description | | :--------------------- | :-------------------------------------------------- | | `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` | | `IsFalse()` | `argument` evaluates to `false` in a Boolean context. | | `IsTrue()` | `argument` evaluates to `true` in a Boolean context. | | `IsNull()` | `argument` is a `NULL` pointer (raw or smart). | | `NotNull()` | `argument` is a non-null pointer (raw or smart). | | `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. (For testing whether an `optional<>` is set, check for equality with `nullopt`. You may need to use `Eq(nullopt)` if the inner type doesn't have `==`.)| | `VariantWithExcept 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.
IsTrue and IsFalse are useful when you need to use a matcher, or for types
that can be explicitly converted to Boolean, but are not implicitly converted to
Boolean. In other cases, you can use the basic
EXPECT_TRUE and EXPECT_FALSE
assertions.
Floating-Point Matchers {#FpMatchers}
| Matcher | Description | | :------------------------------- | :--------------------------------- | | `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. | | `IsNan()` | `argument` is any floating-point type with a NaN value. |The above matchers use ULP-based comparison (the same as used in 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() and MatchesRegex() take ownership of the RE object. They
use the regular expression syntax defined
here. All of
these matchers, except ContainsRegex() and MatchesRegex() 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:
Notes:
- These matchers can also match:
- a native array passed by reference (e.g. in
Foo(const int (&a)[5])), and - an array passed as a pointer and a count (e.g. in
Bar(const T* buffer, int len)-- see Multi-argument Matchers).
- a native array passed by reference (e.g. in
- The array being matched may be multi-dimensional (i.e. its elements can be arrays).
minPointwise(m, ...)should be a matcher for::std::tuple<T, U>whereTandUare the element type of the actual container and the expected container, respectively. For example, to compare twoFoocontainers whereFoodoesn't supportoperator==, one might write:cpp using ::std::get; MATCHER(FooEq, "") { return std::get<0>(arg).Equals(std::get<1>(arg)); } ... EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos));
Member Matchers
| Matcher | Description | | :------------------------------ | :----------------------------------------- | | `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, Functor, or Callback
| Matcher | Description | | :--------------- | :------------------------------------------------ | | `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. |Pointer Matchers
| Matcher | Description | | :------------------------ | :---------------------------------------------- | | `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. | | `WhenDynamicCastToMulti-argument Matchers {#MultiArgMatchers}
Technically, all matchers match a single value. A "multi-argument" matcher is
just one that matches a tuple. The following matchers can be used to match a
tuple (x, y):
Matcher | Description
:------ | :----------
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:
| Matcher | Description | | :------------------------- | :---------------------------------------------- | | `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. | | `ArgsComposite Matchers
You can make a matcher from one or more other matchers:
| Matcher | Description | | :------------------------------- | :-------------------------------------- | | `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. | | `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | | `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. | | `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. | | `Not(m)` | `argument` doesn't match matcher `m`. |Adapters for Matchers
| Matcher | Description | | :---------------------- | :------------------------------------ | | `MatcherCastAddressSatisfies(callback) and Truly(callback) take ownership of callback,
which must be a permanent callback.
Using Matchers as Predicates {#MatchersAsPredicatesCheat}
| Matcher | Description | | :---------------------------- | :------------------------------------------ | | `Matches(m)(value)` | evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor. | | `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. | | `Value(value, m)` | evaluates to `true` if `value` matches `m`. |Defining Matchers
| Matcher | Description | | :----------------------------------- | :------------------------------------ | | `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 matcher `IsDivisibleBy(n)` to match a number divisible by `n`. | | `MATCHER_P2(IsBetween, a, b, std::string(negation ? "isn't" : "is") + " between " + PrintToString(a) + " and " + PrintToString(b)) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. |Notes:
- The
MATCHER*macros cannot be used inside a function or class. - 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).
- You can use
PrintToString(x)to convert a valuexof any type to a string.
Actions {#ActionList}
Actions specify what a mock function should do when invoked.
Returning a Value
| | | | :-------------------------------- | :-------------------------------------------- | | `Return()` | Return from a `void` mock function. | | `Return(value)` | Return `value`. If the type of `value` is different to the mock function's return type, `value` is converted to the latter type at the time the expectation is set, not when the action is executed. | | `ReturnArgSide Effects
| | | | :--------------------------------- | :-------------------------------------- | | `Assign(&variable, value)` | Assign `value` to variable. | | `DeleteArgUsing a Function, Functor, or Lambda as an Action
In the following, by "callable" we mean a free function, std::function,
functor, or lambda.
The return value of the invoked function is used as the return value of the action.
When defining a callable to be used with Invoke*(), you can declare any unused
parameters as Unused:
cpp
using ::testing::Invoke;
double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); }
...
EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance));
Invoke(callback) and InvokeWithoutArgs(callback) take ownership of
callback, which must be permanent. The type of callback must be a base
callback type instead of a derived one, e.g.
```cpp BlockingClosure* done = new BlockingClosure; ... Invoke(done) ...; // This won't compile!
Closure* done2 = new BlockingClosure; ... Invoke(done2) ...; // This works. ```
In InvokeArgument<N>(...), if an argument needs to be passed by reference,
wrap it inside ByRef(). For example,
cpp
using ::testing::ByRef;
using ::testing::InvokeArgument;
...
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
| Matcher | Description | | :------------ | :----------------------------------------------------- | | `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. | | `WithArgDefining 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 {#CardinalityList}
These are used in Times() to specify how many times a mock function will be
called:
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 {#AfterClause}
cpp
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:
cpp
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 {#UsingSequences}
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. All expected calls in the same sequence must occur in the order they are specified.
cpp
using ::testing::Return;
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:
```cpp using ::testing::InSequence; { InSequence seq;
EXPECTCALL(...)...; EXPECTCALL(...)...; ... EXPECT_CALL(...)...; } ```
says that all expected calls in the scope of seq must occur in strict order.
The name seq is irrelevant.
Verifying and Resetting a Mock
gMock will verify the expectations on a mock object when it is destructed, or you can do it earlier:
cpp
using ::testing::Mock;
...
// Verifies and removes the expectations on mock_obj;
// returns true if and only if successful.
Mock::VerifyAndClearExpectations(&mock_obj);
...
// Verifies and removes the expectations on mock_obj;
// also removes the default actions set by ON_CALL();
// returns true if and only if successful.
Mock::VerifyAndClear(&mock_obj);
You can also tell gMock that a mock object can be leaked and doesn't need to be verified:
cpp
Mock::AllowLeak(&mock_obj);
Mock Classes
gMock defines a convenient mock class template
cpp
class MockFunction<R(A1, ..., An)> {
public:
MOCK_METHOD(R, Call, (A1, ..., An));
};
See this recipe for one application of it.