| 1 |
# gMock Cheat Sheet |
| 2 |
|
| 3 |
## Defining a Mock Class |
| 4 |
|
| 5 |
### Mocking a Normal Class {#MockClass} |
| 6 |
|
| 7 |
Given |
| 8 |
|
| 9 |
```cpp |
| 10 |
class Foo { |
| 11 |
... |
| 12 |
virtual ~Foo(); |
| 13 |
virtual int GetSize() const = 0; |
| 14 |
virtual string Describe(const char* name) = 0; |
| 15 |
virtual string Describe(int type) = 0; |
| 16 |
virtual bool Process(Bar elem, int count) = 0; |
| 17 |
}; |
| 18 |
``` |
| 19 |
|
| 20 |
(note that `~Foo()` **must** be virtual) we can define its mock as |
| 21 |
|
| 22 |
```cpp |
| 23 |
#include "gmock/gmock.h" |
| 24 |
|
| 25 |
class MockFoo : public Foo { |
| 26 |
... |
| 27 |
MOCK_METHOD(int, GetSize, (), (const, override)); |
| 28 |
MOCK_METHOD(string, Describe, (const char* name), (override)); |
| 29 |
MOCK_METHOD(string, Describe, (int type), (override)); |
| 30 |
MOCK_METHOD(bool, Process, (Bar elem, int count), (override)); |
| 31 |
}; |
| 32 |
``` |
| 33 |
|
| 34 |
To create a "nice" mock, which ignores all uninteresting calls, a "naggy" mock, |
| 35 |
which warns on all uninteresting calls, or a "strict" mock, which treats them as |
| 36 |
failures: |
| 37 |
|
| 38 |
```cpp |
| 39 |
using ::testing::NiceMock; |
| 40 |
using ::testing::NaggyMock; |
| 41 |
using ::testing::StrictMock; |
| 42 |
|
| 43 |
NiceMock<MockFoo> nice_foo; // The type is a subclass of MockFoo. |
| 44 |
NaggyMock<MockFoo> naggy_foo; // The type is a subclass of MockFoo. |
| 45 |
StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo. |
| 46 |
``` |
| 47 |
|
| 48 |
{: .callout .note} |
| 49 |
**Note:** A mock object is currently naggy by default. We may make it nice by |
| 50 |
default in the future. |
| 51 |
|
| 52 |
### Mocking a Class Template {#MockTemplate} |
| 53 |
|
| 54 |
Class templates can be mocked just like any class. |
| 55 |
|
| 56 |
To mock |
| 57 |
|
| 58 |
```cpp |
| 59 |
template <typename Elem> |
| 60 |
class StackInterface { |
| 61 |
... |
| 62 |
virtual ~StackInterface(); |
| 63 |
virtual int GetSize() const = 0; |
| 64 |
virtual void Push(const Elem& x) = 0; |
| 65 |
}; |
| 66 |
``` |
| 67 |
|
| 68 |
(note that all member functions that are mocked, including `~StackInterface()` |
| 69 |
**must** be virtual). |
| 70 |
|
| 71 |
```cpp |
| 72 |
template <typename Elem> |
| 73 |
class MockStack : public StackInterface<Elem> { |
| 74 |
... |
| 75 |
MOCK_METHOD(int, GetSize, (), (const, override)); |
| 76 |
MOCK_METHOD(void, Push, (const Elem& x), (override)); |
| 77 |
}; |
| 78 |
``` |
| 79 |
|
| 80 |
### Specifying Calling Conventions for Mock Functions |
| 81 |
|
| 82 |
If your mock function doesn't use the default calling convention, you can |
| 83 |
specify it by adding `Calltype(convention)` to `MOCK_METHOD`'s 4th parameter. |
| 84 |
For example, |
| 85 |
|
| 86 |
```cpp |
| 87 |
MOCK_METHOD(bool, Foo, (int n), (Calltype(STDMETHODCALLTYPE))); |
| 88 |
MOCK_METHOD(int, Bar, (double x, double y), |
| 89 |
(const, Calltype(STDMETHODCALLTYPE))); |
| 90 |
``` |
| 91 |
|
| 92 |
where `STDMETHODCALLTYPE` is defined by `<objbase.h>` on Windows. |
| 93 |
|
| 94 |
## Using Mocks in Tests {#UsingMocks} |
| 95 |
|
| 96 |
The typical work flow is: |
| 97 |
|
| 98 |
1. Import the gMock names you need to use. All gMock symbols are in the |
| 99 |
`testing` namespace unless they are macros or otherwise noted. |
| 100 |
2. Create the mock objects. |
| 101 |
3. Optionally, set the default actions of the mock objects. |
| 102 |
4. Set your expectations on the mock objects (How will they be called? What |
| 103 |
will they do?). |
| 104 |
5. Exercise code that uses the mock objects; if necessary, check the result |
| 105 |
using googletest assertions. |
| 106 |
6. When a mock object is destructed, gMock automatically verifies that all |
| 107 |
expectations on it have been satisfied. |
| 108 |
|
| 109 |
Here's an example: |
| 110 |
|
| 111 |
```cpp |
| 112 |
using ::testing::Return; // #1 |
| 113 |
|
| 114 |
TEST(BarTest, DoesThis) { |
| 115 |
MockFoo foo; // #2 |
| 116 |
|
| 117 |
ON_CALL(foo, GetSize()) // #3 |
| 118 |
.WillByDefault(Return(1)); |
| 119 |
// ... other default actions ... |
| 120 |
|
| 121 |
EXPECT_CALL(foo, Describe(5)) // #4 |
| 122 |
.Times(3) |
| 123 |
.WillRepeatedly(Return("Category 5")); |
| 124 |
// ... other expectations ... |
| 125 |
|
| 126 |
EXPECT_EQ(MyProductionFunction(&foo), "good"); // #5 |
| 127 |
} // #6 |
| 128 |
``` |
| 129 |
|
| 130 |
## Setting Default Actions {#OnCall} |
| 131 |
|
| 132 |
gMock has a **built-in default action** for any function that returns `void`, |
| 133 |
`bool`, a numeric value, or a pointer. In C++11, it will additionally returns |
| 134 |
the default-constructed value, if one exists for the given type. |
| 135 |
|
| 136 |
To customize the default action for functions with return type `T`, use |
| 137 |
[`DefaultValue<T>`](reference/mocking.md#DefaultValue). For example: |
| 138 |
|
| 139 |
```cpp |
| 140 |
// Sets the default action for return type std::unique_ptr<Buzz> to |
| 141 |
// creating a new Buzz every time. |
| 142 |
DefaultValue<std::unique_ptr<Buzz>>::SetFactory( |
| 143 |
[] { return MakeUnique<Buzz>(AccessLevel::kInternal); }); |
| 144 |
|
| 145 |
// When this fires, the default action of MakeBuzz() will run, which |
| 146 |
// will return a new Buzz object. |
| 147 |
EXPECT_CALL(mock_buzzer_, MakeBuzz("hello")).Times(AnyNumber()); |
| 148 |
|
| 149 |
auto buzz1 = mock_buzzer_.MakeBuzz("hello"); |
| 150 |
auto buzz2 = mock_buzzer_.MakeBuzz("hello"); |
| 151 |
EXPECT_NE(buzz1, nullptr); |
| 152 |
EXPECT_NE(buzz2, nullptr); |
| 153 |
EXPECT_NE(buzz1, buzz2); |
| 154 |
|
| 155 |
// Resets the default action for return type std::unique_ptr<Buzz>, |
| 156 |
// to avoid interfere with other tests. |
| 157 |
DefaultValue<std::unique_ptr<Buzz>>::Clear(); |
| 158 |
``` |
| 159 |
|
| 160 |
To customize the default action for a particular method of a specific mock |
| 161 |
object, use [`ON_CALL`](reference/mocking.md#ON_CALL). `ON_CALL` has a similar |
| 162 |
syntax to `EXPECT_CALL`, but it is used for setting default behaviors when you |
| 163 |
do not require that the mock method is called. See |
| 164 |
[Knowing When to Expect](gmock_cook_book.md#UseOnCall) for a more detailed |
| 165 |
discussion. |
| 166 |
|
| 167 |
## Setting Expectations {#ExpectCall} |
| 168 |
|
| 169 |
See [`EXPECT_CALL`](reference/mocking.md#EXPECT_CALL) in the Mocking Reference. |
| 170 |
|
| 171 |
## Matchers {#MatcherList} |
| 172 |
|
| 173 |
See the [Matchers Reference](reference/matchers.md). |
| 174 |
|
| 175 |
## Actions {#ActionList} |
| 176 |
|
| 177 |
See the [Actions Reference](reference/actions.md). |
| 178 |
|
| 179 |
## Cardinalities {#CardinalityList} |
| 180 |
|
| 181 |
See the [`Times` clause](reference/mocking.md#EXPECT_CALL.Times) of |
| 182 |
`EXPECT_CALL` in the Mocking Reference. |
| 183 |
|
| 184 |
## Expectation Order |
| 185 |
|
| 186 |
By default, expectations can be matched in *any* order. If some or all |
| 187 |
expectations must be matched in a given order, you can use the |
| 188 |
[`After` clause](reference/mocking.md#EXPECT_CALL.After) or |
| 189 |
[`InSequence` clause](reference/mocking.md#EXPECT_CALL.InSequence) of |
| 190 |
`EXPECT_CALL`, or use an [`InSequence` object](reference/mocking.md#InSequence). |
| 191 |
|
| 192 |
## Verifying and Resetting a Mock |
| 193 |
|
| 194 |
gMock will verify the expectations on a mock object when it is destructed, or |
| 195 |
you can do it earlier: |
| 196 |
|
| 197 |
```cpp |
| 198 |
using ::testing::Mock; |
| 199 |
... |
| 200 |
// Verifies and removes the expectations on mock_obj; |
| 201 |
// returns true if and only if successful. |
| 202 |
Mock::VerifyAndClearExpectations(&mock_obj); |
| 203 |
... |
| 204 |
// Verifies and removes the expectations on mock_obj; |
| 205 |
// also removes the default actions set by ON_CALL(); |
| 206 |
// returns true if and only if successful. |
| 207 |
Mock::VerifyAndClear(&mock_obj); |
| 208 |
``` |
| 209 |
|
| 210 |
Do not set new expectations after verifying and clearing a mock after its use. |
| 211 |
Setting expectations after code that exercises the mock has undefined behavior. |
| 212 |
See [Using Mocks in Tests](gmock_for_dummies.md#using-mocks-in-tests) for more |
| 213 |
information. |
| 214 |
|
| 215 |
You can also tell gMock that a mock object can be leaked and doesn't need to be |
| 216 |
verified: |
| 217 |
|
| 218 |
```cpp |
| 219 |
Mock::AllowLeak(&mock_obj); |
| 220 |
``` |
| 221 |
|
| 222 |
## Mock Classes |
| 223 |
|
| 224 |
gMock defines a convenient mock class template |
| 225 |
|
| 226 |
```cpp |
| 227 |
class MockFunction<R(A1, ..., An)> { |
| 228 |
public: |
| 229 |
MOCK_METHOD(R, Call, (A1, ..., An)); |
| 230 |
}; |
| 231 |
``` |
| 232 |
|
| 233 |
See this [recipe](gmock_cook_book.md#UsingCheckPoints) for one application of |
| 234 |
it. |
| 235 |
|
| 236 |
## Flags |
| 237 |
|
| 238 |
| Flag | Description | |
| 239 |
| :----------------------------- | :---------------------------------------- | |
| 240 |
| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. | |
| 241 |
| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. | |