| 1 |
# gMock Cookbook |
| 2 |
|
| 3 |
You can find recipes for using gMock here. If you haven't yet, please read |
| 4 |
[the dummy guide](gmock_for_dummies.md) first to make sure you understand the |
| 5 |
basics. |
| 6 |
|
| 7 |
{: .callout .note} |
| 8 |
**Note:** gMock lives in the `testing` name space. For readability, it is |
| 9 |
recommended to write `using ::testing::Foo;` once in your file before using the |
| 10 |
name `Foo` defined by gMock. We omit such `using` statements in this section for |
| 11 |
brevity, but you should do it in your own code. |
| 12 |
|
| 13 |
## Creating Mock Classes |
| 14 |
|
| 15 |
Mock classes are defined as normal classes, using the `MOCK_METHOD` macro to |
| 16 |
generate mocked methods. The macro gets 3 or 4 parameters: |
| 17 |
|
| 18 |
```cpp |
| 19 |
class MyMock { |
| 20 |
public: |
| 21 |
MOCK_METHOD(ReturnType, MethodName, (Args...)); |
| 22 |
MOCK_METHOD(ReturnType, MethodName, (Args...), (Specs...)); |
| 23 |
}; |
| 24 |
``` |
| 25 |
|
| 26 |
The first 3 parameters are simply the method declaration, split into 3 parts. |
| 27 |
The 4th parameter accepts a closed list of qualifiers, which affect the |
| 28 |
generated method: |
| 29 |
|
| 30 |
* **`const`** - Makes the mocked method a `const` method. Required if |
| 31 |
overriding a `const` method. |
| 32 |
* **`override`** - Marks the method with `override`. Recommended if overriding |
| 33 |
a `virtual` method. |
| 34 |
* **`noexcept`** - Marks the method with `noexcept`. Required if overriding a |
| 35 |
`noexcept` method. |
| 36 |
* **`Calltype(...)`** - Sets the call type for the method (e.g. to |
| 37 |
`STDMETHODCALLTYPE`), useful in Windows. |
| 38 |
* **`ref(...)`** - Marks the method with the reference qualification |
| 39 |
specified. Required if overriding a method that has reference |
| 40 |
qualifications. Eg `ref(&)` or `ref(&&)`. |
| 41 |
|
| 42 |
### Dealing with unprotected commas |
| 43 |
|
| 44 |
Unprotected commas, i.e. commas which are not surrounded by parentheses, prevent |
| 45 |
`MOCK_METHOD` from parsing its arguments correctly: |
| 46 |
|
| 47 |
{: .bad} |
| 48 |
```cpp |
| 49 |
class MockFoo { |
| 50 |
public: |
| 51 |
MOCK_METHOD(std::pair<bool, int>, GetPair, ()); // Won't compile! |
| 52 |
MOCK_METHOD(bool, CheckMap, (std::map<int, double>, bool)); // Won't compile! |
| 53 |
}; |
| 54 |
``` |
| 55 |
|
| 56 |
Solution 1 - wrap with parentheses: |
| 57 |
|
| 58 |
{: .good} |
| 59 |
```cpp |
| 60 |
class MockFoo { |
| 61 |
public: |
| 62 |
MOCK_METHOD((std::pair<bool, int>), GetPair, ()); |
| 63 |
MOCK_METHOD(bool, CheckMap, ((std::map<int, double>), bool)); |
| 64 |
}; |
| 65 |
``` |
| 66 |
|
| 67 |
Note that wrapping a return or argument type with parentheses is, in general, |
| 68 |
invalid C++. `MOCK_METHOD` removes the parentheses. |
| 69 |
|
| 70 |
Solution 2 - define an alias: |
| 71 |
|
| 72 |
{: .good} |
| 73 |
```cpp |
| 74 |
class MockFoo { |
| 75 |
public: |
| 76 |
using BoolAndInt = std::pair<bool, int>; |
| 77 |
MOCK_METHOD(BoolAndInt, GetPair, ()); |
| 78 |
using MapIntDouble = std::map<int, double>; |
| 79 |
MOCK_METHOD(bool, CheckMap, (MapIntDouble, bool)); |
| 80 |
}; |
| 81 |
``` |
| 82 |
|
| 83 |
### Mocking Private or Protected Methods |
| 84 |
|
| 85 |
You must always put a mock method definition (`MOCK_METHOD`) in a `public:` |
| 86 |
section of the mock class, regardless of the method being mocked being `public`, |
| 87 |
`protected`, or `private` in the base class. This allows `ON_CALL` and |
| 88 |
`EXPECT_CALL` to reference the mock function from outside of the mock class. |
| 89 |
(Yes, C++ allows a subclass to change the access level of a virtual function in |
| 90 |
the base class.) Example: |
| 91 |
|
| 92 |
```cpp |
| 93 |
class Foo { |
| 94 |
public: |
| 95 |
... |
| 96 |
virtual bool Transform(Gadget* g) = 0; |
| 97 |
|
| 98 |
protected: |
| 99 |
virtual void Resume(); |
| 100 |
|
| 101 |
private: |
| 102 |
virtual int GetTimeOut(); |
| 103 |
}; |
| 104 |
|
| 105 |
class MockFoo : public Foo { |
| 106 |
public: |
| 107 |
... |
| 108 |
MOCK_METHOD(bool, Transform, (Gadget* g), (override)); |
| 109 |
|
| 110 |
// The following must be in the public section, even though the |
| 111 |
// methods are protected or private in the base class. |
| 112 |
MOCK_METHOD(void, Resume, (), (override)); |
| 113 |
MOCK_METHOD(int, GetTimeOut, (), (override)); |
| 114 |
}; |
| 115 |
``` |
| 116 |
|
| 117 |
### Mocking Overloaded Methods |
| 118 |
|
| 119 |
You can mock overloaded functions as usual. No special attention is required: |
| 120 |
|
| 121 |
```cpp |
| 122 |
class Foo { |
| 123 |
... |
| 124 |
|
| 125 |
// Must be virtual as we'll inherit from Foo. |
| 126 |
virtual ~Foo(); |
| 127 |
|
| 128 |
// Overloaded on the types and/or numbers of arguments. |
| 129 |
virtual int Add(Element x); |
| 130 |
virtual int Add(int times, Element x); |
| 131 |
|
| 132 |
// Overloaded on the const-ness of this object. |
| 133 |
virtual Bar& GetBar(); |
| 134 |
virtual const Bar& GetBar() const; |
| 135 |
}; |
| 136 |
|
| 137 |
class MockFoo : public Foo { |
| 138 |
... |
| 139 |
MOCK_METHOD(int, Add, (Element x), (override)); |
| 140 |
MOCK_METHOD(int, Add, (int times, Element x), (override)); |
| 141 |
|
| 142 |
MOCK_METHOD(Bar&, GetBar, (), (override)); |
| 143 |
MOCK_METHOD(const Bar&, GetBar, (), (const, override)); |
| 144 |
}; |
| 145 |
``` |
| 146 |
|
| 147 |
{: .callout .note} |
| 148 |
**Note:** if you don't mock all versions of the overloaded method, the compiler |
| 149 |
will give you a warning about some methods in the base class being hidden. To |
| 150 |
fix that, use `using` to bring them in scope: |
| 151 |
|
| 152 |
```cpp |
| 153 |
class MockFoo : public Foo { |
| 154 |
... |
| 155 |
using Foo::Add; |
| 156 |
MOCK_METHOD(int, Add, (Element x), (override)); |
| 157 |
// We don't want to mock int Add(int times, Element x); |
| 158 |
... |
| 159 |
}; |
| 160 |
``` |
| 161 |
|
| 162 |
### Mocking Class Templates |
| 163 |
|
| 164 |
You can mock class templates just like any class. |
| 165 |
|
| 166 |
```cpp |
| 167 |
template <typename Elem> |
| 168 |
class StackInterface { |
| 169 |
... |
| 170 |
// Must be virtual as we'll inherit from StackInterface. |
| 171 |
virtual ~StackInterface(); |
| 172 |
|
| 173 |
virtual int GetSize() const = 0; |
| 174 |
virtual void Push(const Elem& x) = 0; |
| 175 |
}; |
| 176 |
|
| 177 |
template <typename Elem> |
| 178 |
class MockStack : public StackInterface<Elem> { |
| 179 |
... |
| 180 |
MOCK_METHOD(int, GetSize, (), (override)); |
| 181 |
MOCK_METHOD(void, Push, (const Elem& x), (override)); |
| 182 |
}; |
| 183 |
``` |
| 184 |
|
| 185 |
### Mocking Non-virtual Methods {#MockingNonVirtualMethods} |
| 186 |
|
| 187 |
gMock can mock non-virtual functions to be used in Hi-perf dependency injection. |
| 188 |
|
| 189 |
In this case, instead of sharing a common base class with the real class, your |
| 190 |
mock class will be *unrelated* to the real class, but contain methods with the |
| 191 |
same signatures. The syntax for mocking non-virtual methods is the *same* as |
| 192 |
mocking virtual methods (just don't add `override`): |
| 193 |
|
| 194 |
```cpp |
| 195 |
// A simple packet stream class. None of its members is virtual. |
| 196 |
class ConcretePacketStream { |
| 197 |
public: |
| 198 |
void AppendPacket(Packet* new_packet); |
| 199 |
const Packet* GetPacket(size_t packet_number) const; |
| 200 |
size_t NumberOfPackets() const; |
| 201 |
... |
| 202 |
}; |
| 203 |
|
| 204 |
// A mock packet stream class. It inherits from no other, but defines |
| 205 |
// GetPacket() and NumberOfPackets(). |
| 206 |
class MockPacketStream { |
| 207 |
public: |
| 208 |
MOCK_METHOD(const Packet*, GetPacket, (size_t packet_number), (const)); |
| 209 |
MOCK_METHOD(size_t, NumberOfPackets, (), (const)); |
| 210 |
... |
| 211 |
}; |
| 212 |
``` |
| 213 |
|
| 214 |
Note that the mock class doesn't define `AppendPacket()`, unlike the real class. |
| 215 |
That's fine as long as the test doesn't need to call it. |
| 216 |
|
| 217 |
Next, you need a way to say that you want to use `ConcretePacketStream` in |
| 218 |
production code, and use `MockPacketStream` in tests. Since the functions are |
| 219 |
not virtual and the two classes are unrelated, you must specify your choice at |
| 220 |
*compile time* (as opposed to run time). |
| 221 |
|
| 222 |
One way to do it is to templatize your code that needs to use a packet stream. |
| 223 |
More specifically, you will give your code a template type argument for the type |
| 224 |
of the packet stream. In production, you will instantiate your template with |
| 225 |
`ConcretePacketStream` as the type argument. In tests, you will instantiate the |
| 226 |
same template with `MockPacketStream`. For example, you may write: |
| 227 |
|
| 228 |
```cpp |
| 229 |
template <class PacketStream> |
| 230 |
void CreateConnection(PacketStream* stream) { ... } |
| 231 |
|
| 232 |
template <class PacketStream> |
| 233 |
class PacketReader { |
| 234 |
public: |
| 235 |
void ReadPackets(PacketStream* stream, size_t packet_num); |
| 236 |
}; |
| 237 |
``` |
| 238 |
|
| 239 |
Then you can use `CreateConnection<ConcretePacketStream>()` and |
| 240 |
`PacketReader<ConcretePacketStream>` in production code, and use |
| 241 |
`CreateConnection<MockPacketStream>()` and `PacketReader<MockPacketStream>` in |
| 242 |
tests. |
| 243 |
|
| 244 |
```cpp |
| 245 |
MockPacketStream mock_stream; |
| 246 |
EXPECT_CALL(mock_stream, ...)...; |
| 247 |
.. set more expectations on mock_stream ... |
| 248 |
PacketReader<MockPacketStream> reader(&mock_stream); |
| 249 |
... exercise reader ... |
| 250 |
``` |
| 251 |
|
| 252 |
### Mocking Free Functions |
| 253 |
|
| 254 |
It is not possible to directly mock a free function (i.e. a C-style function or |
| 255 |
a static method). If you need to, you can rewrite your code to use an interface |
| 256 |
(abstract class). |
| 257 |
|
| 258 |
Instead of calling a free function (say, `OpenFile`) directly, introduce an |
| 259 |
interface for it and have a concrete subclass that calls the free function: |
| 260 |
|
| 261 |
```cpp |
| 262 |
class FileInterface { |
| 263 |
public: |
| 264 |
... |
| 265 |
virtual bool Open(const char* path, const char* mode) = 0; |
| 266 |
}; |
| 267 |
|
| 268 |
class File : public FileInterface { |
| 269 |
public: |
| 270 |
... |
| 271 |
bool Open(const char* path, const char* mode) override { |
| 272 |
return OpenFile(path, mode); |
| 273 |
} |
| 274 |
}; |
| 275 |
``` |
| 276 |
|
| 277 |
Your code should talk to `FileInterface` to open a file. Now it's easy to mock |
| 278 |
out the function. |
| 279 |
|
| 280 |
This may seem like a lot of hassle, but in practice you often have multiple |
| 281 |
related functions that you can put in the same interface, so the per-function |
| 282 |
syntactic overhead will be much lower. |
| 283 |
|
| 284 |
If you are concerned about the performance overhead incurred by virtual |
| 285 |
functions, and profiling confirms your concern, you can combine this with the |
| 286 |
recipe for [mocking non-virtual methods](#MockingNonVirtualMethods). |
| 287 |
|
| 288 |
### Old-Style `MOCK_METHODn` Macros |
| 289 |
|
| 290 |
Before the generic `MOCK_METHOD` macro |
| 291 |
[was introduced in 2018](https://github.com/google/googletest/commit/c5f08bf91944ce1b19bcf414fa1760e69d20afc2), |
| 292 |
mocks where created using a family of macros collectively called `MOCK_METHODn`. |
| 293 |
These macros are still supported, though migration to the new `MOCK_METHOD` is |
| 294 |
recommended. |
| 295 |
|
| 296 |
The macros in the `MOCK_METHODn` family differ from `MOCK_METHOD`: |
| 297 |
|
| 298 |
* The general structure is `MOCK_METHODn(MethodName, ReturnType(Args))`, |
| 299 |
instead of `MOCK_METHOD(ReturnType, MethodName, (Args))`. |
| 300 |
* The number `n` must equal the number of arguments. |
| 301 |
* When mocking a const method, one must use `MOCK_CONST_METHODn`. |
| 302 |
* When mocking a class template, the macro name must be suffixed with `_T`. |
| 303 |
* In order to specify the call type, the macro name must be suffixed with |
| 304 |
`_WITH_CALLTYPE`, and the call type is the first macro argument. |
| 305 |
|
| 306 |
Old macros and their new equivalents: |
| 307 |
|
| 308 |
<table> |
| 309 |
<tr><th colspan=2>Simple</th></tr> |
| 310 |
<tr> |
| 311 |
<td>Old</td> |
| 312 |
<td><code>MOCK_METHOD1(Foo, bool(int))</code></td> |
| 313 |
</tr> |
| 314 |
<tr> |
| 315 |
<td>New</td> |
| 316 |
<td><code>MOCK_METHOD(bool, Foo, (int))</code></td> |
| 317 |
</tr> |
| 318 |
|
| 319 |
<tr><th colspan=2>Const Method</th></tr> |
| 320 |
<tr> |
| 321 |
<td>Old</td> |
| 322 |
<td><code>MOCK_CONST_METHOD1(Foo, bool(int))</code></td> |
| 323 |
</tr> |
| 324 |
<tr> |
| 325 |
<td>New</td> |
| 326 |
<td><code>MOCK_METHOD(bool, Foo, (int), (const))</code></td> |
| 327 |
</tr> |
| 328 |
|
| 329 |
<tr><th colspan=2>Method in a Class Template</th></tr> |
| 330 |
<tr> |
| 331 |
<td>Old</td> |
| 332 |
<td><code>MOCK_METHOD1_T(Foo, bool(int))</code></td> |
| 333 |
</tr> |
| 334 |
<tr> |
| 335 |
<td>New</td> |
| 336 |
<td><code>MOCK_METHOD(bool, Foo, (int))</code></td> |
| 337 |
</tr> |
| 338 |
|
| 339 |
<tr><th colspan=2>Const Method in a Class Template</th></tr> |
| 340 |
<tr> |
| 341 |
<td>Old</td> |
| 342 |
<td><code>MOCK_CONST_METHOD1_T(Foo, bool(int))</code></td> |
| 343 |
</tr> |
| 344 |
<tr> |
| 345 |
<td>New</td> |
| 346 |
<td><code>MOCK_METHOD(bool, Foo, (int), (const))</code></td> |
| 347 |
</tr> |
| 348 |
|
| 349 |
<tr><th colspan=2>Method with Call Type</th></tr> |
| 350 |
<tr> |
| 351 |
<td>Old</td> |
| 352 |
<td><code>MOCK_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td> |
| 353 |
</tr> |
| 354 |
<tr> |
| 355 |
<td>New</td> |
| 356 |
<td><code>MOCK_METHOD(bool, Foo, (int), (Calltype(STDMETHODCALLTYPE)))</code></td> |
| 357 |
</tr> |
| 358 |
|
| 359 |
<tr><th colspan=2>Const Method with Call Type</th></tr> |
| 360 |
<tr> |
| 361 |
<td>Old</td> |
| 362 |
<td><code>MOCK_CONST_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td> |
| 363 |
</tr> |
| 364 |
<tr> |
| 365 |
<td>New</td> |
| 366 |
<td><code>MOCK_METHOD(bool, Foo, (int), (const, Calltype(STDMETHODCALLTYPE)))</code></td> |
| 367 |
</tr> |
| 368 |
|
| 369 |
<tr><th colspan=2>Method with Call Type in a Class Template</th></tr> |
| 370 |
<tr> |
| 371 |
<td>Old</td> |
| 372 |
<td><code>MOCK_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td> |
| 373 |
</tr> |
| 374 |
<tr> |
| 375 |
<td>New</td> |
| 376 |
<td><code>MOCK_METHOD(bool, Foo, (int), (Calltype(STDMETHODCALLTYPE)))</code></td> |
| 377 |
</tr> |
| 378 |
|
| 379 |
<tr><th colspan=2>Const Method with Call Type in a Class Template</th></tr> |
| 380 |
<tr> |
| 381 |
<td>Old</td> |
| 382 |
<td><code>MOCK_CONST_METHOD1_T_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int))</code></td> |
| 383 |
</tr> |
| 384 |
<tr> |
| 385 |
<td>New</td> |
| 386 |
<td><code>MOCK_METHOD(bool, Foo, (int), (const, Calltype(STDMETHODCALLTYPE)))</code></td> |
| 387 |
</tr> |
| 388 |
</table> |
| 389 |
|
| 390 |
### The Nice, the Strict, and the Naggy {#NiceStrictNaggy} |
| 391 |
|
| 392 |
If a mock method has no `EXPECT_CALL` spec but is called, we say that it's an |
| 393 |
"uninteresting call", and the default action (which can be specified using |
| 394 |
`ON_CALL()`) of the method will be taken. Currently, an uninteresting call will |
| 395 |
also by default cause gMock to print a warning. (In the future, we might remove |
| 396 |
this warning by default.) |
| 397 |
|
| 398 |
However, sometimes you may want to ignore these uninteresting calls, and |
| 399 |
sometimes you may want to treat them as errors. gMock lets you make the decision |
| 400 |
on a per-mock-object basis. |
| 401 |
|
| 402 |
Suppose your test uses a mock class `MockFoo`: |
| 403 |
|
| 404 |
```cpp |
| 405 |
TEST(...) { |
| 406 |
MockFoo mock_foo; |
| 407 |
EXPECT_CALL(mock_foo, DoThis()); |
| 408 |
... code that uses mock_foo ... |
| 409 |
} |
| 410 |
``` |
| 411 |
|
| 412 |
If a method of `mock_foo` other than `DoThis()` is called, you will get a |
| 413 |
warning. However, if you rewrite your test to use `NiceMock<MockFoo>` instead, |
| 414 |
you can suppress the warning: |
| 415 |
|
| 416 |
```cpp |
| 417 |
using ::testing::NiceMock; |
| 418 |
|
| 419 |
TEST(...) { |
| 420 |
NiceMock<MockFoo> mock_foo; |
| 421 |
EXPECT_CALL(mock_foo, DoThis()); |
| 422 |
... code that uses mock_foo ... |
| 423 |
} |
| 424 |
``` |
| 425 |
|
| 426 |
`NiceMock<MockFoo>` is a subclass of `MockFoo`, so it can be used wherever |
| 427 |
`MockFoo` is accepted. |
| 428 |
|
| 429 |
It also works if `MockFoo`'s constructor takes some arguments, as |
| 430 |
`NiceMock<MockFoo>` "inherits" `MockFoo`'s constructors: |
| 431 |
|
| 432 |
```cpp |
| 433 |
using ::testing::NiceMock; |
| 434 |
|
| 435 |
TEST(...) { |
| 436 |
NiceMock<MockFoo> mock_foo(5, "hi"); // Calls MockFoo(5, "hi"). |
| 437 |
EXPECT_CALL(mock_foo, DoThis()); |
| 438 |
... code that uses mock_foo ... |
| 439 |
} |
| 440 |
``` |
| 441 |
|
| 442 |
The usage of `StrictMock` is similar, except that it makes all uninteresting |
| 443 |
calls failures: |
| 444 |
|
| 445 |
```cpp |
| 446 |
using ::testing::StrictMock; |
| 447 |
|
| 448 |
TEST(...) { |
| 449 |
StrictMock<MockFoo> mock_foo; |
| 450 |
EXPECT_CALL(mock_foo, DoThis()); |
| 451 |
... code that uses mock_foo ... |
| 452 |
|
| 453 |
// The test will fail if a method of mock_foo other than DoThis() |
| 454 |
// is called. |
| 455 |
} |
| 456 |
``` |
| 457 |
|
| 458 |
{: .callout .note} |
| 459 |
NOTE: `NiceMock` and `StrictMock` only affects *uninteresting* calls (calls of |
| 460 |
*methods* with no expectations); they do not affect *unexpected* calls (calls of |
| 461 |
methods with expectations, but they don't match). See |
| 462 |
[Understanding Uninteresting vs Unexpected Calls](#uninteresting-vs-unexpected). |
| 463 |
|
| 464 |
There are some caveats though (sadly they are side effects of C++'s |
| 465 |
limitations): |
| 466 |
|
| 467 |
1. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` only work for mock methods |
| 468 |
defined using the `MOCK_METHOD` macro **directly** in the `MockFoo` class. |
| 469 |
If a mock method is defined in a **base class** of `MockFoo`, the "nice" or |
| 470 |
"strict" modifier may not affect it, depending on the compiler. In |
| 471 |
particular, nesting `NiceMock` and `StrictMock` (e.g. |
| 472 |
`NiceMock<StrictMock<MockFoo> >`) is **not** supported. |
| 473 |
2. `NiceMock<MockFoo>` and `StrictMock<MockFoo>` may not work correctly if the |
| 474 |
destructor of `MockFoo` is not virtual. We would like to fix this, but it |
| 475 |
requires cleaning up existing tests. |
| 476 |
|
| 477 |
Finally, you should be **very cautious** about when to use naggy or strict |
| 478 |
mocks, as they tend to make tests more brittle and harder to maintain. When you |
| 479 |
refactor your code without changing its externally visible behavior, ideally you |
| 480 |
shouldn't need to update any tests. If your code interacts with a naggy mock, |
| 481 |
however, you may start to get spammed with warnings as the result of your |
| 482 |
change. Worse, if your code interacts with a strict mock, your tests may start |
| 483 |
to fail and you'll be forced to fix them. Our general recommendation is to use |
| 484 |
nice mocks (not yet the default) most of the time, use naggy mocks (the current |
| 485 |
default) when developing or debugging tests, and use strict mocks only as the |
| 486 |
last resort. |
| 487 |
|
| 488 |
### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces} |
| 489 |
|
| 490 |
Sometimes a method has a long list of arguments that is mostly uninteresting. |
| 491 |
For example: |
| 492 |
|
| 493 |
```cpp |
| 494 |
class LogSink { |
| 495 |
public: |
| 496 |
... |
| 497 |
virtual void send(LogSeverity severity, const char* full_filename, |
| 498 |
const char* base_filename, int line, |
| 499 |
const struct tm* tm_time, |
| 500 |
const char* message, size_t message_len) = 0; |
| 501 |
}; |
| 502 |
``` |
| 503 |
|
| 504 |
This method's argument list is lengthy and hard to work with (the `message` |
| 505 |
argument is not even 0-terminated). If we mock it as is, using the mock will be |
| 506 |
awkward. If, however, we try to simplify this interface, we'll need to fix all |
| 507 |
clients depending on it, which is often infeasible. |
| 508 |
|
| 509 |
The trick is to redispatch the method in the mock class: |
| 510 |
|
| 511 |
```cpp |
| 512 |
class ScopedMockLog : public LogSink { |
| 513 |
public: |
| 514 |
... |
| 515 |
void send(LogSeverity severity, const char* full_filename, |
| 516 |
const char* base_filename, int line, const tm* tm_time, |
| 517 |
const char* message, size_t message_len) override { |
| 518 |
// We are only interested in the log severity, full file name, and |
| 519 |
// log message. |
| 520 |
Log(severity, full_filename, std::string(message, message_len)); |
| 521 |
} |
| 522 |
|
| 523 |
// Implements the mock method: |
| 524 |
// |
| 525 |
// void Log(LogSeverity severity, |
| 526 |
// const string& file_path, |
| 527 |
// const string& message); |
| 528 |
MOCK_METHOD(void, Log, |
| 529 |
(LogSeverity severity, const string& file_path, |
| 530 |
const string& message)); |
| 531 |
}; |
| 532 |
``` |
| 533 |
|
| 534 |
By defining a new mock method with a trimmed argument list, we make the mock |
| 535 |
class more user-friendly. |
| 536 |
|
| 537 |
This technique may also be applied to make overloaded methods more amenable to |
| 538 |
mocking. For example, when overloads have been used to implement default |
| 539 |
arguments: |
| 540 |
|
| 541 |
```cpp |
| 542 |
class MockTurtleFactory : public TurtleFactory { |
| 543 |
public: |
| 544 |
Turtle* MakeTurtle(int length, int weight) override { ... } |
| 545 |
Turtle* MakeTurtle(int length, int weight, int speed) override { ... } |
| 546 |
|
| 547 |
// the above methods delegate to this one: |
| 548 |
MOCK_METHOD(Turtle*, DoMakeTurtle, ()); |
| 549 |
}; |
| 550 |
``` |
| 551 |
|
| 552 |
This allows tests that don't care which overload was invoked to avoid specifying |
| 553 |
argument matchers: |
| 554 |
|
| 555 |
```cpp |
| 556 |
ON_CALL(factory, DoMakeTurtle) |
| 557 |
.WillByDefault(Return(MakeMockTurtle())); |
| 558 |
``` |
| 559 |
|
| 560 |
### Alternative to Mocking Concrete Classes |
| 561 |
|
| 562 |
Often you may find yourself using classes that don't implement interfaces. In |
| 563 |
order to test your code that uses such a class (let's call it `Concrete`), you |
| 564 |
may be tempted to make the methods of `Concrete` virtual and then mock it. |
| 565 |
|
| 566 |
Try not to do that. |
| 567 |
|
| 568 |
Making a non-virtual function virtual is a big decision. It creates an extension |
| 569 |
point where subclasses can tweak your class' behavior. This weakens your control |
| 570 |
on the class because now it's harder to maintain the class invariants. You |
| 571 |
should make a function virtual only when there is a valid reason for a subclass |
| 572 |
to override it. |
| 573 |
|
| 574 |
Mocking concrete classes directly is problematic as it creates a tight coupling |
| 575 |
between the class and the tests - any small change in the class may invalidate |
| 576 |
your tests and make test maintenance a pain. |
| 577 |
|
| 578 |
To avoid such problems, many programmers have been practicing "coding to |
| 579 |
interfaces": instead of talking to the `Concrete` class, your code would define |
| 580 |
an interface and talk to it. Then you implement that interface as an adaptor on |
| 581 |
top of `Concrete`. In tests, you can easily mock that interface to observe how |
| 582 |
your code is doing. |
| 583 |
|
| 584 |
This technique incurs some overhead: |
| 585 |
|
| 586 |
* You pay the cost of virtual function calls (usually not a problem). |
| 587 |
* There is more abstraction for the programmers to learn. |
| 588 |
|
| 589 |
However, it can also bring significant benefits in addition to better |
| 590 |
testability: |
| 591 |
|
| 592 |
* `Concrete`'s API may not fit your problem domain very well, as you may not |
| 593 |
be the only client it tries to serve. By designing your own interface, you |
| 594 |
have a chance to tailor it to your need - you may add higher-level |
| 595 |
functionalities, rename stuff, etc instead of just trimming the class. This |
| 596 |
allows you to write your code (user of the interface) in a more natural way, |
| 597 |
which means it will be more readable, more maintainable, and you'll be more |
| 598 |
productive. |
| 599 |
* If `Concrete`'s implementation ever has to change, you don't have to rewrite |
| 600 |
everywhere it is used. Instead, you can absorb the change in your |
| 601 |
implementation of the interface, and your other code and tests will be |
| 602 |
insulated from this change. |
| 603 |
|
| 604 |
Some people worry that if everyone is practicing this technique, they will end |
| 605 |
up writing lots of redundant code. This concern is totally understandable. |
| 606 |
However, there are two reasons why it may not be the case: |
| 607 |
|
| 608 |
* Different projects may need to use `Concrete` in different ways, so the best |
| 609 |
interfaces for them will be different. Therefore, each of them will have its |
| 610 |
own domain-specific interface on top of `Concrete`, and they will not be the |
| 611 |
same code. |
| 612 |
* If enough projects want to use the same interface, they can always share it, |
| 613 |
just like they have been sharing `Concrete`. You can check in the interface |
| 614 |
and the adaptor somewhere near `Concrete` (perhaps in a `contrib` |
| 615 |
sub-directory) and let many projects use it. |
| 616 |
|
| 617 |
You need to weigh the pros and cons carefully for your particular problem, but |
| 618 |
I'd like to assure you that the Java community has been practicing this for a |
| 619 |
long time and it's a proven effective technique applicable in a wide variety of |
| 620 |
situations. :-) |
| 621 |
|
| 622 |
### Delegating Calls to a Fake {#DelegatingToFake} |
| 623 |
|
| 624 |
Some times you have a non-trivial fake implementation of an interface. For |
| 625 |
example: |
| 626 |
|
| 627 |
```cpp |
| 628 |
class Foo { |
| 629 |
public: |
| 630 |
virtual ~Foo() {} |
| 631 |
virtual char DoThis(int n) = 0; |
| 632 |
virtual void DoThat(const char* s, int* p) = 0; |
| 633 |
}; |
| 634 |
|
| 635 |
class FakeFoo : public Foo { |
| 636 |
public: |
| 637 |
char DoThis(int n) override { |
| 638 |
return (n > 0) ? '+' : |
| 639 |
(n < 0) ? '-' : '0'; |
| 640 |
} |
| 641 |
|
| 642 |
void DoThat(const char* s, int* p) override { |
| 643 |
*p = strlen(s); |
| 644 |
} |
| 645 |
}; |
| 646 |
``` |
| 647 |
|
| 648 |
Now you want to mock this interface such that you can set expectations on it. |
| 649 |
However, you also want to use `FakeFoo` for the default behavior, as duplicating |
| 650 |
it in the mock object is, well, a lot of work. |
| 651 |
|
| 652 |
When you define the mock class using gMock, you can have it delegate its default |
| 653 |
action to a fake class you already have, using this pattern: |
| 654 |
|
| 655 |
```cpp |
| 656 |
class MockFoo : public Foo { |
| 657 |
public: |
| 658 |
// Normal mock method definitions using gMock. |
| 659 |
MOCK_METHOD(char, DoThis, (int n), (override)); |
| 660 |
MOCK_METHOD(void, DoThat, (const char* s, int* p), (override)); |
| 661 |
|
| 662 |
// Delegates the default actions of the methods to a FakeFoo object. |
| 663 |
// This must be called *before* the custom ON_CALL() statements. |
| 664 |
void DelegateToFake() { |
| 665 |
ON_CALL(*this, DoThis).WillByDefault([this](int n) { |
| 666 |
return fake_.DoThis(n); |
| 667 |
}); |
| 668 |
ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) { |
| 669 |
fake_.DoThat(s, p); |
| 670 |
}); |
| 671 |
} |
| 672 |
|
| 673 |
private: |
| 674 |
FakeFoo fake_; // Keeps an instance of the fake in the mock. |
| 675 |
}; |
| 676 |
``` |
| 677 |
|
| 678 |
With that, you can use `MockFoo` in your tests as usual. Just remember that if |
| 679 |
you don't explicitly set an action in an `ON_CALL()` or `EXPECT_CALL()`, the |
| 680 |
fake will be called upon to do it.: |
| 681 |
|
| 682 |
```cpp |
| 683 |
using ::testing::_; |
| 684 |
|
| 685 |
TEST(AbcTest, Xyz) { |
| 686 |
MockFoo foo; |
| 687 |
|
| 688 |
foo.DelegateToFake(); // Enables the fake for delegation. |
| 689 |
|
| 690 |
// Put your ON_CALL(foo, ...)s here, if any. |
| 691 |
|
| 692 |
// No action specified, meaning to use the default action. |
| 693 |
EXPECT_CALL(foo, DoThis(5)); |
| 694 |
EXPECT_CALL(foo, DoThat(_, _)); |
| 695 |
|
| 696 |
int n = 0; |
| 697 |
EXPECT_EQ('+', foo.DoThis(5)); // FakeFoo::DoThis() is invoked. |
| 698 |
foo.DoThat("Hi", &n); // FakeFoo::DoThat() is invoked. |
| 699 |
EXPECT_EQ(2, n); |
| 700 |
} |
| 701 |
``` |
| 702 |
|
| 703 |
**Some tips:** |
| 704 |
|
| 705 |
* If you want, you can still override the default action by providing your own |
| 706 |
`ON_CALL()` or using `.WillOnce()` / `.WillRepeatedly()` in `EXPECT_CALL()`. |
| 707 |
* In `DelegateToFake()`, you only need to delegate the methods whose fake |
| 708 |
implementation you intend to use. |
| 709 |
|
| 710 |
* The general technique discussed here works for overloaded methods, but |
| 711 |
you'll need to tell the compiler which version you mean. To disambiguate a |
| 712 |
mock function (the one you specify inside the parentheses of `ON_CALL()`), |
| 713 |
use [this technique](#SelectOverload); to disambiguate a fake function (the |
| 714 |
one you place inside `Invoke()`), use a `static_cast` to specify the |
| 715 |
function's type. For instance, if class `Foo` has methods `char DoThis(int |
| 716 |
n)` and `bool DoThis(double x) const`, and you want to invoke the latter, |
| 717 |
you need to write `Invoke(&fake_, static_cast<bool (FakeFoo::*)(double) |
| 718 |
const>(&FakeFoo::DoThis))` instead of `Invoke(&fake_, &FakeFoo::DoThis)` |
| 719 |
(The strange-looking thing inside the angled brackets of `static_cast` is |
| 720 |
the type of a function pointer to the second `DoThis()` method.). |
| 721 |
|
| 722 |
* Having to mix a mock and a fake is often a sign of something gone wrong. |
| 723 |
Perhaps you haven't got used to the interaction-based way of testing yet. Or |
| 724 |
perhaps your interface is taking on too many roles and should be split up. |
| 725 |
Therefore, **don't abuse this**. We would only recommend to do it as an |
| 726 |
intermediate step when you are refactoring your code. |
| 727 |
|
| 728 |
Regarding the tip on mixing a mock and a fake, here's an example on why it may |
| 729 |
be a bad sign: Suppose you have a class `System` for low-level system |
| 730 |
operations. In particular, it does file and I/O operations. And suppose you want |
| 731 |
to test how your code uses `System` to do I/O, and you just want the file |
| 732 |
operations to work normally. If you mock out the entire `System` class, you'll |
| 733 |
have to provide a fake implementation for the file operation part, which |
| 734 |
suggests that `System` is taking on too many roles. |
| 735 |
|
| 736 |
Instead, you can define a `FileOps` interface and an `IOOps` interface and split |
| 737 |
`System`'s functionalities into the two. Then you can mock `IOOps` without |
| 738 |
mocking `FileOps`. |
| 739 |
|
| 740 |
### Delegating Calls to a Real Object |
| 741 |
|
| 742 |
When using testing doubles (mocks, fakes, stubs, and etc), sometimes their |
| 743 |
behaviors will differ from those of the real objects. This difference could be |
| 744 |
either intentional (as in simulating an error such that you can test the error |
| 745 |
handling code) or unintentional. If your mocks have different behaviors than the |
| 746 |
real objects by mistake, you could end up with code that passes the tests but |
| 747 |
fails in production. |
| 748 |
|
| 749 |
You can use the *delegating-to-real* technique to ensure that your mock has the |
| 750 |
same behavior as the real object while retaining the ability to validate calls. |
| 751 |
This technique is very similar to the [delegating-to-fake](#DelegatingToFake) |
| 752 |
technique, the difference being that we use a real object instead of a fake. |
| 753 |
Here's an example: |
| 754 |
|
| 755 |
```cpp |
| 756 |
using ::testing::AtLeast; |
| 757 |
|
| 758 |
class MockFoo : public Foo { |
| 759 |
public: |
| 760 |
MockFoo() { |
| 761 |
// By default, all calls are delegated to the real object. |
| 762 |
ON_CALL(*this, DoThis).WillByDefault([this](int n) { |
| 763 |
return real_.DoThis(n); |
| 764 |
}); |
| 765 |
ON_CALL(*this, DoThat).WillByDefault([this](const char* s, int* p) { |
| 766 |
real_.DoThat(s, p); |
| 767 |
}); |
| 768 |
... |
| 769 |
} |
| 770 |
MOCK_METHOD(char, DoThis, ...); |
| 771 |
MOCK_METHOD(void, DoThat, ...); |
| 772 |
... |
| 773 |
private: |
| 774 |
Foo real_; |
| 775 |
}; |
| 776 |
|
| 777 |
... |
| 778 |
MockFoo mock; |
| 779 |
EXPECT_CALL(mock, DoThis()) |
| 780 |
.Times(3); |
| 781 |
EXPECT_CALL(mock, DoThat("Hi")) |
| 782 |
.Times(AtLeast(1)); |
| 783 |
... use mock in test ... |
| 784 |
``` |
| 785 |
|
| 786 |
With this, gMock will verify that your code made the right calls (with the right |
| 787 |
arguments, in the right order, called the right number of times, etc), and a |
| 788 |
real object will answer the calls (so the behavior will be the same as in |
| 789 |
production). This gives you the best of both worlds. |
| 790 |
|
| 791 |
### Delegating Calls to a Parent Class |
| 792 |
|
| 793 |
Ideally, you should code to interfaces, whose methods are all pure virtual. In |
| 794 |
reality, sometimes you do need to mock a virtual method that is not pure (i.e, |
| 795 |
it already has an implementation). For example: |
| 796 |
|
| 797 |
```cpp |
| 798 |
class Foo { |
| 799 |
public: |
| 800 |
virtual ~Foo(); |
| 801 |
|
| 802 |
virtual void Pure(int n) = 0; |
| 803 |
virtual int Concrete(const char* str) { ... } |
| 804 |
}; |
| 805 |
|
| 806 |
class MockFoo : public Foo { |
| 807 |
public: |
| 808 |
// Mocking a pure method. |
| 809 |
MOCK_METHOD(void, Pure, (int n), (override)); |
| 810 |
// Mocking a concrete method. Foo::Concrete() is shadowed. |
| 811 |
MOCK_METHOD(int, Concrete, (const char* str), (override)); |
| 812 |
}; |
| 813 |
``` |
| 814 |
|
| 815 |
Sometimes you may want to call `Foo::Concrete()` instead of |
| 816 |
`MockFoo::Concrete()`. Perhaps you want to do it as part of a stub action, or |
| 817 |
perhaps your test doesn't need to mock `Concrete()` at all (but it would be |
| 818 |
oh-so painful to have to define a new mock class whenever you don't need to mock |
| 819 |
one of its methods). |
| 820 |
|
| 821 |
You can call `Foo::Concrete()` inside an action by: |
| 822 |
|
| 823 |
```cpp |
| 824 |
... |
| 825 |
EXPECT_CALL(foo, Concrete).WillOnce([&foo](const char* str) { |
| 826 |
return foo.Foo::Concrete(str); |
| 827 |
}); |
| 828 |
``` |
| 829 |
|
| 830 |
or tell the mock object that you don't want to mock `Concrete()`: |
| 831 |
|
| 832 |
```cpp |
| 833 |
... |
| 834 |
ON_CALL(foo, Concrete).WillByDefault([&foo](const char* str) { |
| 835 |
return foo.Foo::Concrete(str); |
| 836 |
}); |
| 837 |
``` |
| 838 |
|
| 839 |
(Why don't we just write `{ return foo.Concrete(str); }`? If you do that, |
| 840 |
`MockFoo::Concrete()` will be called (and cause an infinite recursion) since |
| 841 |
`Foo::Concrete()` is virtual. That's just how C++ works.) |
| 842 |
|
| 843 |
## Using Matchers |
| 844 |
|
| 845 |
### Matching Argument Values Exactly |
| 846 |
|
| 847 |
You can specify exactly which arguments a mock method is expecting: |
| 848 |
|
| 849 |
```cpp |
| 850 |
using ::testing::Return; |
| 851 |
... |
| 852 |
EXPECT_CALL(foo, DoThis(5)) |
| 853 |
.WillOnce(Return('a')); |
| 854 |
EXPECT_CALL(foo, DoThat("Hello", bar)); |
| 855 |
``` |
| 856 |
|
| 857 |
### Using Simple Matchers |
| 858 |
|
| 859 |
You can use matchers to match arguments that have a certain property: |
| 860 |
|
| 861 |
```cpp |
| 862 |
using ::testing::NotNull; |
| 863 |
using ::testing::Return; |
| 864 |
... |
| 865 |
EXPECT_CALL(foo, DoThis(Ge(5))) // The argument must be >= 5. |
| 866 |
.WillOnce(Return('a')); |
| 867 |
EXPECT_CALL(foo, DoThat("Hello", NotNull())); |
| 868 |
// The second argument must not be NULL. |
| 869 |
``` |
| 870 |
|
| 871 |
A frequently used matcher is `_`, which matches anything: |
| 872 |
|
| 873 |
```cpp |
| 874 |
EXPECT_CALL(foo, DoThat(_, NotNull())); |
| 875 |
``` |
| 876 |
|
| 877 |
### Combining Matchers {#CombiningMatchers} |
| 878 |
|
| 879 |
You can build complex matchers from existing ones using `AllOf()`, |
| 880 |
`AllOfArray()`, `AnyOf()`, `AnyOfArray()` and `Not()`: |
| 881 |
|
| 882 |
```cpp |
| 883 |
using ::testing::AllOf; |
| 884 |
using ::testing::Gt; |
| 885 |
using ::testing::HasSubstr; |
| 886 |
using ::testing::Ne; |
| 887 |
using ::testing::Not; |
| 888 |
... |
| 889 |
// The argument must be > 5 and != 10. |
| 890 |
EXPECT_CALL(foo, DoThis(AllOf(Gt(5), |
| 891 |
Ne(10)))); |
| 892 |
|
| 893 |
// The first argument must not contain sub-string "blah". |
| 894 |
EXPECT_CALL(foo, DoThat(Not(HasSubstr("blah")), |
| 895 |
NULL)); |
| 896 |
``` |
| 897 |
|
| 898 |
Matchers are function objects, and parametrized matchers can be composed just |
| 899 |
like any other function. However because their types can be long and rarely |
| 900 |
provide meaningful information, it can be easier to express them with C++14 |
| 901 |
generic lambdas to avoid specifying types. For example, |
| 902 |
|
| 903 |
```cpp |
| 904 |
using ::testing::Contains; |
| 905 |
using ::testing::Property; |
| 906 |
|
| 907 |
inline constexpr auto HasFoo = [](const auto& f) { |
| 908 |
return Property(&MyClass::foo, Contains(f)); |
| 909 |
}; |
| 910 |
... |
| 911 |
EXPECT_THAT(x, HasFoo("blah")); |
| 912 |
``` |
| 913 |
|
| 914 |
### Casting Matchers {#SafeMatcherCast} |
| 915 |
|
| 916 |
gMock matchers are statically typed, meaning that the compiler can catch your |
| 917 |
mistake if you use a matcher of the wrong type (for example, if you use `Eq(5)` |
| 918 |
to match a `string` argument). Good for you! |
| 919 |
|
| 920 |
Sometimes, however, you know what you're doing and want the compiler to give you |
| 921 |
some slack. One example is that you have a matcher for `long` and the argument |
| 922 |
you want to match is `int`. While the two types aren't exactly the same, there |
| 923 |
is nothing really wrong with using a `Matcher<long>` to match an `int` - after |
| 924 |
all, we can first convert the `int` argument to a `long` losslessly before |
| 925 |
giving it to the matcher. |
| 926 |
|
| 927 |
To support this need, gMock gives you the `SafeMatcherCast<T>(m)` function. It |
| 928 |
casts a matcher `m` to type `Matcher<T>`. To ensure safety, gMock checks that |
| 929 |
(let `U` be the type `m` accepts : |
| 930 |
|
| 931 |
1. Type `T` can be *implicitly* cast to type `U`; |
| 932 |
2. When both `T` and `U` are built-in arithmetic types (`bool`, integers, and |
| 933 |
floating-point numbers), the conversion from `T` to `U` is not lossy (in |
| 934 |
other words, any value representable by `T` can also be represented by `U`); |
| 935 |
and |
| 936 |
3. When `U` is a reference, `T` must also be a reference (as the underlying |
| 937 |
matcher may be interested in the address of the `U` value). |
| 938 |
|
| 939 |
The code won't compile if any of these conditions isn't met. |
| 940 |
|
| 941 |
Here's one example: |
| 942 |
|
| 943 |
```cpp |
| 944 |
using ::testing::SafeMatcherCast; |
| 945 |
|
| 946 |
// A base class and a child class. |
| 947 |
class Base { ... }; |
| 948 |
class Derived : public Base { ... }; |
| 949 |
|
| 950 |
class MockFoo : public Foo { |
| 951 |
public: |
| 952 |
MOCK_METHOD(void, DoThis, (Derived* derived), (override)); |
| 953 |
}; |
| 954 |
|
| 955 |
... |
| 956 |
MockFoo foo; |
| 957 |
// m is a Matcher<Base*> we got from somewhere. |
| 958 |
EXPECT_CALL(foo, DoThis(SafeMatcherCast<Derived*>(m))); |
| 959 |
``` |
| 960 |
|
| 961 |
If you find `SafeMatcherCast<T>(m)` too limiting, you can use a similar function |
| 962 |
`MatcherCast<T>(m)`. The difference is that `MatcherCast` works as long as you |
| 963 |
can `static_cast` type `T` to type `U`. |
| 964 |
|
| 965 |
`MatcherCast` essentially lets you bypass C++'s type system (`static_cast` isn't |
| 966 |
always safe as it could throw away information, for example), so be careful not |
| 967 |
to misuse/abuse it. |
| 968 |
|
| 969 |
### Selecting Between Overloaded Functions {#SelectOverload} |
| 970 |
|
| 971 |
If you expect an overloaded function to be called, the compiler may need some |
| 972 |
help on which overloaded version it is. |
| 973 |
|
| 974 |
To disambiguate functions overloaded on the const-ness of this object, use the |
| 975 |
`Const()` argument wrapper. |
| 976 |
|
| 977 |
```cpp |
| 978 |
using ::testing::ReturnRef; |
| 979 |
|
| 980 |
class MockFoo : public Foo { |
| 981 |
... |
| 982 |
MOCK_METHOD(Bar&, GetBar, (), (override)); |
| 983 |
MOCK_METHOD(const Bar&, GetBar, (), (const, override)); |
| 984 |
}; |
| 985 |
|
| 986 |
... |
| 987 |
MockFoo foo; |
| 988 |
Bar bar1, bar2; |
| 989 |
EXPECT_CALL(foo, GetBar()) // The non-const GetBar(). |
| 990 |
.WillOnce(ReturnRef(bar1)); |
| 991 |
EXPECT_CALL(Const(foo), GetBar()) // The const GetBar(). |
| 992 |
.WillOnce(ReturnRef(bar2)); |
| 993 |
``` |
| 994 |
|
| 995 |
(`Const()` is defined by gMock and returns a `const` reference to its argument.) |
| 996 |
|
| 997 |
To disambiguate overloaded functions with the same number of arguments but |
| 998 |
different argument types, you may need to specify the exact type of a matcher, |
| 999 |
either by wrapping your matcher in `Matcher<type>()`, or using a matcher whose |
| 1000 |
type is fixed (`TypedEq<type>`, `An<type>()`, etc): |
| 1001 |
|
| 1002 |
```cpp |
| 1003 |
using ::testing::An; |
| 1004 |
using ::testing::Matcher; |
| 1005 |
using ::testing::TypedEq; |
| 1006 |
|
| 1007 |
class MockPrinter : public Printer { |
| 1008 |
public: |
| 1009 |
MOCK_METHOD(void, Print, (int n), (override)); |
| 1010 |
MOCK_METHOD(void, Print, (char c), (override)); |
| 1011 |
}; |
| 1012 |
|
| 1013 |
TEST(PrinterTest, Print) { |
| 1014 |
MockPrinter printer; |
| 1015 |
|
| 1016 |
EXPECT_CALL(printer, Print(An<int>())); // void Print(int); |
| 1017 |
EXPECT_CALL(printer, Print(Matcher<int>(Lt(5)))); // void Print(int); |
| 1018 |
EXPECT_CALL(printer, Print(TypedEq<char>('a'))); // void Print(char); |
| 1019 |
|
| 1020 |
printer.Print(3); |
| 1021 |
printer.Print(6); |
| 1022 |
printer.Print('a'); |
| 1023 |
} |
| 1024 |
``` |
| 1025 |
|
| 1026 |
### Performing Different Actions Based on the Arguments |
| 1027 |
|
| 1028 |
When a mock method is called, the *last* matching expectation that's still |
| 1029 |
active will be selected (think "newer overrides older"). So, you can make a |
| 1030 |
method do different things depending on its argument values like this: |
| 1031 |
|
| 1032 |
```cpp |
| 1033 |
using ::testing::_; |
| 1034 |
using ::testing::Lt; |
| 1035 |
using ::testing::Return; |
| 1036 |
... |
| 1037 |
// The default case. |
| 1038 |
EXPECT_CALL(foo, DoThis(_)) |
| 1039 |
.WillRepeatedly(Return('b')); |
| 1040 |
// The more specific case. |
| 1041 |
EXPECT_CALL(foo, DoThis(Lt(5))) |
| 1042 |
.WillRepeatedly(Return('a')); |
| 1043 |
``` |
| 1044 |
|
| 1045 |
Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will be |
| 1046 |
returned; otherwise `'b'` will be returned. |
| 1047 |
|
| 1048 |
### Matching Multiple Arguments as a Whole |
| 1049 |
|
| 1050 |
Sometimes it's not enough to match the arguments individually. For example, we |
| 1051 |
may want to say that the first argument must be less than the second argument. |
| 1052 |
The `With()` clause allows us to match all arguments of a mock function as a |
| 1053 |
whole. For example, |
| 1054 |
|
| 1055 |
```cpp |
| 1056 |
using ::testing::_; |
| 1057 |
using ::testing::Ne; |
| 1058 |
using ::testing::Lt; |
| 1059 |
... |
| 1060 |
EXPECT_CALL(foo, InRange(Ne(0), _)) |
| 1061 |
.With(Lt()); |
| 1062 |
``` |
| 1063 |
|
| 1064 |
says that the first argument of `InRange()` must not be 0, and must be less than |
| 1065 |
the second argument. |
| 1066 |
|
| 1067 |
The expression inside `With()` must be a matcher of type `Matcher<std::tuple<A1, |
| 1068 |
..., An>>`, where `A1`, ..., `An` are the types of the function arguments. |
| 1069 |
|
| 1070 |
You can also write `AllArgs(m)` instead of `m` inside `.With()`. The two forms |
| 1071 |
are equivalent, but `.With(AllArgs(Lt()))` is more readable than `.With(Lt())`. |
| 1072 |
|
| 1073 |
You can use `Args<k1, ..., kn>(m)` to match the `n` selected arguments (as a |
| 1074 |
tuple) against `m`. For example, |
| 1075 |
|
| 1076 |
```cpp |
| 1077 |
using ::testing::_; |
| 1078 |
using ::testing::AllOf; |
| 1079 |
using ::testing::Args; |
| 1080 |
using ::testing::Lt; |
| 1081 |
... |
| 1082 |
EXPECT_CALL(foo, Blah) |
| 1083 |
.With(AllOf(Args<0, 1>(Lt()), Args<1, 2>(Lt()))); |
| 1084 |
``` |
| 1085 |
|
| 1086 |
says that `Blah` will be called with arguments `x`, `y`, and `z` where `x < y < |
| 1087 |
z`. Note that in this example, it wasn't necessary to specify the positional |
| 1088 |
matchers. |
| 1089 |
|
| 1090 |
As a convenience and example, gMock provides some matchers for 2-tuples, |
| 1091 |
including the `Lt()` matcher above. See |
| 1092 |
[Multi-argument Matchers](reference/matchers.md#MultiArgMatchers) for the |
| 1093 |
complete list. |
| 1094 |
|
| 1095 |
Note that if you want to pass the arguments to a predicate of your own (e.g. |
| 1096 |
`.With(Args<0, 1>(Truly(&MyPredicate)))`), that predicate MUST be written to |
| 1097 |
take a `std::tuple` as its argument; gMock will pass the `n` selected arguments |
| 1098 |
as *one* single tuple to the predicate. |
| 1099 |
|
| 1100 |
### Using Matchers as Predicates |
| 1101 |
|
| 1102 |
Have you noticed that a matcher is just a fancy predicate that also knows how to |
| 1103 |
describe itself? Many existing algorithms take predicates as arguments (e.g. |
| 1104 |
those defined in STL's `<algorithm>` header), and it would be a shame if gMock |
| 1105 |
matchers were not allowed to participate. |
| 1106 |
|
| 1107 |
Luckily, you can use a matcher where a unary predicate functor is expected by |
| 1108 |
wrapping it inside the `Matches()` function. For example, |
| 1109 |
|
| 1110 |
```cpp |
| 1111 |
#include <algorithm> |
| 1112 |
#include <vector> |
| 1113 |
|
| 1114 |
using ::testing::Matches; |
| 1115 |
using ::testing::Ge; |
| 1116 |
|
| 1117 |
vector<int> v; |
| 1118 |
... |
| 1119 |
// How many elements in v are >= 10? |
| 1120 |
const int count = count_if(v.begin(), v.end(), Matches(Ge(10))); |
| 1121 |
``` |
| 1122 |
|
| 1123 |
Since you can build complex matchers from simpler ones easily using gMock, this |
| 1124 |
gives you a way to conveniently construct composite predicates (doing the same |
| 1125 |
using STL's `<functional>` header is just painful). For example, here's a |
| 1126 |
predicate that's satisfied by any number that is >= 0, <= 100, and != 50: |
| 1127 |
|
| 1128 |
```cpp |
| 1129 |
using testing::AllOf; |
| 1130 |
using testing::Ge; |
| 1131 |
using testing::Le; |
| 1132 |
using testing::Matches; |
| 1133 |
using testing::Ne; |
| 1134 |
... |
| 1135 |
Matches(AllOf(Ge(0), Le(100), Ne(50))) |
| 1136 |
``` |
| 1137 |
|
| 1138 |
### Using Matchers in googletest Assertions |
| 1139 |
|
| 1140 |
See [`EXPECT_THAT`](reference/assertions.md#EXPECT_THAT) in the Assertions |
| 1141 |
Reference. |
| 1142 |
|
| 1143 |
### Using Predicates as Matchers |
| 1144 |
|
| 1145 |
gMock provides a set of built-in matchers for matching arguments with expected |
| 1146 |
values—see the [Matchers Reference](reference/matchers.md) for more information. |
| 1147 |
In case you find the built-in set lacking, you can use an arbitrary unary |
| 1148 |
predicate function or functor as a matcher - as long as the predicate accepts a |
| 1149 |
value of the type you want. You do this by wrapping the predicate inside the |
| 1150 |
`Truly()` function, for example: |
| 1151 |
|
| 1152 |
```cpp |
| 1153 |
using ::testing::Truly; |
| 1154 |
|
| 1155 |
int IsEven(int n) { return (n % 2) == 0 ? 1 : 0; } |
| 1156 |
... |
| 1157 |
// Bar() must be called with an even number. |
| 1158 |
EXPECT_CALL(foo, Bar(Truly(IsEven))); |
| 1159 |
``` |
| 1160 |
|
| 1161 |
Note that the predicate function / functor doesn't have to return `bool`. It |
| 1162 |
works as long as the return value can be used as the condition in in statement |
| 1163 |
`if (condition) ...`. |
| 1164 |
|
| 1165 |
### Matching Arguments that Are Not Copyable |
| 1166 |
|
| 1167 |
When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of |
| 1168 |
`bar`. When `Foo()` is called later, gMock compares the argument to `Foo()` with |
| 1169 |
the saved copy of `bar`. This way, you don't need to worry about `bar` being |
| 1170 |
modified or destroyed after the `EXPECT_CALL()` is executed. The same is true |
| 1171 |
when you use matchers like `Eq(bar)`, `Le(bar)`, and so on. |
| 1172 |
|
| 1173 |
But what if `bar` cannot be copied (i.e. has no copy constructor)? You could |
| 1174 |
define your own matcher function or callback and use it with `Truly()`, as the |
| 1175 |
previous couple of recipes have shown. Or, you may be able to get away from it |
| 1176 |
if you can guarantee that `bar` won't be changed after the `EXPECT_CALL()` is |
| 1177 |
executed. Just tell gMock that it should save a reference to `bar`, instead of a |
| 1178 |
copy of it. Here's how: |
| 1179 |
|
| 1180 |
```cpp |
| 1181 |
using ::testing::Eq; |
| 1182 |
using ::testing::Lt; |
| 1183 |
... |
| 1184 |
// Expects that Foo()'s argument == bar. |
| 1185 |
EXPECT_CALL(mock_obj, Foo(Eq(std::ref(bar)))); |
| 1186 |
|
| 1187 |
// Expects that Foo()'s argument < bar. |
| 1188 |
EXPECT_CALL(mock_obj, Foo(Lt(std::ref(bar)))); |
| 1189 |
``` |
| 1190 |
|
| 1191 |
Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the |
| 1192 |
result is undefined. |
| 1193 |
|
| 1194 |
### Validating a Member of an Object |
| 1195 |
|
| 1196 |
Often a mock function takes a reference to object as an argument. When matching |
| 1197 |
the argument, you may not want to compare the entire object against a fixed |
| 1198 |
object, as that may be over-specification. Instead, you may need to validate a |
| 1199 |
certain member variable or the result of a certain getter method of the object. |
| 1200 |
You can do this with `Field()` and `Property()`. More specifically, |
| 1201 |
|
| 1202 |
```cpp |
| 1203 |
Field(&Foo::bar, m) |
| 1204 |
``` |
| 1205 |
|
| 1206 |
is a matcher that matches a `Foo` object whose `bar` member variable satisfies |
| 1207 |
matcher `m`. |
| 1208 |
|
| 1209 |
```cpp |
| 1210 |
Property(&Foo::baz, m) |
| 1211 |
``` |
| 1212 |
|
| 1213 |
is a matcher that matches a `Foo` object whose `baz()` method returns a value |
| 1214 |
that satisfies matcher `m`. |
| 1215 |
|
| 1216 |
For example: |
| 1217 |
|
| 1218 |
| Expression | Description | |
| 1219 |
| :--------------------------- | :--------------------------------------- | |
| 1220 |
| `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. | |
| 1221 |
| `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. | |
| 1222 |
|
| 1223 |
Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument |
| 1224 |
and be declared as `const`. Don't use `Property()` against member functions that |
| 1225 |
you do not own, because taking addresses of functions is fragile and generally |
| 1226 |
not part of the contract of the function. |
| 1227 |
|
| 1228 |
`Field()` and `Property()` can also match plain pointers to objects. For |
| 1229 |
instance, |
| 1230 |
|
| 1231 |
```cpp |
| 1232 |
using ::testing::Field; |
| 1233 |
using ::testing::Ge; |
| 1234 |
... |
| 1235 |
Field(&Foo::number, Ge(3)) |
| 1236 |
``` |
| 1237 |
|
| 1238 |
matches a plain pointer `p` where `p->number >= 3`. If `p` is `NULL`, the match |
| 1239 |
will always fail regardless of the inner matcher. |
| 1240 |
|
| 1241 |
What if you want to validate more than one members at the same time? Remember |
| 1242 |
that there are [`AllOf()` and `AllOfArray()`](#CombiningMatchers). |
| 1243 |
|
| 1244 |
Finally `Field()` and `Property()` provide overloads that take the field or |
| 1245 |
property names as the first argument to include it in the error message. This |
| 1246 |
can be useful when creating combined matchers. |
| 1247 |
|
| 1248 |
```cpp |
| 1249 |
using ::testing::AllOf; |
| 1250 |
using ::testing::Field; |
| 1251 |
using ::testing::Matcher; |
| 1252 |
using ::testing::SafeMatcherCast; |
| 1253 |
|
| 1254 |
Matcher<Foo> IsFoo(const Foo& foo) { |
| 1255 |
return AllOf(Field("some_field", &Foo::some_field, foo.some_field), |
| 1256 |
Field("other_field", &Foo::other_field, foo.other_field), |
| 1257 |
Field("last_field", &Foo::last_field, foo.last_field)); |
| 1258 |
} |
| 1259 |
``` |
| 1260 |
|
| 1261 |
### Validating the Value Pointed to by a Pointer Argument |
| 1262 |
|
| 1263 |
C++ functions often take pointers as arguments. You can use matchers like |
| 1264 |
`IsNull()`, `NotNull()`, and other comparison matchers to match a pointer, but |
| 1265 |
what if you want to make sure the value *pointed to* by the pointer, instead of |
| 1266 |
the pointer itself, has a certain property? Well, you can use the `Pointee(m)` |
| 1267 |
matcher. |
| 1268 |
|
| 1269 |
`Pointee(m)` matches a pointer if and only if `m` matches the value the pointer |
| 1270 |
points to. For example: |
| 1271 |
|
| 1272 |
```cpp |
| 1273 |
using ::testing::Ge; |
| 1274 |
using ::testing::Pointee; |
| 1275 |
... |
| 1276 |
EXPECT_CALL(foo, Bar(Pointee(Ge(3)))); |
| 1277 |
``` |
| 1278 |
|
| 1279 |
expects `foo.Bar()` to be called with a pointer that points to a value greater |
| 1280 |
than or equal to 3. |
| 1281 |
|
| 1282 |
One nice thing about `Pointee()` is that it treats a `NULL` pointer as a match |
| 1283 |
failure, so you can write `Pointee(m)` instead of |
| 1284 |
|
| 1285 |
```cpp |
| 1286 |
using ::testing::AllOf; |
| 1287 |
using ::testing::NotNull; |
| 1288 |
using ::testing::Pointee; |
| 1289 |
... |
| 1290 |
AllOf(NotNull(), Pointee(m)) |
| 1291 |
``` |
| 1292 |
|
| 1293 |
without worrying that a `NULL` pointer will crash your test. |
| 1294 |
|
| 1295 |
Also, did we tell you that `Pointee()` works with both raw pointers **and** |
| 1296 |
smart pointers (`std::unique_ptr`, `std::shared_ptr`, etc)? |
| 1297 |
|
| 1298 |
What if you have a pointer to pointer? You guessed it - you can use nested |
| 1299 |
`Pointee()` to probe deeper inside the value. For example, |
| 1300 |
`Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer that points |
| 1301 |
to a number less than 3 (what a mouthful...). |
| 1302 |
|
| 1303 |
### Testing a Certain Property of an Object |
| 1304 |
|
| 1305 |
Sometimes you want to specify that an object argument has a certain property, |
| 1306 |
but there is no existing matcher that does this. If you want good error |
| 1307 |
messages, you should [define a matcher](#NewMatchers). If you want to do it |
| 1308 |
quick and dirty, you could get away with writing an ordinary function. |
| 1309 |
|
| 1310 |
Let's say you have a mock function that takes an object of type `Foo`, which has |
| 1311 |
an `int bar()` method and an `int baz()` method, and you want to constrain that |
| 1312 |
the argument's `bar()` value plus its `baz()` value is a given number. Here's |
| 1313 |
how you can define a matcher to do it: |
| 1314 |
|
| 1315 |
```cpp |
| 1316 |
using ::testing::Matcher; |
| 1317 |
|
| 1318 |
class BarPlusBazEqMatcher { |
| 1319 |
public: |
| 1320 |
explicit BarPlusBazEqMatcher(int expected_sum) |
| 1321 |
: expected_sum_(expected_sum) {} |
| 1322 |
|
| 1323 |
bool MatchAndExplain(const Foo& foo, |
| 1324 |
std::ostream* /* listener */) const { |
| 1325 |
return (foo.bar() + foo.baz()) == expected_sum_; |
| 1326 |
} |
| 1327 |
|
| 1328 |
void DescribeTo(std::ostream& os) const { |
| 1329 |
os << "bar() + baz() equals " << expected_sum_; |
| 1330 |
} |
| 1331 |
|
| 1332 |
void DescribeNegationTo(std::ostream& os) const { |
| 1333 |
os << "bar() + baz() does not equal " << expected_sum_; |
| 1334 |
} |
| 1335 |
private: |
| 1336 |
const int expected_sum_; |
| 1337 |
}; |
| 1338 |
|
| 1339 |
Matcher<const Foo&> BarPlusBazEq(int expected_sum) { |
| 1340 |
return BarPlusBazEqMatcher(expected_sum); |
| 1341 |
} |
| 1342 |
|
| 1343 |
... |
| 1344 |
EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...; |
| 1345 |
``` |
| 1346 |
|
| 1347 |
### Matching Containers |
| 1348 |
|
| 1349 |
Sometimes an STL container (e.g. list, vector, map, ...) is passed to a mock |
| 1350 |
function and you may want to validate it. Since most STL containers support the |
| 1351 |
`==` operator, you can write `Eq(expected_container)` or simply |
| 1352 |
`expected_container` to match a container exactly. |
| 1353 |
|
| 1354 |
Sometimes, though, you may want to be more flexible (for example, the first |
| 1355 |
element must be an exact match, but the second element can be any positive |
| 1356 |
number, and so on). Also, containers used in tests often have a small number of |
| 1357 |
elements, and having to define the expected container out-of-line is a bit of a |
| 1358 |
hassle. |
| 1359 |
|
| 1360 |
You can use the `ElementsAre()` or `UnorderedElementsAre()` matcher in such |
| 1361 |
cases: |
| 1362 |
|
| 1363 |
```cpp |
| 1364 |
using ::testing::_; |
| 1365 |
using ::testing::ElementsAre; |
| 1366 |
using ::testing::Gt; |
| 1367 |
... |
| 1368 |
MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override)); |
| 1369 |
... |
| 1370 |
EXPECT_CALL(mock, Foo(ElementsAre(1, Gt(0), _, 5))); |
| 1371 |
``` |
| 1372 |
|
| 1373 |
The above matcher says that the container must have 4 elements, which must be 1, |
| 1374 |
greater than 0, anything, and 5 respectively. |
| 1375 |
|
| 1376 |
If you instead write: |
| 1377 |
|
| 1378 |
```cpp |
| 1379 |
using ::testing::_; |
| 1380 |
using ::testing::Gt; |
| 1381 |
using ::testing::UnorderedElementsAre; |
| 1382 |
... |
| 1383 |
MOCK_METHOD(void, Foo, (const vector<int>& numbers), (override)); |
| 1384 |
... |
| 1385 |
EXPECT_CALL(mock, Foo(UnorderedElementsAre(1, Gt(0), _, 5))); |
| 1386 |
``` |
| 1387 |
|
| 1388 |
It means that the container must have 4 elements, which (under some permutation) |
| 1389 |
must be 1, greater than 0, anything, and 5 respectively. |
| 1390 |
|
| 1391 |
As an alternative you can place the arguments in a C-style array and use |
| 1392 |
`ElementsAreArray()` or `UnorderedElementsAreArray()` instead: |
| 1393 |
|
| 1394 |
```cpp |
| 1395 |
using ::testing::ElementsAreArray; |
| 1396 |
... |
| 1397 |
// ElementsAreArray accepts an array of element values. |
| 1398 |
const int expected_vector1[] = {1, 5, 2, 4, ...}; |
| 1399 |
EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector1))); |
| 1400 |
|
| 1401 |
// Or, an array of element matchers. |
| 1402 |
Matcher<int> expected_vector2[] = {1, Gt(2), _, 3, ...}; |
| 1403 |
EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector2))); |
| 1404 |
``` |
| 1405 |
|
| 1406 |
In case the array needs to be dynamically created (and therefore the array size |
| 1407 |
cannot be inferred by the compiler), you can give `ElementsAreArray()` an |
| 1408 |
additional argument to specify the array size: |
| 1409 |
|
| 1410 |
```cpp |
| 1411 |
using ::testing::ElementsAreArray; |
| 1412 |
... |
| 1413 |
int* const expected_vector3 = new int[count]; |
| 1414 |
... fill expected_vector3 with values ... |
| 1415 |
EXPECT_CALL(mock, Foo(ElementsAreArray(expected_vector3, count))); |
| 1416 |
``` |
| 1417 |
|
| 1418 |
Use `Pair` when comparing maps or other associative containers. |
| 1419 |
|
| 1420 |
{% raw %} |
| 1421 |
|
| 1422 |
```cpp |
| 1423 |
using testing::ElementsAre; |
| 1424 |
using testing::Pair; |
| 1425 |
... |
| 1426 |
std::map<string, int> m = {{"a", 1}, {"b", 2}, {"c", 3}}; |
| 1427 |
EXPECT_THAT(m, ElementsAre(Pair("a", 1), Pair("b", 2), Pair("c", 3))); |
| 1428 |
``` |
| 1429 |
|
| 1430 |
{% endraw %} |
| 1431 |
|
| 1432 |
**Tips:** |
| 1433 |
|
| 1434 |
* `ElementsAre*()` can be used to match *any* container that implements the |
| 1435 |
STL iterator pattern (i.e. it has a `const_iterator` type and supports |
| 1436 |
`begin()/end()`), not just the ones defined in STL. It will even work with |
| 1437 |
container types yet to be written - as long as they follows the above |
| 1438 |
pattern. |
| 1439 |
* You can use nested `ElementsAre*()` to match nested (multi-dimensional) |
| 1440 |
containers. |
| 1441 |
* If the container is passed by pointer instead of by reference, just write |
| 1442 |
`Pointee(ElementsAre*(...))`. |
| 1443 |
* The order of elements *matters* for `ElementsAre*()`. If you are using it |
| 1444 |
with containers whose element order are undefined (e.g. `hash_map`) you |
| 1445 |
should use `WhenSorted` around `ElementsAre`. |
| 1446 |
|
| 1447 |
### Sharing Matchers |
| 1448 |
|
| 1449 |
Under the hood, a gMock matcher object consists of a pointer to a ref-counted |
| 1450 |
implementation object. Copying matchers is allowed and very efficient, as only |
| 1451 |
the pointer is copied. When the last matcher that references the implementation |
| 1452 |
object dies, the implementation object will be deleted. |
| 1453 |
|
| 1454 |
Therefore, if you have some complex matcher that you want to use again and |
| 1455 |
again, there is no need to build it every time. Just assign it to a matcher |
| 1456 |
variable and use that variable repeatedly! For example, |
| 1457 |
|
| 1458 |
```cpp |
| 1459 |
using ::testing::AllOf; |
| 1460 |
using ::testing::Gt; |
| 1461 |
using ::testing::Le; |
| 1462 |
using ::testing::Matcher; |
| 1463 |
... |
| 1464 |
Matcher<int> in_range = AllOf(Gt(5), Le(10)); |
| 1465 |
... use in_range as a matcher in multiple EXPECT_CALLs ... |
| 1466 |
``` |
| 1467 |
|
| 1468 |
### Matchers must have no side-effects {#PureMatchers} |
| 1469 |
|
| 1470 |
{: .callout .warning} |
| 1471 |
WARNING: gMock does not guarantee when or how many times a matcher will be |
| 1472 |
invoked. Therefore, all matchers must be *purely functional*: they cannot have |
| 1473 |
any side effects, and the match result must not depend on anything other than |
| 1474 |
the matcher's parameters and the value being matched. |
| 1475 |
|
| 1476 |
This requirement must be satisfied no matter how a matcher is defined (e.g., if |
| 1477 |
it is one of the standard matchers, or a custom matcher). In particular, a |
| 1478 |
matcher can never call a mock function, as that will affect the state of the |
| 1479 |
mock object and gMock. |
| 1480 |
|
| 1481 |
## Setting Expectations |
| 1482 |
|
| 1483 |
### Knowing When to Expect {#UseOnCall} |
| 1484 |
|
| 1485 |
**`ON_CALL`** is likely the *single most under-utilized construct* in gMock. |
| 1486 |
|
| 1487 |
There are basically two constructs for defining the behavior of a mock object: |
| 1488 |
`ON_CALL` and `EXPECT_CALL`. The difference? `ON_CALL` defines what happens when |
| 1489 |
a mock method is called, but <em>doesn't imply any expectation on the method |
| 1490 |
being called</em>. `EXPECT_CALL` not only defines the behavior, but also sets an |
| 1491 |
expectation that <em>the method will be called with the given arguments, for the |
| 1492 |
given number of times</em> (and *in the given order* when you specify the order |
| 1493 |
too). |
| 1494 |
|
| 1495 |
Since `EXPECT_CALL` does more, isn't it better than `ON_CALL`? Not really. Every |
| 1496 |
`EXPECT_CALL` adds a constraint on the behavior of the code under test. Having |
| 1497 |
more constraints than necessary is *baaad* - even worse than not having enough |
| 1498 |
constraints. |
| 1499 |
|
| 1500 |
This may be counter-intuitive. How could tests that verify more be worse than |
| 1501 |
tests that verify less? Isn't verification the whole point of tests? |
| 1502 |
|
| 1503 |
The answer lies in *what* a test should verify. **A good test verifies the |
| 1504 |
contract of the code.** If a test over-specifies, it doesn't leave enough |
| 1505 |
freedom to the implementation. As a result, changing the implementation without |
| 1506 |
breaking the contract (e.g. refactoring and optimization), which should be |
| 1507 |
perfectly fine to do, can break such tests. Then you have to spend time fixing |
| 1508 |
them, only to see them broken again the next time the implementation is changed. |
| 1509 |
|
| 1510 |
Keep in mind that one doesn't have to verify more than one property in one test. |
| 1511 |
In fact, **it's a good style to verify only one thing in one test.** If you do |
| 1512 |
that, a bug will likely break only one or two tests instead of dozens (which |
| 1513 |
case would you rather debug?). If you are also in the habit of giving tests |
| 1514 |
descriptive names that tell what they verify, you can often easily guess what's |
| 1515 |
wrong just from the test log itself. |
| 1516 |
|
| 1517 |
So use `ON_CALL` by default, and only use `EXPECT_CALL` when you actually intend |
| 1518 |
to verify that the call is made. For example, you may have a bunch of `ON_CALL`s |
| 1519 |
in your test fixture to set the common mock behavior shared by all tests in the |
| 1520 |
same group, and write (scarcely) different `EXPECT_CALL`s in different `TEST_F`s |
| 1521 |
to verify different aspects of the code's behavior. Compared with the style |
| 1522 |
where each `TEST` has many `EXPECT_CALL`s, this leads to tests that are more |
| 1523 |
resilient to implementational changes (and thus less likely to require |
| 1524 |
maintenance) and makes the intent of the tests more obvious (so they are easier |
| 1525 |
to maintain when you do need to maintain them). |
| 1526 |
|
| 1527 |
If you are bothered by the "Uninteresting mock function call" message printed |
| 1528 |
when a mock method without an `EXPECT_CALL` is called, you may use a `NiceMock` |
| 1529 |
instead to suppress all such messages for the mock object, or suppress the |
| 1530 |
message for specific methods by adding `EXPECT_CALL(...).Times(AnyNumber())`. DO |
| 1531 |
NOT suppress it by blindly adding an `EXPECT_CALL(...)`, or you'll have a test |
| 1532 |
that's a pain to maintain. |
| 1533 |
|
| 1534 |
### Ignoring Uninteresting Calls |
| 1535 |
|
| 1536 |
If you are not interested in how a mock method is called, just don't say |
| 1537 |
anything about it. In this case, if the method is ever called, gMock will |
| 1538 |
perform its default action to allow the test program to continue. If you are not |
| 1539 |
happy with the default action taken by gMock, you can override it using |
| 1540 |
`DefaultValue<T>::Set()` (described [here](#DefaultValue)) or `ON_CALL()`. |
| 1541 |
|
| 1542 |
Please note that once you expressed interest in a particular mock method (via |
| 1543 |
`EXPECT_CALL()`), all invocations to it must match some expectation. If this |
| 1544 |
function is called but the arguments don't match any `EXPECT_CALL()` statement, |
| 1545 |
it will be an error. |
| 1546 |
|
| 1547 |
### Disallowing Unexpected Calls |
| 1548 |
|
| 1549 |
If a mock method shouldn't be called at all, explicitly say so: |
| 1550 |
|
| 1551 |
```cpp |
| 1552 |
using ::testing::_; |
| 1553 |
... |
| 1554 |
EXPECT_CALL(foo, Bar(_)) |
| 1555 |
.Times(0); |
| 1556 |
``` |
| 1557 |
|
| 1558 |
If some calls to the method are allowed, but the rest are not, just list all the |
| 1559 |
expected calls: |
| 1560 |
|
| 1561 |
```cpp |
| 1562 |
using ::testing::AnyNumber; |
| 1563 |
using ::testing::Gt; |
| 1564 |
... |
| 1565 |
EXPECT_CALL(foo, Bar(5)); |
| 1566 |
EXPECT_CALL(foo, Bar(Gt(10))) |
| 1567 |
.Times(AnyNumber()); |
| 1568 |
``` |
| 1569 |
|
| 1570 |
A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` statements |
| 1571 |
will be an error. |
| 1572 |
|
| 1573 |
### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected} |
| 1574 |
|
| 1575 |
*Uninteresting* calls and *unexpected* calls are different concepts in gMock. |
| 1576 |
*Very* different. |
| 1577 |
|
| 1578 |
A call `x.Y(...)` is **uninteresting** if there's *not even a single* |
| 1579 |
`EXPECT_CALL(x, Y(...))` set. In other words, the test isn't interested in the |
| 1580 |
`x.Y()` method at all, as evident in that the test doesn't care to say anything |
| 1581 |
about it. |
| 1582 |
|
| 1583 |
A call `x.Y(...)` is **unexpected** if there are *some* `EXPECT_CALL(x, |
| 1584 |
Y(...))`s set, but none of them matches the call. Put another way, the test is |
| 1585 |
interested in the `x.Y()` method (therefore it explicitly sets some |
| 1586 |
`EXPECT_CALL` to verify how it's called); however, the verification fails as the |
| 1587 |
test doesn't expect this particular call to happen. |
| 1588 |
|
| 1589 |
**An unexpected call is always an error,** as the code under test doesn't behave |
| 1590 |
the way the test expects it to behave. |
| 1591 |
|
| 1592 |
**By default, an uninteresting call is not an error,** as it violates no |
| 1593 |
constraint specified by the test. (gMock's philosophy is that saying nothing |
| 1594 |
means there is no constraint.) However, it leads to a warning, as it *might* |
| 1595 |
indicate a problem (e.g. the test author might have forgotten to specify a |
| 1596 |
constraint). |
| 1597 |
|
| 1598 |
In gMock, `NiceMock` and `StrictMock` can be used to make a mock class "nice" or |
| 1599 |
"strict". How does this affect uninteresting calls and unexpected calls? |
| 1600 |
|
| 1601 |
A **nice mock** suppresses uninteresting call *warnings*. It is less chatty than |
| 1602 |
the default mock, but otherwise is the same. If a test fails with a default |
| 1603 |
mock, it will also fail using a nice mock instead. And vice versa. Don't expect |
| 1604 |
making a mock nice to change the test's result. |
| 1605 |
|
| 1606 |
A **strict mock** turns uninteresting call warnings into errors. So making a |
| 1607 |
mock strict may change the test's result. |
| 1608 |
|
| 1609 |
Let's look at an example: |
| 1610 |
|
| 1611 |
```cpp |
| 1612 |
TEST(...) { |
| 1613 |
NiceMock<MockDomainRegistry> mock_registry; |
| 1614 |
EXPECT_CALL(mock_registry, GetDomainOwner("google.com")) |
| 1615 |
.WillRepeatedly(Return("Larry Page")); |
| 1616 |
|
| 1617 |
// Use mock_registry in code under test. |
| 1618 |
... &mock_registry ... |
| 1619 |
} |
| 1620 |
``` |
| 1621 |
|
| 1622 |
The sole `EXPECT_CALL` here says that all calls to `GetDomainOwner()` must have |
| 1623 |
`"google.com"` as the argument. If `GetDomainOwner("yahoo.com")` is called, it |
| 1624 |
will be an unexpected call, and thus an error. *Having a nice mock doesn't |
| 1625 |
change the severity of an unexpected call.* |
| 1626 |
|
| 1627 |
So how do we tell gMock that `GetDomainOwner()` can be called with some other |
| 1628 |
arguments as well? The standard technique is to add a "catch all" `EXPECT_CALL`: |
| 1629 |
|
| 1630 |
```cpp |
| 1631 |
EXPECT_CALL(mock_registry, GetDomainOwner(_)) |
| 1632 |
.Times(AnyNumber()); // catches all other calls to this method. |
| 1633 |
EXPECT_CALL(mock_registry, GetDomainOwner("google.com")) |
| 1634 |
.WillRepeatedly(Return("Larry Page")); |
| 1635 |
``` |
| 1636 |
|
| 1637 |
Remember that `_` is the wildcard matcher that matches anything. With this, if |
| 1638 |
`GetDomainOwner("google.com")` is called, it will do what the second |
| 1639 |
`EXPECT_CALL` says; if it is called with a different argument, it will do what |
| 1640 |
the first `EXPECT_CALL` says. |
| 1641 |
|
| 1642 |
Note that the order of the two `EXPECT_CALL`s is important, as a newer |
| 1643 |
`EXPECT_CALL` takes precedence over an older one. |
| 1644 |
|
| 1645 |
For more on uninteresting calls, nice mocks, and strict mocks, read |
| 1646 |
["The Nice, the Strict, and the Naggy"](#NiceStrictNaggy). |
| 1647 |
|
| 1648 |
### Ignoring Uninteresting Arguments {#ParameterlessExpectations} |
| 1649 |
|
| 1650 |
If your test doesn't care about the parameters (it only cares about the number |
| 1651 |
or order of calls), you can often simply omit the parameter list: |
| 1652 |
|
| 1653 |
```cpp |
| 1654 |
// Expect foo.Bar( ... ) twice with any arguments. |
| 1655 |
EXPECT_CALL(foo, Bar).Times(2); |
| 1656 |
|
| 1657 |
// Delegate to the given method whenever the factory is invoked. |
| 1658 |
ON_CALL(foo_factory, MakeFoo) |
| 1659 |
.WillByDefault(&BuildFooForTest); |
| 1660 |
``` |
| 1661 |
|
| 1662 |
This functionality is only available when a method is not overloaded; to prevent |
| 1663 |
unexpected behavior it is a compilation error to try to set an expectation on a |
| 1664 |
method where the specific overload is ambiguous. You can work around this by |
| 1665 |
supplying a [simpler mock interface](#SimplerInterfaces) than the mocked class |
| 1666 |
provides. |
| 1667 |
|
| 1668 |
This pattern is also useful when the arguments are interesting, but match logic |
| 1669 |
is substantially complex. You can leave the argument list unspecified and use |
| 1670 |
SaveArg actions to [save the values for later verification](#SaveArgVerify). If |
| 1671 |
you do that, you can easily differentiate calling the method the wrong number of |
| 1672 |
times from calling it with the wrong arguments. |
| 1673 |
|
| 1674 |
### Expecting Ordered Calls {#OrderedCalls} |
| 1675 |
|
| 1676 |
Although an `EXPECT_CALL()` statement defined later takes precedence when gMock |
| 1677 |
tries to match a function call with an expectation, by default calls don't have |
| 1678 |
to happen in the order `EXPECT_CALL()` statements are written. For example, if |
| 1679 |
the arguments match the matchers in the second `EXPECT_CALL()`, but not those in |
| 1680 |
the first and third, then the second expectation will be used. |
| 1681 |
|
| 1682 |
If you would rather have all calls occur in the order of the expectations, put |
| 1683 |
the `EXPECT_CALL()` statements in a block where you define a variable of type |
| 1684 |
`InSequence`: |
| 1685 |
|
| 1686 |
```cpp |
| 1687 |
using ::testing::_; |
| 1688 |
using ::testing::InSequence; |
| 1689 |
|
| 1690 |
{ |
| 1691 |
InSequence s; |
| 1692 |
|
| 1693 |
EXPECT_CALL(foo, DoThis(5)); |
| 1694 |
EXPECT_CALL(bar, DoThat(_)) |
| 1695 |
.Times(2); |
| 1696 |
EXPECT_CALL(foo, DoThis(6)); |
| 1697 |
} |
| 1698 |
``` |
| 1699 |
|
| 1700 |
In this example, we expect a call to `foo.DoThis(5)`, followed by two calls to |
| 1701 |
`bar.DoThat()` where the argument can be anything, which are in turn followed by |
| 1702 |
a call to `foo.DoThis(6)`. If a call occurred out-of-order, gMock will report an |
| 1703 |
error. |
| 1704 |
|
| 1705 |
### Expecting Partially Ordered Calls {#PartialOrder} |
| 1706 |
|
| 1707 |
Sometimes requiring everything to occur in a predetermined order can lead to |
| 1708 |
brittle tests. For example, we may care about `A` occurring before both `B` and |
| 1709 |
`C`, but aren't interested in the relative order of `B` and `C`. In this case, |
| 1710 |
the test should reflect our real intent, instead of being overly constraining. |
| 1711 |
|
| 1712 |
gMock allows you to impose an arbitrary DAG (directed acyclic graph) on the |
| 1713 |
calls. One way to express the DAG is to use the |
| 1714 |
[`After` clause](reference/mocking.md#EXPECT_CALL.After) of `EXPECT_CALL`. |
| 1715 |
|
| 1716 |
Another way is via the `InSequence()` clause (not the same as the `InSequence` |
| 1717 |
class), which we borrowed from jMock 2. It's less flexible than `After()`, but |
| 1718 |
more convenient when you have long chains of sequential calls, as it doesn't |
| 1719 |
require you to come up with different names for the expectations in the chains. |
| 1720 |
Here's how it works: |
| 1721 |
|
| 1722 |
If we view `EXPECT_CALL()` statements as nodes in a graph, and add an edge from |
| 1723 |
node A to node B wherever A must occur before B, we can get a DAG. We use the |
| 1724 |
term "sequence" to mean a directed path in this DAG. Now, if we decompose the |
| 1725 |
DAG into sequences, we just need to know which sequences each `EXPECT_CALL()` |
| 1726 |
belongs to in order to be able to reconstruct the original DAG. |
| 1727 |
|
| 1728 |
So, to specify the partial order on the expectations we need to do two things: |
| 1729 |
first to define some `Sequence` objects, and then for each `EXPECT_CALL()` say |
| 1730 |
which `Sequence` objects it is part of. |
| 1731 |
|
| 1732 |
Expectations in the same sequence must occur in the order they are written. For |
| 1733 |
example, |
| 1734 |
|
| 1735 |
```cpp |
| 1736 |
using ::testing::Sequence; |
| 1737 |
... |
| 1738 |
Sequence s1, s2; |
| 1739 |
|
| 1740 |
EXPECT_CALL(foo, A()) |
| 1741 |
.InSequence(s1, s2); |
| 1742 |
EXPECT_CALL(bar, B()) |
| 1743 |
.InSequence(s1); |
| 1744 |
EXPECT_CALL(bar, C()) |
| 1745 |
.InSequence(s2); |
| 1746 |
EXPECT_CALL(foo, D()) |
| 1747 |
.InSequence(s2); |
| 1748 |
``` |
| 1749 |
|
| 1750 |
specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> C -> D`): |
| 1751 |
|
| 1752 |
```text |
| 1753 |
+---> B |
| 1754 |
| |
| 1755 |
A ---| |
| 1756 |
| |
| 1757 |
+---> C ---> D |
| 1758 |
``` |
| 1759 |
|
| 1760 |
This means that A must occur before B and C, and C must occur before D. There's |
| 1761 |
no restriction about the order other than these. |
| 1762 |
|
| 1763 |
### Controlling When an Expectation Retires |
| 1764 |
|
| 1765 |
When a mock method is called, gMock only considers expectations that are still |
| 1766 |
active. An expectation is active when created, and becomes inactive (aka |
| 1767 |
*retires*) when a call that has to occur later has occurred. For example, in |
| 1768 |
|
| 1769 |
```cpp |
| 1770 |
using ::testing::_; |
| 1771 |
using ::testing::Sequence; |
| 1772 |
... |
| 1773 |
Sequence s1, s2; |
| 1774 |
|
| 1775 |
EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #1 |
| 1776 |
.Times(AnyNumber()) |
| 1777 |
.InSequence(s1, s2); |
| 1778 |
EXPECT_CALL(log, Log(WARNING, _, "Data set is empty.")) // #2 |
| 1779 |
.InSequence(s1); |
| 1780 |
EXPECT_CALL(log, Log(WARNING, _, "User not found.")) // #3 |
| 1781 |
.InSequence(s2); |
| 1782 |
``` |
| 1783 |
|
| 1784 |
as soon as either #2 or #3 is matched, #1 will retire. If a warning `"File too |
| 1785 |
large."` is logged after this, it will be an error. |
| 1786 |
|
| 1787 |
Note that an expectation doesn't retire automatically when it's saturated. For |
| 1788 |
example, |
| 1789 |
|
| 1790 |
```cpp |
| 1791 |
using ::testing::_; |
| 1792 |
... |
| 1793 |
EXPECT_CALL(log, Log(WARNING, _, _)); // #1 |
| 1794 |
EXPECT_CALL(log, Log(WARNING, _, "File too large.")); // #2 |
| 1795 |
``` |
| 1796 |
|
| 1797 |
says that there will be exactly one warning with the message `"File too |
| 1798 |
large."`. If the second warning contains this message too, #2 will match again |
| 1799 |
and result in an upper-bound-violated error. |
| 1800 |
|
| 1801 |
If this is not what you want, you can ask an expectation to retire as soon as it |
| 1802 |
becomes saturated: |
| 1803 |
|
| 1804 |
```cpp |
| 1805 |
using ::testing::_; |
| 1806 |
... |
| 1807 |
EXPECT_CALL(log, Log(WARNING, _, _)); // #1 |
| 1808 |
EXPECT_CALL(log, Log(WARNING, _, "File too large.")) // #2 |
| 1809 |
.RetiresOnSaturation(); |
| 1810 |
``` |
| 1811 |
|
| 1812 |
Here #2 can be used only once, so if you have two warnings with the message |
| 1813 |
`"File too large."`, the first will match #2 and the second will match #1 - |
| 1814 |
there will be no error. |
| 1815 |
|
| 1816 |
## Using Actions |
| 1817 |
|
| 1818 |
### Returning References from Mock Methods |
| 1819 |
|
| 1820 |
If a mock function's return type is a reference, you need to use `ReturnRef()` |
| 1821 |
instead of `Return()` to return a result: |
| 1822 |
|
| 1823 |
```cpp |
| 1824 |
using ::testing::ReturnRef; |
| 1825 |
|
| 1826 |
class MockFoo : public Foo { |
| 1827 |
public: |
| 1828 |
MOCK_METHOD(Bar&, GetBar, (), (override)); |
| 1829 |
}; |
| 1830 |
... |
| 1831 |
MockFoo foo; |
| 1832 |
Bar bar; |
| 1833 |
EXPECT_CALL(foo, GetBar()) |
| 1834 |
.WillOnce(ReturnRef(bar)); |
| 1835 |
... |
| 1836 |
``` |
| 1837 |
|
| 1838 |
### Returning Live Values from Mock Methods |
| 1839 |
|
| 1840 |
The `Return(x)` action saves a copy of `x` when the action is created, and |
| 1841 |
always returns the same value whenever it's executed. Sometimes you may want to |
| 1842 |
instead return the *live* value of `x` (i.e. its value at the time when the |
| 1843 |
action is *executed*.). Use either `ReturnRef()` or `ReturnPointee()` for this |
| 1844 |
purpose. |
| 1845 |
|
| 1846 |
If the mock function's return type is a reference, you can do it using |
| 1847 |
`ReturnRef(x)`, as shown in the previous recipe ("Returning References from Mock |
| 1848 |
Methods"). However, gMock doesn't let you use `ReturnRef()` in a mock function |
| 1849 |
whose return type is not a reference, as doing that usually indicates a user |
| 1850 |
error. So, what shall you do? |
| 1851 |
|
| 1852 |
Though you may be tempted, DO NOT use `std::ref()`: |
| 1853 |
|
| 1854 |
```cpp |
| 1855 |
using testing::Return; |
| 1856 |
|
| 1857 |
class MockFoo : public Foo { |
| 1858 |
public: |
| 1859 |
MOCK_METHOD(int, GetValue, (), (override)); |
| 1860 |
}; |
| 1861 |
... |
| 1862 |
int x = 0; |
| 1863 |
MockFoo foo; |
| 1864 |
EXPECT_CALL(foo, GetValue()) |
| 1865 |
.WillRepeatedly(Return(std::ref(x))); // Wrong! |
| 1866 |
x = 42; |
| 1867 |
EXPECT_EQ(42, foo.GetValue()); |
| 1868 |
``` |
| 1869 |
|
| 1870 |
Unfortunately, it doesn't work here. The above code will fail with error: |
| 1871 |
|
| 1872 |
```text |
| 1873 |
Value of: foo.GetValue() |
| 1874 |
Actual: 0 |
| 1875 |
Expected: 42 |
| 1876 |
``` |
| 1877 |
|
| 1878 |
The reason is that `Return(*value*)` converts `value` to the actual return type |
| 1879 |
of the mock function at the time when the action is *created*, not when it is |
| 1880 |
*executed*. (This behavior was chosen for the action to be safe when `value` is |
| 1881 |
a proxy object that references some temporary objects.) As a result, |
| 1882 |
`std::ref(x)` is converted to an `int` value (instead of a `const int&`) when |
| 1883 |
the expectation is set, and `Return(std::ref(x))` will always return 0. |
| 1884 |
|
| 1885 |
`ReturnPointee(pointer)` was provided to solve this problem specifically. It |
| 1886 |
returns the value pointed to by `pointer` at the time the action is *executed*: |
| 1887 |
|
| 1888 |
```cpp |
| 1889 |
using testing::ReturnPointee; |
| 1890 |
... |
| 1891 |
int x = 0; |
| 1892 |
MockFoo foo; |
| 1893 |
EXPECT_CALL(foo, GetValue()) |
| 1894 |
.WillRepeatedly(ReturnPointee(&x)); // Note the & here. |
| 1895 |
x = 42; |
| 1896 |
EXPECT_EQ(42, foo.GetValue()); // This will succeed now. |
| 1897 |
``` |
| 1898 |
|
| 1899 |
### Combining Actions |
| 1900 |
|
| 1901 |
Want to do more than one thing when a function is called? That's fine. `DoAll()` |
| 1902 |
allow you to do sequence of actions every time. Only the return value of the |
| 1903 |
last action in the sequence will be used. |
| 1904 |
|
| 1905 |
```cpp |
| 1906 |
using ::testing::_; |
| 1907 |
using ::testing::DoAll; |
| 1908 |
|
| 1909 |
class MockFoo : public Foo { |
| 1910 |
public: |
| 1911 |
MOCK_METHOD(bool, Bar, (int n), (override)); |
| 1912 |
}; |
| 1913 |
... |
| 1914 |
EXPECT_CALL(foo, Bar(_)) |
| 1915 |
.WillOnce(DoAll(action_1, |
| 1916 |
action_2, |
| 1917 |
... |
| 1918 |
action_n)); |
| 1919 |
``` |
| 1920 |
|
| 1921 |
### Verifying Complex Arguments {#SaveArgVerify} |
| 1922 |
|
| 1923 |
If you want to verify that a method is called with a particular argument but the |
| 1924 |
match criteria is complex, it can be difficult to distinguish between |
| 1925 |
cardinality failures (calling the method the wrong number of times) and argument |
| 1926 |
match failures. Similarly, if you are matching multiple parameters, it may not |
| 1927 |
be easy to distinguishing which argument failed to match. For example: |
| 1928 |
|
| 1929 |
```cpp |
| 1930 |
// Not ideal: this could fail because of a problem with arg1 or arg2, or maybe |
| 1931 |
// just the method wasn't called. |
| 1932 |
EXPECT_CALL(foo, SendValues(_, ElementsAre(1, 4, 4, 7), EqualsProto( ... ))); |
| 1933 |
``` |
| 1934 |
|
| 1935 |
You can instead save the arguments and test them individually: |
| 1936 |
|
| 1937 |
```cpp |
| 1938 |
EXPECT_CALL(foo, SendValues) |
| 1939 |
.WillOnce(DoAll(SaveArg<1>(&actual_array), SaveArg<2>(&actual_proto))); |
| 1940 |
... run the test |
| 1941 |
EXPECT_THAT(actual_array, ElementsAre(1, 4, 4, 7)); |
| 1942 |
EXPECT_THAT(actual_proto, EqualsProto( ... )); |
| 1943 |
``` |
| 1944 |
|
| 1945 |
### Mocking Side Effects {#MockingSideEffects} |
| 1946 |
|
| 1947 |
Sometimes a method exhibits its effect not via returning a value but via side |
| 1948 |
effects. For example, it may change some global state or modify an output |
| 1949 |
argument. To mock side effects, in general you can define your own action by |
| 1950 |
implementing `::testing::ActionInterface`. |
| 1951 |
|
| 1952 |
If all you need to do is to change an output argument, the built-in |
| 1953 |
`SetArgPointee()` action is convenient: |
| 1954 |
|
| 1955 |
```cpp |
| 1956 |
using ::testing::_; |
| 1957 |
using ::testing::SetArgPointee; |
| 1958 |
|
| 1959 |
class MockMutator : public Mutator { |
| 1960 |
public: |
| 1961 |
MOCK_METHOD(void, Mutate, (bool mutate, int* value), (override)); |
| 1962 |
... |
| 1963 |
} |
| 1964 |
... |
| 1965 |
MockMutator mutator; |
| 1966 |
EXPECT_CALL(mutator, Mutate(true, _)) |
| 1967 |
.WillOnce(SetArgPointee<1>(5)); |
| 1968 |
``` |
| 1969 |
|
| 1970 |
In this example, when `mutator.Mutate()` is called, we will assign 5 to the |
| 1971 |
`int` variable pointed to by argument #1 (0-based). |
| 1972 |
|
| 1973 |
`SetArgPointee()` conveniently makes an internal copy of the value you pass to |
| 1974 |
it, removing the need to keep the value in scope and alive. The implication |
| 1975 |
however is that the value must have a copy constructor and assignment operator. |
| 1976 |
|
| 1977 |
If the mock method also needs to return a value as well, you can chain |
| 1978 |
`SetArgPointee()` with `Return()` using `DoAll()`, remembering to put the |
| 1979 |
`Return()` statement last: |
| 1980 |
|
| 1981 |
```cpp |
| 1982 |
using ::testing::_; |
| 1983 |
using ::testing::DoAll; |
| 1984 |
using ::testing::Return; |
| 1985 |
using ::testing::SetArgPointee; |
| 1986 |
|
| 1987 |
class MockMutator : public Mutator { |
| 1988 |
public: |
| 1989 |
... |
| 1990 |
MOCK_METHOD(bool, MutateInt, (int* value), (override)); |
| 1991 |
} |
| 1992 |
... |
| 1993 |
MockMutator mutator; |
| 1994 |
EXPECT_CALL(mutator, MutateInt(_)) |
| 1995 |
.WillOnce(DoAll(SetArgPointee<0>(5), |
| 1996 |
Return(true))); |
| 1997 |
``` |
| 1998 |
|
| 1999 |
Note, however, that if you use the `ReturnOKWith()` method, it will override the |
| 2000 |
values provided by `SetArgPointee()` in the response parameters of your function |
| 2001 |
call. |
| 2002 |
|
| 2003 |
If the output argument is an array, use the `SetArrayArgument<N>(first, last)` |
| 2004 |
action instead. It copies the elements in source range `[first, last)` to the |
| 2005 |
array pointed to by the `N`-th (0-based) argument: |
| 2006 |
|
| 2007 |
```cpp |
| 2008 |
using ::testing::NotNull; |
| 2009 |
using ::testing::SetArrayArgument; |
| 2010 |
|
| 2011 |
class MockArrayMutator : public ArrayMutator { |
| 2012 |
public: |
| 2013 |
MOCK_METHOD(void, Mutate, (int* values, int num_values), (override)); |
| 2014 |
... |
| 2015 |
} |
| 2016 |
... |
| 2017 |
MockArrayMutator mutator; |
| 2018 |
int values[5] = {1, 2, 3, 4, 5}; |
| 2019 |
EXPECT_CALL(mutator, Mutate(NotNull(), 5)) |
| 2020 |
.WillOnce(SetArrayArgument<0>(values, values + 5)); |
| 2021 |
``` |
| 2022 |
|
| 2023 |
This also works when the argument is an output iterator: |
| 2024 |
|
| 2025 |
```cpp |
| 2026 |
using ::testing::_; |
| 2027 |
using ::testing::SetArrayArgument; |
| 2028 |
|
| 2029 |
class MockRolodex : public Rolodex { |
| 2030 |
public: |
| 2031 |
MOCK_METHOD(void, GetNames, (std::back_insert_iterator<vector<string>>), |
| 2032 |
(override)); |
| 2033 |
... |
| 2034 |
} |
| 2035 |
... |
| 2036 |
MockRolodex rolodex; |
| 2037 |
vector<string> names = {"George", "John", "Thomas"}; |
| 2038 |
EXPECT_CALL(rolodex, GetNames(_)) |
| 2039 |
.WillOnce(SetArrayArgument<0>(names.begin(), names.end())); |
| 2040 |
``` |
| 2041 |
|
| 2042 |
### Changing a Mock Object's Behavior Based on the State |
| 2043 |
|
| 2044 |
If you expect a call to change the behavior of a mock object, you can use |
| 2045 |
`::testing::InSequence` to specify different behaviors before and after the |
| 2046 |
call: |
| 2047 |
|
| 2048 |
```cpp |
| 2049 |
using ::testing::InSequence; |
| 2050 |
using ::testing::Return; |
| 2051 |
|
| 2052 |
... |
| 2053 |
{ |
| 2054 |
InSequence seq; |
| 2055 |
EXPECT_CALL(my_mock, IsDirty()) |
| 2056 |
.WillRepeatedly(Return(true)); |
| 2057 |
EXPECT_CALL(my_mock, Flush()); |
| 2058 |
EXPECT_CALL(my_mock, IsDirty()) |
| 2059 |
.WillRepeatedly(Return(false)); |
| 2060 |
} |
| 2061 |
my_mock.FlushIfDirty(); |
| 2062 |
``` |
| 2063 |
|
| 2064 |
This makes `my_mock.IsDirty()` return `true` before `my_mock.Flush()` is called |
| 2065 |
and return `false` afterwards. |
| 2066 |
|
| 2067 |
If the behavior change is more complex, you can store the effects in a variable |
| 2068 |
and make a mock method get its return value from that variable: |
| 2069 |
|
| 2070 |
```cpp |
| 2071 |
using ::testing::_; |
| 2072 |
using ::testing::SaveArg; |
| 2073 |
using ::testing::Return; |
| 2074 |
|
| 2075 |
ACTION_P(ReturnPointee, p) { return *p; } |
| 2076 |
... |
| 2077 |
int previous_value = 0; |
| 2078 |
EXPECT_CALL(my_mock, GetPrevValue) |
| 2079 |
.WillRepeatedly(ReturnPointee(&previous_value)); |
| 2080 |
EXPECT_CALL(my_mock, UpdateValue) |
| 2081 |
.WillRepeatedly(SaveArg<0>(&previous_value)); |
| 2082 |
my_mock.DoSomethingToUpdateValue(); |
| 2083 |
``` |
| 2084 |
|
| 2085 |
Here `my_mock.GetPrevValue()` will always return the argument of the last |
| 2086 |
`UpdateValue()` call. |
| 2087 |
|
| 2088 |
### Setting the Default Value for a Return Type {#DefaultValue} |
| 2089 |
|
| 2090 |
If a mock method's return type is a built-in C++ type or pointer, by default it |
| 2091 |
will return 0 when invoked. Also, in C++ 11 and above, a mock method whose |
| 2092 |
return type has a default constructor will return a default-constructed value by |
| 2093 |
default. You only need to specify an action if this default value doesn't work |
| 2094 |
for you. |
| 2095 |
|
| 2096 |
Sometimes, you may want to change this default value, or you may want to specify |
| 2097 |
a default value for types gMock doesn't know about. You can do this using the |
| 2098 |
`::testing::DefaultValue` class template: |
| 2099 |
|
| 2100 |
```cpp |
| 2101 |
using ::testing::DefaultValue; |
| 2102 |
|
| 2103 |
class MockFoo : public Foo { |
| 2104 |
public: |
| 2105 |
MOCK_METHOD(Bar, CalculateBar, (), (override)); |
| 2106 |
}; |
| 2107 |
|
| 2108 |
|
| 2109 |
... |
| 2110 |
Bar default_bar; |
| 2111 |
// Sets the default return value for type Bar. |
| 2112 |
DefaultValue<Bar>::Set(default_bar); |
| 2113 |
|
| 2114 |
MockFoo foo; |
| 2115 |
|
| 2116 |
// We don't need to specify an action here, as the default |
| 2117 |
// return value works for us. |
| 2118 |
EXPECT_CALL(foo, CalculateBar()); |
| 2119 |
|
| 2120 |
foo.CalculateBar(); // This should return default_bar. |
| 2121 |
|
| 2122 |
// Unsets the default return value. |
| 2123 |
DefaultValue<Bar>::Clear(); |
| 2124 |
``` |
| 2125 |
|
| 2126 |
Please note that changing the default value for a type can make your tests hard |
| 2127 |
to understand. We recommend you to use this feature judiciously. For example, |
| 2128 |
you may want to make sure the `Set()` and `Clear()` calls are right next to the |
| 2129 |
code that uses your mock. |
| 2130 |
|
| 2131 |
### Setting the Default Actions for a Mock Method |
| 2132 |
|
| 2133 |
You've learned how to change the default value of a given type. However, this |
| 2134 |
may be too coarse for your purpose: perhaps you have two mock methods with the |
| 2135 |
same return type and you want them to have different behaviors. The `ON_CALL()` |
| 2136 |
macro allows you to customize your mock's behavior at the method level: |
| 2137 |
|
| 2138 |
```cpp |
| 2139 |
using ::testing::_; |
| 2140 |
using ::testing::AnyNumber; |
| 2141 |
using ::testing::Gt; |
| 2142 |
using ::testing::Return; |
| 2143 |
... |
| 2144 |
ON_CALL(foo, Sign(_)) |
| 2145 |
.WillByDefault(Return(-1)); |
| 2146 |
ON_CALL(foo, Sign(0)) |
| 2147 |
.WillByDefault(Return(0)); |
| 2148 |
ON_CALL(foo, Sign(Gt(0))) |
| 2149 |
.WillByDefault(Return(1)); |
| 2150 |
|
| 2151 |
EXPECT_CALL(foo, Sign(_)) |
| 2152 |
.Times(AnyNumber()); |
| 2153 |
|
| 2154 |
foo.Sign(5); // This should return 1. |
| 2155 |
foo.Sign(-9); // This should return -1. |
| 2156 |
foo.Sign(0); // This should return 0. |
| 2157 |
``` |
| 2158 |
|
| 2159 |
As you may have guessed, when there are more than one `ON_CALL()` statements, |
| 2160 |
the newer ones in the order take precedence over the older ones. In other words, |
| 2161 |
the **last** one that matches the function arguments will be used. This matching |
| 2162 |
order allows you to set up the common behavior in a mock object's constructor or |
| 2163 |
the test fixture's set-up phase and specialize the mock's behavior later. |
| 2164 |
|
| 2165 |
Note that both `ON_CALL` and `EXPECT_CALL` have the same "later statements take |
| 2166 |
precedence" rule, but they don't interact. That is, `EXPECT_CALL`s have their |
| 2167 |
own precedence order distinct from the `ON_CALL` precedence order. |
| 2168 |
|
| 2169 |
### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions} |
| 2170 |
|
| 2171 |
If the built-in actions don't suit you, you can use an existing callable |
| 2172 |
(function, `std::function`, method, functor, lambda) as an action. |
| 2173 |
|
| 2174 |
```cpp |
| 2175 |
using ::testing::_; using ::testing::Invoke; |
| 2176 |
|
| 2177 |
class MockFoo : public Foo { |
| 2178 |
public: |
| 2179 |
MOCK_METHOD(int, Sum, (int x, int y), (override)); |
| 2180 |
MOCK_METHOD(bool, ComplexJob, (int x), (override)); |
| 2181 |
}; |
| 2182 |
|
| 2183 |
int CalculateSum(int x, int y) { return x + y; } |
| 2184 |
int Sum3(int x, int y, int z) { return x + y + z; } |
| 2185 |
|
| 2186 |
class Helper { |
| 2187 |
public: |
| 2188 |
bool ComplexJob(int x); |
| 2189 |
}; |
| 2190 |
|
| 2191 |
... |
| 2192 |
MockFoo foo; |
| 2193 |
Helper helper; |
| 2194 |
EXPECT_CALL(foo, Sum(_, _)) |
| 2195 |
.WillOnce(&CalculateSum) |
| 2196 |
.WillRepeatedly(Invoke(NewPermanentCallback(Sum3, 1))); |
| 2197 |
EXPECT_CALL(foo, ComplexJob(_)) |
| 2198 |
.WillOnce(Invoke(&helper, &Helper::ComplexJob)) |
| 2199 |
.WillOnce([] { return true; }) |
| 2200 |
.WillRepeatedly([](int x) { return x > 0; }); |
| 2201 |
|
| 2202 |
foo.Sum(5, 6); // Invokes CalculateSum(5, 6). |
| 2203 |
foo.Sum(2, 3); // Invokes Sum3(1, 2, 3). |
| 2204 |
foo.ComplexJob(10); // Invokes helper.ComplexJob(10). |
| 2205 |
foo.ComplexJob(-1); // Invokes the inline lambda. |
| 2206 |
``` |
| 2207 |
|
| 2208 |
The only requirement is that the type of the function, etc must be *compatible* |
| 2209 |
with the signature of the mock function, meaning that the latter's arguments (if |
| 2210 |
it takes any) can be implicitly converted to the corresponding arguments of the |
| 2211 |
former, and the former's return type can be implicitly converted to that of the |
| 2212 |
latter. So, you can invoke something whose type is *not* exactly the same as the |
| 2213 |
mock function, as long as it's safe to do so - nice, huh? |
| 2214 |
|
| 2215 |
Note that: |
| 2216 |
|
| 2217 |
* The action takes ownership of the callback and will delete it when the |
| 2218 |
action itself is destructed. |
| 2219 |
* If the type of a callback is derived from a base callback type `C`, you need |
| 2220 |
to implicitly cast it to `C` to resolve the overloading, e.g. |
| 2221 |
|
| 2222 |
```cpp |
| 2223 |
using ::testing::Invoke; |
| 2224 |
... |
| 2225 |
ResultCallback<bool>* is_ok = ...; |
| 2226 |
... Invoke(is_ok) ...; // This works. |
| 2227 |
|
| 2228 |
BlockingClosure* done = new BlockingClosure; |
| 2229 |
... Invoke(implicit_cast<Closure*>(done)) ...; // The cast is necessary. |
| 2230 |
``` |
| 2231 |
|
| 2232 |
### Using Functions with Extra Info as Actions |
| 2233 |
|
| 2234 |
The function or functor you call using `Invoke()` must have the same number of |
| 2235 |
arguments as the mock function you use it for. Sometimes you may have a function |
| 2236 |
that takes more arguments, and you are willing to pass in the extra arguments |
| 2237 |
yourself to fill the gap. You can do this in gMock using callbacks with |
| 2238 |
pre-bound arguments. Here's an example: |
| 2239 |
|
| 2240 |
```cpp |
| 2241 |
using ::testing::Invoke; |
| 2242 |
|
| 2243 |
class MockFoo : public Foo { |
| 2244 |
public: |
| 2245 |
MOCK_METHOD(char, DoThis, (int n), (override)); |
| 2246 |
}; |
| 2247 |
|
| 2248 |
char SignOfSum(int x, int y) { |
| 2249 |
const int sum = x + y; |
| 2250 |
return (sum > 0) ? '+' : (sum < 0) ? '-' : '0'; |
| 2251 |
} |
| 2252 |
|
| 2253 |
TEST_F(FooTest, Test) { |
| 2254 |
MockFoo foo; |
| 2255 |
|
| 2256 |
EXPECT_CALL(foo, DoThis(2)) |
| 2257 |
.WillOnce(Invoke(NewPermanentCallback(SignOfSum, 5))); |
| 2258 |
EXPECT_EQ('+', foo.DoThis(2)); // Invokes SignOfSum(5, 2). |
| 2259 |
} |
| 2260 |
``` |
| 2261 |
|
| 2262 |
### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments |
| 2263 |
|
| 2264 |
`Invoke()` passes the mock function's arguments to the function, etc being |
| 2265 |
invoked such that the callee has the full context of the call to work with. If |
| 2266 |
the invoked function is not interested in some or all of the arguments, it can |
| 2267 |
simply ignore them. |
| 2268 |
|
| 2269 |
Yet, a common pattern is that a test author wants to invoke a function without |
| 2270 |
the arguments of the mock function. She could do that using a wrapper function |
| 2271 |
that throws away the arguments before invoking an underlining nullary function. |
| 2272 |
Needless to say, this can be tedious and obscures the intent of the test. |
| 2273 |
|
| 2274 |
There are two solutions to this problem. First, you can pass any callable of |
| 2275 |
zero args as an action. Alternatively, use `InvokeWithoutArgs()`, which is like |
| 2276 |
`Invoke()` except that it doesn't pass the mock function's arguments to the |
| 2277 |
callee. Here's an example of each: |
| 2278 |
|
| 2279 |
```cpp |
| 2280 |
using ::testing::_; |
| 2281 |
using ::testing::InvokeWithoutArgs; |
| 2282 |
|
| 2283 |
class MockFoo : public Foo { |
| 2284 |
public: |
| 2285 |
MOCK_METHOD(bool, ComplexJob, (int n), (override)); |
| 2286 |
}; |
| 2287 |
|
| 2288 |
bool Job1() { ... } |
| 2289 |
bool Job2(int n, char c) { ... } |
| 2290 |
|
| 2291 |
... |
| 2292 |
MockFoo foo; |
| 2293 |
EXPECT_CALL(foo, ComplexJob(_)) |
| 2294 |
.WillOnce([] { Job1(); }); |
| 2295 |
.WillOnce(InvokeWithoutArgs(NewPermanentCallback(Job2, 5, 'a'))); |
| 2296 |
|
| 2297 |
foo.ComplexJob(10); // Invokes Job1(). |
| 2298 |
foo.ComplexJob(20); // Invokes Job2(5, 'a'). |
| 2299 |
``` |
| 2300 |
|
| 2301 |
Note that: |
| 2302 |
|
| 2303 |
* The action takes ownership of the callback and will delete it when the |
| 2304 |
action itself is destructed. |
| 2305 |
* If the type of a callback is derived from a base callback type `C`, you need |
| 2306 |
to implicitly cast it to `C` to resolve the overloading, e.g. |
| 2307 |
|
| 2308 |
```cpp |
| 2309 |
using ::testing::InvokeWithoutArgs; |
| 2310 |
... |
| 2311 |
ResultCallback<bool>* is_ok = ...; |
| 2312 |
... InvokeWithoutArgs(is_ok) ...; // This works. |
| 2313 |
|
| 2314 |
BlockingClosure* done = ...; |
| 2315 |
... InvokeWithoutArgs(implicit_cast<Closure*>(done)) ...; |
| 2316 |
// The cast is necessary. |
| 2317 |
``` |
| 2318 |
|
| 2319 |
### Invoking an Argument of the Mock Function |
| 2320 |
|
| 2321 |
Sometimes a mock function will receive a function pointer, a functor (in other |
| 2322 |
words, a "callable") as an argument, e.g. |
| 2323 |
|
| 2324 |
```cpp |
| 2325 |
class MockFoo : public Foo { |
| 2326 |
public: |
| 2327 |
MOCK_METHOD(bool, DoThis, (int n, (ResultCallback1<bool, int>* callback)), |
| 2328 |
(override)); |
| 2329 |
}; |
| 2330 |
``` |
| 2331 |
|
| 2332 |
and you may want to invoke this callable argument: |
| 2333 |
|
| 2334 |
```cpp |
| 2335 |
using ::testing::_; |
| 2336 |
... |
| 2337 |
MockFoo foo; |
| 2338 |
EXPECT_CALL(foo, DoThis(_, _)) |
| 2339 |
.WillOnce(...); |
| 2340 |
// Will execute callback->Run(5), where callback is the |
| 2341 |
// second argument DoThis() receives. |
| 2342 |
``` |
| 2343 |
|
| 2344 |
{: .callout .note} |
| 2345 |
NOTE: The section below is legacy documentation from before C++ had lambdas: |
| 2346 |
|
| 2347 |
Arghh, you need to refer to a mock function argument but C++ has no lambda |
| 2348 |
(yet), so you have to define your own action. :-( Or do you really? |
| 2349 |
|
| 2350 |
Well, gMock has an action to solve *exactly* this problem: |
| 2351 |
|
| 2352 |
```cpp |
| 2353 |
InvokeArgument<N>(arg_1, arg_2, ..., arg_m) |
| 2354 |
``` |
| 2355 |
|
| 2356 |
will invoke the `N`-th (0-based) argument the mock function receives, with |
| 2357 |
`arg_1`, `arg_2`, ..., and `arg_m`. No matter if the argument is a function |
| 2358 |
pointer, a functor, or a callback. gMock handles them all. |
| 2359 |
|
| 2360 |
With that, you could write: |
| 2361 |
|
| 2362 |
```cpp |
| 2363 |
using ::testing::_; |
| 2364 |
using ::testing::InvokeArgument; |
| 2365 |
... |
| 2366 |
EXPECT_CALL(foo, DoThis(_, _)) |
| 2367 |
.WillOnce(InvokeArgument<1>(5)); |
| 2368 |
// Will execute callback->Run(5), where callback is the |
| 2369 |
// second argument DoThis() receives. |
| 2370 |
``` |
| 2371 |
|
| 2372 |
What if the callable takes an argument by reference? No problem - just wrap it |
| 2373 |
inside `std::ref()`: |
| 2374 |
|
| 2375 |
```cpp |
| 2376 |
... |
| 2377 |
MOCK_METHOD(bool, Bar, |
| 2378 |
((ResultCallback2<bool, int, const Helper&>* callback)), |
| 2379 |
(override)); |
| 2380 |
... |
| 2381 |
using ::testing::_; |
| 2382 |
using ::testing::InvokeArgument; |
| 2383 |
... |
| 2384 |
MockFoo foo; |
| 2385 |
Helper helper; |
| 2386 |
... |
| 2387 |
EXPECT_CALL(foo, Bar(_)) |
| 2388 |
.WillOnce(InvokeArgument<0>(5, std::ref(helper))); |
| 2389 |
// std::ref(helper) guarantees that a reference to helper, not a copy of |
| 2390 |
// it, will be passed to the callback. |
| 2391 |
``` |
| 2392 |
|
| 2393 |
What if the callable takes an argument by reference and we do **not** wrap the |
| 2394 |
argument in `std::ref()`? Then `InvokeArgument()` will *make a copy* of the |
| 2395 |
argument, and pass a *reference to the copy*, instead of a reference to the |
| 2396 |
original value, to the callable. This is especially handy when the argument is a |
| 2397 |
temporary value: |
| 2398 |
|
| 2399 |
```cpp |
| 2400 |
... |
| 2401 |
MOCK_METHOD(bool, DoThat, (bool (*f)(const double& x, const string& s)), |
| 2402 |
(override)); |
| 2403 |
... |
| 2404 |
using ::testing::_; |
| 2405 |
using ::testing::InvokeArgument; |
| 2406 |
... |
| 2407 |
MockFoo foo; |
| 2408 |
... |
| 2409 |
EXPECT_CALL(foo, DoThat(_)) |
| 2410 |
.WillOnce(InvokeArgument<0>(5.0, string("Hi"))); |
| 2411 |
// Will execute (*f)(5.0, string("Hi")), where f is the function pointer |
| 2412 |
// DoThat() receives. Note that the values 5.0 and string("Hi") are |
| 2413 |
// temporary and dead once the EXPECT_CALL() statement finishes. Yet |
| 2414 |
// it's fine to perform this action later, since a copy of the values |
| 2415 |
// are kept inside the InvokeArgument action. |
| 2416 |
``` |
| 2417 |
|
| 2418 |
### Ignoring an Action's Result |
| 2419 |
|
| 2420 |
Sometimes you have an action that returns *something*, but you need an action |
| 2421 |
that returns `void` (perhaps you want to use it in a mock function that returns |
| 2422 |
`void`, or perhaps it needs to be used in `DoAll()` and it's not the last in the |
| 2423 |
list). `IgnoreResult()` lets you do that. For example: |
| 2424 |
|
| 2425 |
```cpp |
| 2426 |
using ::testing::_; |
| 2427 |
using ::testing::DoAll; |
| 2428 |
using ::testing::IgnoreResult; |
| 2429 |
using ::testing::Return; |
| 2430 |
|
| 2431 |
int Process(const MyData& data); |
| 2432 |
string DoSomething(); |
| 2433 |
|
| 2434 |
class MockFoo : public Foo { |
| 2435 |
public: |
| 2436 |
MOCK_METHOD(void, Abc, (const MyData& data), (override)); |
| 2437 |
MOCK_METHOD(bool, Xyz, (), (override)); |
| 2438 |
}; |
| 2439 |
|
| 2440 |
... |
| 2441 |
MockFoo foo; |
| 2442 |
EXPECT_CALL(foo, Abc(_)) |
| 2443 |
// .WillOnce(Invoke(Process)); |
| 2444 |
// The above line won't compile as Process() returns int but Abc() needs |
| 2445 |
// to return void. |
| 2446 |
.WillOnce(IgnoreResult(Process)); |
| 2447 |
EXPECT_CALL(foo, Xyz()) |
| 2448 |
.WillOnce(DoAll(IgnoreResult(DoSomething), |
| 2449 |
// Ignores the string DoSomething() returns. |
| 2450 |
Return(true))); |
| 2451 |
``` |
| 2452 |
|
| 2453 |
Note that you **cannot** use `IgnoreResult()` on an action that already returns |
| 2454 |
`void`. Doing so will lead to ugly compiler errors. |
| 2455 |
|
| 2456 |
### Selecting an Action's Arguments {#SelectingArgs} |
| 2457 |
|
| 2458 |
Say you have a mock function `Foo()` that takes seven arguments, and you have a |
| 2459 |
custom action that you want to invoke when `Foo()` is called. Trouble is, the |
| 2460 |
custom action only wants three arguments: |
| 2461 |
|
| 2462 |
```cpp |
| 2463 |
using ::testing::_; |
| 2464 |
using ::testing::Invoke; |
| 2465 |
... |
| 2466 |
MOCK_METHOD(bool, Foo, |
| 2467 |
(bool visible, const string& name, int x, int y, |
| 2468 |
(const map<pair<int, int>>), double& weight, double min_weight, |
| 2469 |
double max_wight)); |
| 2470 |
... |
| 2471 |
bool IsVisibleInQuadrant1(bool visible, int x, int y) { |
| 2472 |
return visible && x >= 0 && y >= 0; |
| 2473 |
} |
| 2474 |
... |
| 2475 |
EXPECT_CALL(mock, Foo) |
| 2476 |
.WillOnce(Invoke(IsVisibleInQuadrant1)); // Uh, won't compile. :-( |
| 2477 |
``` |
| 2478 |
|
| 2479 |
To please the compiler God, you need to define an "adaptor" that has the same |
| 2480 |
signature as `Foo()` and calls the custom action with the right arguments: |
| 2481 |
|
| 2482 |
```cpp |
| 2483 |
using ::testing::_; |
| 2484 |
using ::testing::Invoke; |
| 2485 |
... |
| 2486 |
bool MyIsVisibleInQuadrant1(bool visible, const string& name, int x, int y, |
| 2487 |
const map<pair<int, int>, double>& weight, |
| 2488 |
double min_weight, double max_wight) { |
| 2489 |
return IsVisibleInQuadrant1(visible, x, y); |
| 2490 |
} |
| 2491 |
... |
| 2492 |
EXPECT_CALL(mock, Foo) |
| 2493 |
.WillOnce(Invoke(MyIsVisibleInQuadrant1)); // Now it works. |
| 2494 |
``` |
| 2495 |
|
| 2496 |
But isn't this awkward? |
| 2497 |
|
| 2498 |
gMock provides a generic *action adaptor*, so you can spend your time minding |
| 2499 |
more important business than writing your own adaptors. Here's the syntax: |
| 2500 |
|
| 2501 |
```cpp |
| 2502 |
WithArgs<N1, N2, ..., Nk>(action) |
| 2503 |
``` |
| 2504 |
|
| 2505 |
creates an action that passes the arguments of the mock function at the given |
| 2506 |
indices (0-based) to the inner `action` and performs it. Using `WithArgs`, our |
| 2507 |
original example can be written as: |
| 2508 |
|
| 2509 |
```cpp |
| 2510 |
using ::testing::_; |
| 2511 |
using ::testing::Invoke; |
| 2512 |
using ::testing::WithArgs; |
| 2513 |
... |
| 2514 |
EXPECT_CALL(mock, Foo) |
| 2515 |
.WillOnce(WithArgs<0, 2, 3>(Invoke(IsVisibleInQuadrant1))); // No need to define your own adaptor. |
| 2516 |
``` |
| 2517 |
|
| 2518 |
For better readability, gMock also gives you: |
| 2519 |
|
| 2520 |
* `WithoutArgs(action)` when the inner `action` takes *no* argument, and |
| 2521 |
* `WithArg<N>(action)` (no `s` after `Arg`) when the inner `action` takes |
| 2522 |
*one* argument. |
| 2523 |
|
| 2524 |
As you may have realized, `InvokeWithoutArgs(...)` is just syntactic sugar for |
| 2525 |
`WithoutArgs(Invoke(...))`. |
| 2526 |
|
| 2527 |
Here are more tips: |
| 2528 |
|
| 2529 |
* The inner action used in `WithArgs` and friends does not have to be |
| 2530 |
`Invoke()` -- it can be anything. |
| 2531 |
* You can repeat an argument in the argument list if necessary, e.g. |
| 2532 |
`WithArgs<2, 3, 3, 5>(...)`. |
| 2533 |
* You can change the order of the arguments, e.g. `WithArgs<3, 2, 1>(...)`. |
| 2534 |
* The types of the selected arguments do *not* have to match the signature of |
| 2535 |
the inner action exactly. It works as long as they can be implicitly |
| 2536 |
converted to the corresponding arguments of the inner action. For example, |
| 2537 |
if the 4-th argument of the mock function is an `int` and `my_action` takes |
| 2538 |
a `double`, `WithArg<4>(my_action)` will work. |
| 2539 |
|
| 2540 |
### Ignoring Arguments in Action Functions |
| 2541 |
|
| 2542 |
The [selecting-an-action's-arguments](#SelectingArgs) recipe showed us one way |
| 2543 |
to make a mock function and an action with incompatible argument lists fit |
| 2544 |
together. The downside is that wrapping the action in `WithArgs<...>()` can get |
| 2545 |
tedious for people writing the tests. |
| 2546 |
|
| 2547 |
If you are defining a function (or method, functor, lambda, callback) to be used |
| 2548 |
with `Invoke*()`, and you are not interested in some of its arguments, an |
| 2549 |
alternative to `WithArgs` is to declare the uninteresting arguments as `Unused`. |
| 2550 |
This makes the definition less cluttered and less fragile in case the types of |
| 2551 |
the uninteresting arguments change. It could also increase the chance the action |
| 2552 |
function can be reused. For example, given |
| 2553 |
|
| 2554 |
```cpp |
| 2555 |
public: |
| 2556 |
MOCK_METHOD(double, Foo, double(const string& label, double x, double y), |
| 2557 |
(override)); |
| 2558 |
MOCK_METHOD(double, Bar, (int index, double x, double y), (override)); |
| 2559 |
``` |
| 2560 |
|
| 2561 |
instead of |
| 2562 |
|
| 2563 |
```cpp |
| 2564 |
using ::testing::_; |
| 2565 |
using ::testing::Invoke; |
| 2566 |
|
| 2567 |
double DistanceToOriginWithLabel(const string& label, double x, double y) { |
| 2568 |
return sqrt(x*x + y*y); |
| 2569 |
} |
| 2570 |
double DistanceToOriginWithIndex(int index, double x, double y) { |
| 2571 |
return sqrt(x*x + y*y); |
| 2572 |
} |
| 2573 |
... |
| 2574 |
EXPECT_CALL(mock, Foo("abc", _, _)) |
| 2575 |
.WillOnce(Invoke(DistanceToOriginWithLabel)); |
| 2576 |
EXPECT_CALL(mock, Bar(5, _, _)) |
| 2577 |
.WillOnce(Invoke(DistanceToOriginWithIndex)); |
| 2578 |
``` |
| 2579 |
|
| 2580 |
you could write |
| 2581 |
|
| 2582 |
```cpp |
| 2583 |
using ::testing::_; |
| 2584 |
using ::testing::Invoke; |
| 2585 |
using ::testing::Unused; |
| 2586 |
|
| 2587 |
double DistanceToOrigin(Unused, double x, double y) { |
| 2588 |
return sqrt(x*x + y*y); |
| 2589 |
} |
| 2590 |
... |
| 2591 |
EXPECT_CALL(mock, Foo("abc", _, _)) |
| 2592 |
.WillOnce(Invoke(DistanceToOrigin)); |
| 2593 |
EXPECT_CALL(mock, Bar(5, _, _)) |
| 2594 |
.WillOnce(Invoke(DistanceToOrigin)); |
| 2595 |
``` |
| 2596 |
|
| 2597 |
### Sharing Actions |
| 2598 |
|
| 2599 |
Just like matchers, a gMock action object consists of a pointer to a ref-counted |
| 2600 |
implementation object. Therefore copying actions is also allowed and very |
| 2601 |
efficient. When the last action that references the implementation object dies, |
| 2602 |
the implementation object will be deleted. |
| 2603 |
|
| 2604 |
If you have some complex action that you want to use again and again, you may |
| 2605 |
not have to build it from scratch every time. If the action doesn't have an |
| 2606 |
internal state (i.e. if it always does the same thing no matter how many times |
| 2607 |
it has been called), you can assign it to an action variable and use that |
| 2608 |
variable repeatedly. For example: |
| 2609 |
|
| 2610 |
```cpp |
| 2611 |
using ::testing::Action; |
| 2612 |
using ::testing::DoAll; |
| 2613 |
using ::testing::Return; |
| 2614 |
using ::testing::SetArgPointee; |
| 2615 |
... |
| 2616 |
Action<bool(int*)> set_flag = DoAll(SetArgPointee<0>(5), |
| 2617 |
Return(true)); |
| 2618 |
... use set_flag in .WillOnce() and .WillRepeatedly() ... |
| 2619 |
``` |
| 2620 |
|
| 2621 |
However, if the action has its own state, you may be surprised if you share the |
| 2622 |
action object. Suppose you have an action factory `IncrementCounter(init)` which |
| 2623 |
creates an action that increments and returns a counter whose initial value is |
| 2624 |
`init`, using two actions created from the same expression and using a shared |
| 2625 |
action will exhibit different behaviors. Example: |
| 2626 |
|
| 2627 |
```cpp |
| 2628 |
EXPECT_CALL(foo, DoThis()) |
| 2629 |
.WillRepeatedly(IncrementCounter(0)); |
| 2630 |
EXPECT_CALL(foo, DoThat()) |
| 2631 |
.WillRepeatedly(IncrementCounter(0)); |
| 2632 |
foo.DoThis(); // Returns 1. |
| 2633 |
foo.DoThis(); // Returns 2. |
| 2634 |
foo.DoThat(); // Returns 1 - Blah() uses a different |
| 2635 |
// counter than Bar()'s. |
| 2636 |
``` |
| 2637 |
|
| 2638 |
versus |
| 2639 |
|
| 2640 |
```cpp |
| 2641 |
using ::testing::Action; |
| 2642 |
... |
| 2643 |
Action<int()> increment = IncrementCounter(0); |
| 2644 |
EXPECT_CALL(foo, DoThis()) |
| 2645 |
.WillRepeatedly(increment); |
| 2646 |
EXPECT_CALL(foo, DoThat()) |
| 2647 |
.WillRepeatedly(increment); |
| 2648 |
foo.DoThis(); // Returns 1. |
| 2649 |
foo.DoThis(); // Returns 2. |
| 2650 |
foo.DoThat(); // Returns 3 - the counter is shared. |
| 2651 |
``` |
| 2652 |
|
| 2653 |
### Testing Asynchronous Behavior |
| 2654 |
|
| 2655 |
One oft-encountered problem with gMock is that it can be hard to test |
| 2656 |
asynchronous behavior. Suppose you had a `EventQueue` class that you wanted to |
| 2657 |
test, and you created a separate `EventDispatcher` interface so that you could |
| 2658 |
easily mock it out. However, the implementation of the class fired all the |
| 2659 |
events on a background thread, which made test timings difficult. You could just |
| 2660 |
insert `sleep()` statements and hope for the best, but that makes your test |
| 2661 |
behavior nondeterministic. A better way is to use gMock actions and |
| 2662 |
`Notification` objects to force your asynchronous test to behave synchronously. |
| 2663 |
|
| 2664 |
```cpp |
| 2665 |
class MockEventDispatcher : public EventDispatcher { |
| 2666 |
MOCK_METHOD(bool, DispatchEvent, (int32), (override)); |
| 2667 |
}; |
| 2668 |
|
| 2669 |
TEST(EventQueueTest, EnqueueEventTest) { |
| 2670 |
MockEventDispatcher mock_event_dispatcher; |
| 2671 |
EventQueue event_queue(&mock_event_dispatcher); |
| 2672 |
|
| 2673 |
const int32 kEventId = 321; |
| 2674 |
absl::Notification done; |
| 2675 |
EXPECT_CALL(mock_event_dispatcher, DispatchEvent(kEventId)) |
| 2676 |
.WillOnce([&done] { done.Notify(); }); |
| 2677 |
|
| 2678 |
event_queue.EnqueueEvent(kEventId); |
| 2679 |
done.WaitForNotification(); |
| 2680 |
} |
| 2681 |
``` |
| 2682 |
|
| 2683 |
In the example above, we set our normal gMock expectations, but then add an |
| 2684 |
additional action to notify the `Notification` object. Now we can just call |
| 2685 |
`Notification::WaitForNotification()` in the main thread to wait for the |
| 2686 |
asynchronous call to finish. After that, our test suite is complete and we can |
| 2687 |
safely exit. |
| 2688 |
|
| 2689 |
{: .callout .note} |
| 2690 |
Note: this example has a downside: namely, if the expectation is not satisfied, |
| 2691 |
our test will run forever. It will eventually time-out and fail, but it will |
| 2692 |
take longer and be slightly harder to debug. To alleviate this problem, you can |
| 2693 |
use `WaitForNotificationWithTimeout(ms)` instead of `WaitForNotification()`. |
| 2694 |
|
| 2695 |
## Misc Recipes on Using gMock |
| 2696 |
|
| 2697 |
### Mocking Methods That Use Move-Only Types |
| 2698 |
|
| 2699 |
C++11 introduced *move-only types*. A move-only-typed value can be moved from |
| 2700 |
one object to another, but cannot be copied. `std::unique_ptr<T>` is probably |
| 2701 |
the most commonly used move-only type. |
| 2702 |
|
| 2703 |
Mocking a method that takes and/or returns move-only types presents some |
| 2704 |
challenges, but nothing insurmountable. This recipe shows you how you can do it. |
| 2705 |
Note that the support for move-only method arguments was only introduced to |
| 2706 |
gMock in April 2017; in older code, you may find more complex |
| 2707 |
[workarounds](#LegacyMoveOnly) for lack of this feature. |
| 2708 |
|
| 2709 |
Let’s say we are working on a fictional project that lets one post and share |
| 2710 |
snippets called “buzzes”. Your code uses these types: |
| 2711 |
|
| 2712 |
```cpp |
| 2713 |
enum class AccessLevel { kInternal, kPublic }; |
| 2714 |
|
| 2715 |
class Buzz { |
| 2716 |
public: |
| 2717 |
explicit Buzz(AccessLevel access) { ... } |
| 2718 |
... |
| 2719 |
}; |
| 2720 |
|
| 2721 |
class Buzzer { |
| 2722 |
public: |
| 2723 |
virtual ~Buzzer() {} |
| 2724 |
virtual std::unique_ptr<Buzz> MakeBuzz(StringPiece text) = 0; |
| 2725 |
virtual bool ShareBuzz(std::unique_ptr<Buzz> buzz, int64_t timestamp) = 0; |
| 2726 |
... |
| 2727 |
}; |
| 2728 |
``` |
| 2729 |
|
| 2730 |
A `Buzz` object represents a snippet being posted. A class that implements the |
| 2731 |
`Buzzer` interface is capable of creating and sharing `Buzz`es. Methods in |
| 2732 |
`Buzzer` may return a `unique_ptr<Buzz>` or take a `unique_ptr<Buzz>`. Now we |
| 2733 |
need to mock `Buzzer` in our tests. |
| 2734 |
|
| 2735 |
To mock a method that accepts or returns move-only types, you just use the |
| 2736 |
familiar `MOCK_METHOD` syntax as usual: |
| 2737 |
|
| 2738 |
```cpp |
| 2739 |
class MockBuzzer : public Buzzer { |
| 2740 |
public: |
| 2741 |
MOCK_METHOD(std::unique_ptr<Buzz>, MakeBuzz, (StringPiece text), (override)); |
| 2742 |
MOCK_METHOD(bool, ShareBuzz, (std::unique_ptr<Buzz> buzz, int64_t timestamp), |
| 2743 |
(override)); |
| 2744 |
}; |
| 2745 |
``` |
| 2746 |
|
| 2747 |
Now that we have the mock class defined, we can use it in tests. In the |
| 2748 |
following code examples, we assume that we have defined a `MockBuzzer` object |
| 2749 |
named `mock_buzzer_`: |
| 2750 |
|
| 2751 |
```cpp |
| 2752 |
MockBuzzer mock_buzzer_; |
| 2753 |
``` |
| 2754 |
|
| 2755 |
First let’s see how we can set expectations on the `MakeBuzz()` method, which |
| 2756 |
returns a `unique_ptr<Buzz>`. |
| 2757 |
|
| 2758 |
As usual, if you set an expectation without an action (i.e. the `.WillOnce()` or |
| 2759 |
`.WillRepeatedly()` clause), when that expectation fires, the default action for |
| 2760 |
that method will be taken. Since `unique_ptr<>` has a default constructor that |
| 2761 |
returns a null `unique_ptr`, that’s what you’ll get if you don’t specify an |
| 2762 |
action: |
| 2763 |
|
| 2764 |
```cpp |
| 2765 |
// Use the default action. |
| 2766 |
EXPECT_CALL(mock_buzzer_, MakeBuzz("hello")); |
| 2767 |
|
| 2768 |
// Triggers the previous EXPECT_CALL. |
| 2769 |
EXPECT_EQ(nullptr, mock_buzzer_.MakeBuzz("hello")); |
| 2770 |
``` |
| 2771 |
|
| 2772 |
If you are not happy with the default action, you can tweak it as usual; see |
| 2773 |
[Setting Default Actions](#OnCall). |
| 2774 |
|
| 2775 |
If you just need to return a pre-defined move-only value, you can use the |
| 2776 |
`Return(ByMove(...))` action: |
| 2777 |
|
| 2778 |
```cpp |
| 2779 |
// When this fires, the unique_ptr<> specified by ByMove(...) will |
| 2780 |
// be returned. |
| 2781 |
EXPECT_CALL(mock_buzzer_, MakeBuzz("world")) |
| 2782 |
.WillOnce(Return(ByMove(MakeUnique<Buzz>(AccessLevel::kInternal)))); |
| 2783 |
|
| 2784 |
EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("world")); |
| 2785 |
``` |
| 2786 |
|
| 2787 |
Note that `ByMove()` is essential here - if you drop it, the code won’t compile. |
| 2788 |
|
| 2789 |
Quiz time! What do you think will happen if a `Return(ByMove(...))` action is |
| 2790 |
performed more than once (e.g. you write `... |
| 2791 |
.WillRepeatedly(Return(ByMove(...)));`)? Come think of it, after the first time |
| 2792 |
the action runs, the source value will be consumed (since it’s a move-only |
| 2793 |
value), so the next time around, there’s no value to move from -- you’ll get a |
| 2794 |
run-time error that `Return(ByMove(...))` can only be run once. |
| 2795 |
|
| 2796 |
If you need your mock method to do more than just moving a pre-defined value, |
| 2797 |
remember that you can always use a lambda or a callable object, which can do |
| 2798 |
pretty much anything you want: |
| 2799 |
|
| 2800 |
```cpp |
| 2801 |
EXPECT_CALL(mock_buzzer_, MakeBuzz("x")) |
| 2802 |
.WillRepeatedly([](StringPiece text) { |
| 2803 |
return MakeUnique<Buzz>(AccessLevel::kInternal); |
| 2804 |
}); |
| 2805 |
|
| 2806 |
EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x")); |
| 2807 |
EXPECT_NE(nullptr, mock_buzzer_.MakeBuzz("x")); |
| 2808 |
``` |
| 2809 |
|
| 2810 |
Every time this `EXPECT_CALL` fires, a new `unique_ptr<Buzz>` will be created |
| 2811 |
and returned. You cannot do this with `Return(ByMove(...))`. |
| 2812 |
|
| 2813 |
That covers returning move-only values; but how do we work with methods |
| 2814 |
accepting move-only arguments? The answer is that they work normally, although |
| 2815 |
some actions will not compile when any of method's arguments are move-only. You |
| 2816 |
can always use `Return`, or a [lambda or functor](#FunctionsAsActions): |
| 2817 |
|
| 2818 |
```cpp |
| 2819 |
using ::testing::Unused; |
| 2820 |
|
| 2821 |
EXPECT_CALL(mock_buzzer_, ShareBuzz(NotNull(), _)).WillOnce(Return(true)); |
| 2822 |
EXPECT_TRUE(mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal)), |
| 2823 |
0); |
| 2824 |
|
| 2825 |
EXPECT_CALL(mock_buzzer_, ShareBuzz(_, _)).WillOnce( |
| 2826 |
[](std::unique_ptr<Buzz> buzz, Unused) { return buzz != nullptr; }); |
| 2827 |
EXPECT_FALSE(mock_buzzer_.ShareBuzz(nullptr, 0)); |
| 2828 |
``` |
| 2829 |
|
| 2830 |
Many built-in actions (`WithArgs`, `WithoutArgs`,`DeleteArg`, `SaveArg`, ...) |
| 2831 |
could in principle support move-only arguments, but the support for this is not |
| 2832 |
implemented yet. If this is blocking you, please file a bug. |
| 2833 |
|
| 2834 |
A few actions (e.g. `DoAll`) copy their arguments internally, so they can never |
| 2835 |
work with non-copyable objects; you'll have to use functors instead. |
| 2836 |
|
| 2837 |
#### Legacy workarounds for move-only types {#LegacyMoveOnly} |
| 2838 |
|
| 2839 |
Support for move-only function arguments was only introduced to gMock in April |
| 2840 |
of 2017. In older code, you may encounter the following workaround for the lack |
| 2841 |
of this feature (it is no longer necessary - we're including it just for |
| 2842 |
reference): |
| 2843 |
|
| 2844 |
```cpp |
| 2845 |
class MockBuzzer : public Buzzer { |
| 2846 |
public: |
| 2847 |
MOCK_METHOD(bool, DoShareBuzz, (Buzz* buzz, Time timestamp)); |
| 2848 |
bool ShareBuzz(std::unique_ptr<Buzz> buzz, Time timestamp) override { |
| 2849 |
return DoShareBuzz(buzz.get(), timestamp); |
| 2850 |
} |
| 2851 |
}; |
| 2852 |
``` |
| 2853 |
|
| 2854 |
The trick is to delegate the `ShareBuzz()` method to a mock method (let’s call |
| 2855 |
it `DoShareBuzz()`) that does not take move-only parameters. Then, instead of |
| 2856 |
setting expectations on `ShareBuzz()`, you set them on the `DoShareBuzz()` mock |
| 2857 |
method: |
| 2858 |
|
| 2859 |
```cpp |
| 2860 |
MockBuzzer mock_buzzer_; |
| 2861 |
EXPECT_CALL(mock_buzzer_, DoShareBuzz(NotNull(), _)); |
| 2862 |
|
| 2863 |
// When one calls ShareBuzz() on the MockBuzzer like this, the call is |
| 2864 |
// forwarded to DoShareBuzz(), which is mocked. Therefore this statement |
| 2865 |
// will trigger the above EXPECT_CALL. |
| 2866 |
mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal), 0); |
| 2867 |
``` |
| 2868 |
|
| 2869 |
### Making the Compilation Faster |
| 2870 |
|
| 2871 |
Believe it or not, the *vast majority* of the time spent on compiling a mock |
| 2872 |
class is in generating its constructor and destructor, as they perform |
| 2873 |
non-trivial tasks (e.g. verification of the expectations). What's more, mock |
| 2874 |
methods with different signatures have different types and thus their |
| 2875 |
constructors/destructors need to be generated by the compiler separately. As a |
| 2876 |
result, if you mock many different types of methods, compiling your mock class |
| 2877 |
can get really slow. |
| 2878 |
|
| 2879 |
If you are experiencing slow compilation, you can move the definition of your |
| 2880 |
mock class' constructor and destructor out of the class body and into a `.cc` |
| 2881 |
file. This way, even if you `#include` your mock class in N files, the compiler |
| 2882 |
only needs to generate its constructor and destructor once, resulting in a much |
| 2883 |
faster compilation. |
| 2884 |
|
| 2885 |
Let's illustrate the idea using an example. Here's the definition of a mock |
| 2886 |
class before applying this recipe: |
| 2887 |
|
| 2888 |
```cpp |
| 2889 |
// File mock_foo.h. |
| 2890 |
... |
| 2891 |
class MockFoo : public Foo { |
| 2892 |
public: |
| 2893 |
// Since we don't declare the constructor or the destructor, |
| 2894 |
// the compiler will generate them in every translation unit |
| 2895 |
// where this mock class is used. |
| 2896 |
|
| 2897 |
MOCK_METHOD(int, DoThis, (), (override)); |
| 2898 |
MOCK_METHOD(bool, DoThat, (const char* str), (override)); |
| 2899 |
... more mock methods ... |
| 2900 |
}; |
| 2901 |
``` |
| 2902 |
|
| 2903 |
After the change, it would look like: |
| 2904 |
|
| 2905 |
```cpp |
| 2906 |
// File mock_foo.h. |
| 2907 |
... |
| 2908 |
class MockFoo : public Foo { |
| 2909 |
public: |
| 2910 |
// The constructor and destructor are declared, but not defined, here. |
| 2911 |
MockFoo(); |
| 2912 |
virtual ~MockFoo(); |
| 2913 |
|
| 2914 |
MOCK_METHOD(int, DoThis, (), (override)); |
| 2915 |
MOCK_METHOD(bool, DoThat, (const char* str), (override)); |
| 2916 |
... more mock methods ... |
| 2917 |
}; |
| 2918 |
``` |
| 2919 |
|
| 2920 |
and |
| 2921 |
|
| 2922 |
```cpp |
| 2923 |
// File mock_foo.cc. |
| 2924 |
#include "path/to/mock_foo.h" |
| 2925 |
|
| 2926 |
// The definitions may appear trivial, but the functions actually do a |
| 2927 |
// lot of things through the constructors/destructors of the member |
| 2928 |
// variables used to implement the mock methods. |
| 2929 |
MockFoo::MockFoo() {} |
| 2930 |
MockFoo::~MockFoo() {} |
| 2931 |
``` |
| 2932 |
|
| 2933 |
### Forcing a Verification |
| 2934 |
|
| 2935 |
When it's being destroyed, your friendly mock object will automatically verify |
| 2936 |
that all expectations on it have been satisfied, and will generate googletest |
| 2937 |
failures if not. This is convenient as it leaves you with one less thing to |
| 2938 |
worry about. That is, unless you are not sure if your mock object will be |
| 2939 |
destroyed. |
| 2940 |
|
| 2941 |
How could it be that your mock object won't eventually be destroyed? Well, it |
| 2942 |
might be created on the heap and owned by the code you are testing. Suppose |
| 2943 |
there's a bug in that code and it doesn't delete the mock object properly - you |
| 2944 |
could end up with a passing test when there's actually a bug. |
| 2945 |
|
| 2946 |
Using a heap checker is a good idea and can alleviate the concern, but its |
| 2947 |
implementation is not 100% reliable. So, sometimes you do want to *force* gMock |
| 2948 |
to verify a mock object before it is (hopefully) destructed. You can do this |
| 2949 |
with `Mock::VerifyAndClearExpectations(&mock_object)`: |
| 2950 |
|
| 2951 |
```cpp |
| 2952 |
TEST(MyServerTest, ProcessesRequest) { |
| 2953 |
using ::testing::Mock; |
| 2954 |
|
| 2955 |
MockFoo* const foo = new MockFoo; |
| 2956 |
EXPECT_CALL(*foo, ...)...; |
| 2957 |
// ... other expectations ... |
| 2958 |
|
| 2959 |
// server now owns foo. |
| 2960 |
MyServer server(foo); |
| 2961 |
server.ProcessRequest(...); |
| 2962 |
|
| 2963 |
// In case that server's destructor will forget to delete foo, |
| 2964 |
// this will verify the expectations anyway. |
| 2965 |
Mock::VerifyAndClearExpectations(foo); |
| 2966 |
} // server is destroyed when it goes out of scope here. |
| 2967 |
``` |
| 2968 |
|
| 2969 |
{: .callout .tip} |
| 2970 |
**Tip:** The `Mock::VerifyAndClearExpectations()` function returns a `bool` to |
| 2971 |
indicate whether the verification was successful (`true` for yes), so you can |
| 2972 |
wrap that function call inside a `ASSERT_TRUE()` if there is no point going |
| 2973 |
further when the verification has failed. |
| 2974 |
|
| 2975 |
Do not set new expectations after verifying and clearing a mock after its use. |
| 2976 |
Setting expectations after code that exercises the mock has undefined behavior. |
| 2977 |
See [Using Mocks in Tests](gmock_for_dummies.md#using-mocks-in-tests) for more |
| 2978 |
information. |
| 2979 |
|
| 2980 |
### Using Checkpoints {#UsingCheckPoints} |
| 2981 |
|
| 2982 |
Sometimes you might want to test a mock object's behavior in phases whose sizes |
| 2983 |
are each manageable, or you might want to set more detailed expectations about |
| 2984 |
which API calls invoke which mock functions. |
| 2985 |
|
| 2986 |
A technique you can use is to put the expectations in a sequence and insert |
| 2987 |
calls to a dummy "checkpoint" function at specific places. Then you can verify |
| 2988 |
that the mock function calls do happen at the right time. For example, if you |
| 2989 |
are exercising the code: |
| 2990 |
|
| 2991 |
```cpp |
| 2992 |
Foo(1); |
| 2993 |
Foo(2); |
| 2994 |
Foo(3); |
| 2995 |
``` |
| 2996 |
|
| 2997 |
and want to verify that `Foo(1)` and `Foo(3)` both invoke `mock.Bar("a")`, but |
| 2998 |
`Foo(2)` doesn't invoke anything, you can write: |
| 2999 |
|
| 3000 |
```cpp |
| 3001 |
using ::testing::MockFunction; |
| 3002 |
|
| 3003 |
TEST(FooTest, InvokesBarCorrectly) { |
| 3004 |
MyMock mock; |
| 3005 |
// Class MockFunction<F> has exactly one mock method. It is named |
| 3006 |
// Call() and has type F. |
| 3007 |
MockFunction<void(string check_point_name)> check; |
| 3008 |
{ |
| 3009 |
InSequence s; |
| 3010 |
|
| 3011 |
EXPECT_CALL(mock, Bar("a")); |
| 3012 |
EXPECT_CALL(check, Call("1")); |
| 3013 |
EXPECT_CALL(check, Call("2")); |
| 3014 |
EXPECT_CALL(mock, Bar("a")); |
| 3015 |
} |
| 3016 |
Foo(1); |
| 3017 |
check.Call("1"); |
| 3018 |
Foo(2); |
| 3019 |
check.Call("2"); |
| 3020 |
Foo(3); |
| 3021 |
} |
| 3022 |
``` |
| 3023 |
|
| 3024 |
The expectation spec says that the first `Bar("a")` call must happen before |
| 3025 |
checkpoint "1", the second `Bar("a")` call must happen after checkpoint "2", and |
| 3026 |
nothing should happen between the two checkpoints. The explicit checkpoints make |
| 3027 |
it clear which `Bar("a")` is called by which call to `Foo()`. |
| 3028 |
|
| 3029 |
### Mocking Destructors |
| 3030 |
|
| 3031 |
Sometimes you want to make sure a mock object is destructed at the right time, |
| 3032 |
e.g. after `bar->A()` is called but before `bar->B()` is called. We already know |
| 3033 |
that you can specify constraints on the [order](#OrderedCalls) of mock function |
| 3034 |
calls, so all we need to do is to mock the destructor of the mock function. |
| 3035 |
|
| 3036 |
This sounds simple, except for one problem: a destructor is a special function |
| 3037 |
with special syntax and special semantics, and the `MOCK_METHOD` macro doesn't |
| 3038 |
work for it: |
| 3039 |
|
| 3040 |
```cpp |
| 3041 |
MOCK_METHOD(void, ~MockFoo, ()); // Won't compile! |
| 3042 |
``` |
| 3043 |
|
| 3044 |
The good news is that you can use a simple pattern to achieve the same effect. |
| 3045 |
First, add a mock function `Die()` to your mock class and call it in the |
| 3046 |
destructor, like this: |
| 3047 |
|
| 3048 |
```cpp |
| 3049 |
class MockFoo : public Foo { |
| 3050 |
... |
| 3051 |
// Add the following two lines to the mock class. |
| 3052 |
MOCK_METHOD(void, Die, ()); |
| 3053 |
~MockFoo() override { Die(); } |
| 3054 |
}; |
| 3055 |
``` |
| 3056 |
|
| 3057 |
(If the name `Die()` clashes with an existing symbol, choose another name.) Now, |
| 3058 |
we have translated the problem of testing when a `MockFoo` object dies to |
| 3059 |
testing when its `Die()` method is called: |
| 3060 |
|
| 3061 |
```cpp |
| 3062 |
MockFoo* foo = new MockFoo; |
| 3063 |
MockBar* bar = new MockBar; |
| 3064 |
... |
| 3065 |
{ |
| 3066 |
InSequence s; |
| 3067 |
|
| 3068 |
// Expects *foo to die after bar->A() and before bar->B(). |
| 3069 |
EXPECT_CALL(*bar, A()); |
| 3070 |
EXPECT_CALL(*foo, Die()); |
| 3071 |
EXPECT_CALL(*bar, B()); |
| 3072 |
} |
| 3073 |
``` |
| 3074 |
|
| 3075 |
And that's that. |
| 3076 |
|
| 3077 |
### Using gMock and Threads {#UsingThreads} |
| 3078 |
|
| 3079 |
In a **unit** test, it's best if you could isolate and test a piece of code in a |
| 3080 |
single-threaded context. That avoids race conditions and dead locks, and makes |
| 3081 |
debugging your test much easier. |
| 3082 |
|
| 3083 |
Yet most programs are multi-threaded, and sometimes to test something we need to |
| 3084 |
pound on it from more than one thread. gMock works for this purpose too. |
| 3085 |
|
| 3086 |
Remember the steps for using a mock: |
| 3087 |
|
| 3088 |
1. Create a mock object `foo`. |
| 3089 |
2. Set its default actions and expectations using `ON_CALL()` and |
| 3090 |
`EXPECT_CALL()`. |
| 3091 |
3. The code under test calls methods of `foo`. |
| 3092 |
4. Optionally, verify and reset the mock. |
| 3093 |
5. Destroy the mock yourself, or let the code under test destroy it. The |
| 3094 |
destructor will automatically verify it. |
| 3095 |
|
| 3096 |
If you follow the following simple rules, your mocks and threads can live |
| 3097 |
happily together: |
| 3098 |
|
| 3099 |
* Execute your *test code* (as opposed to the code being tested) in *one* |
| 3100 |
thread. This makes your test easy to follow. |
| 3101 |
* Obviously, you can do step #1 without locking. |
| 3102 |
* When doing step #2 and #5, make sure no other thread is accessing `foo`. |
| 3103 |
Obvious too, huh? |
| 3104 |
* #3 and #4 can be done either in one thread or in multiple threads - anyway |
| 3105 |
you want. gMock takes care of the locking, so you don't have to do any - |
| 3106 |
unless required by your test logic. |
| 3107 |
|
| 3108 |
If you violate the rules (for example, if you set expectations on a mock while |
| 3109 |
another thread is calling its methods), you get undefined behavior. That's not |
| 3110 |
fun, so don't do it. |
| 3111 |
|
| 3112 |
gMock guarantees that the action for a mock function is done in the same thread |
| 3113 |
that called the mock function. For example, in |
| 3114 |
|
| 3115 |
```cpp |
| 3116 |
EXPECT_CALL(mock, Foo(1)) |
| 3117 |
.WillOnce(action1); |
| 3118 |
EXPECT_CALL(mock, Foo(2)) |
| 3119 |
.WillOnce(action2); |
| 3120 |
``` |
| 3121 |
|
| 3122 |
if `Foo(1)` is called in thread 1 and `Foo(2)` is called in thread 2, gMock will |
| 3123 |
execute `action1` in thread 1 and `action2` in thread 2. |
| 3124 |
|
| 3125 |
gMock does *not* impose a sequence on actions performed in different threads |
| 3126 |
(doing so may create deadlocks as the actions may need to cooperate). This means |
| 3127 |
that the execution of `action1` and `action2` in the above example *may* |
| 3128 |
interleave. If this is a problem, you should add proper synchronization logic to |
| 3129 |
`action1` and `action2` to make the test thread-safe. |
| 3130 |
|
| 3131 |
Also, remember that `DefaultValue<T>` is a global resource that potentially |
| 3132 |
affects *all* living mock objects in your program. Naturally, you won't want to |
| 3133 |
mess with it from multiple threads or when there still are mocks in action. |
| 3134 |
|
| 3135 |
### Controlling How Much Information gMock Prints |
| 3136 |
|
| 3137 |
When gMock sees something that has the potential of being an error (e.g. a mock |
| 3138 |
function with no expectation is called, a.k.a. an uninteresting call, which is |
| 3139 |
allowed but perhaps you forgot to explicitly ban the call), it prints some |
| 3140 |
warning messages, including the arguments of the function, the return value, and |
| 3141 |
the stack trace. Hopefully this will remind you to take a look and see if there |
| 3142 |
is indeed a problem. |
| 3143 |
|
| 3144 |
Sometimes you are confident that your tests are correct and may not appreciate |
| 3145 |
such friendly messages. Some other times, you are debugging your tests or |
| 3146 |
learning about the behavior of the code you are testing, and wish you could |
| 3147 |
observe every mock call that happens (including argument values, the return |
| 3148 |
value, and the stack trace). Clearly, one size doesn't fit all. |
| 3149 |
|
| 3150 |
You can control how much gMock tells you using the `--gmock_verbose=LEVEL` |
| 3151 |
command-line flag, where `LEVEL` is a string with three possible values: |
| 3152 |
|
| 3153 |
* `info`: gMock will print all informational messages, warnings, and errors |
| 3154 |
(most verbose). At this setting, gMock will also log any calls to the |
| 3155 |
`ON_CALL/EXPECT_CALL` macros. It will include a stack trace in |
| 3156 |
"uninteresting call" warnings. |
| 3157 |
* `warning`: gMock will print both warnings and errors (less verbose); it will |
| 3158 |
omit the stack traces in "uninteresting call" warnings. This is the default. |
| 3159 |
* `error`: gMock will print errors only (least verbose). |
| 3160 |
|
| 3161 |
Alternatively, you can adjust the value of that flag from within your tests like |
| 3162 |
so: |
| 3163 |
|
| 3164 |
```cpp |
| 3165 |
::testing::FLAGS_gmock_verbose = "error"; |
| 3166 |
``` |
| 3167 |
|
| 3168 |
If you find gMock printing too many stack frames with its informational or |
| 3169 |
warning messages, remember that you can control their amount with the |
| 3170 |
`--gtest_stack_trace_depth=max_depth` flag. |
| 3171 |
|
| 3172 |
Now, judiciously use the right flag to enable gMock serve you better! |
| 3173 |
|
| 3174 |
### Gaining Super Vision into Mock Calls |
| 3175 |
|
| 3176 |
You have a test using gMock. It fails: gMock tells you some expectations aren't |
| 3177 |
satisfied. However, you aren't sure why: Is there a typo somewhere in the |
| 3178 |
matchers? Did you mess up the order of the `EXPECT_CALL`s? Or is the code under |
| 3179 |
test doing something wrong? How can you find out the cause? |
| 3180 |
|
| 3181 |
Won't it be nice if you have X-ray vision and can actually see the trace of all |
| 3182 |
`EXPECT_CALL`s and mock method calls as they are made? For each call, would you |
| 3183 |
like to see its actual argument values and which `EXPECT_CALL` gMock thinks it |
| 3184 |
matches? If you still need some help to figure out who made these calls, how |
| 3185 |
about being able to see the complete stack trace at each mock call? |
| 3186 |
|
| 3187 |
You can unlock this power by running your test with the `--gmock_verbose=info` |
| 3188 |
flag. For example, given the test program: |
| 3189 |
|
| 3190 |
```cpp |
| 3191 |
#include "gmock/gmock.h" |
| 3192 |
|
| 3193 |
using testing::_; |
| 3194 |
using testing::HasSubstr; |
| 3195 |
using testing::Return; |
| 3196 |
|
| 3197 |
class MockFoo { |
| 3198 |
public: |
| 3199 |
MOCK_METHOD(void, F, (const string& x, const string& y)); |
| 3200 |
}; |
| 3201 |
|
| 3202 |
TEST(Foo, Bar) { |
| 3203 |
MockFoo mock; |
| 3204 |
EXPECT_CALL(mock, F(_, _)).WillRepeatedly(Return()); |
| 3205 |
EXPECT_CALL(mock, F("a", "b")); |
| 3206 |
EXPECT_CALL(mock, F("c", HasSubstr("d"))); |
| 3207 |
|
| 3208 |
mock.F("a", "good"); |
| 3209 |
mock.F("a", "b"); |
| 3210 |
} |
| 3211 |
``` |
| 3212 |
|
| 3213 |
if you run it with `--gmock_verbose=info`, you will see this output: |
| 3214 |
|
| 3215 |
```shell |
| 3216 |
[ RUN ] Foo.Bar |
| 3217 |
|
| 3218 |
foo_test.cc:14: EXPECT_CALL(mock, F(_, _)) invoked |
| 3219 |
Stack trace: ... |
| 3220 |
|
| 3221 |
foo_test.cc:15: EXPECT_CALL(mock, F("a", "b")) invoked |
| 3222 |
Stack trace: ... |
| 3223 |
|
| 3224 |
foo_test.cc:16: EXPECT_CALL(mock, F("c", HasSubstr("d"))) invoked |
| 3225 |
Stack trace: ... |
| 3226 |
|
| 3227 |
foo_test.cc:14: Mock function call matches EXPECT_CALL(mock, F(_, _))... |
| 3228 |
Function call: F(@0x7fff7c8dad40"a",@0x7fff7c8dad10"good") |
| 3229 |
Stack trace: ... |
| 3230 |
|
| 3231 |
foo_test.cc:15: Mock function call matches EXPECT_CALL(mock, F("a", "b"))... |
| 3232 |
Function call: F(@0x7fff7c8dada0"a",@0x7fff7c8dad70"b") |
| 3233 |
Stack trace: ... |
| 3234 |
|
| 3235 |
foo_test.cc:16: Failure |
| 3236 |
Actual function call count doesn't match EXPECT_CALL(mock, F("c", HasSubstr("d")))... |
| 3237 |
Expected: to be called once |
| 3238 |
Actual: never called - unsatisfied and active |
| 3239 |
[ FAILED ] Foo.Bar |
| 3240 |
``` |
| 3241 |
|
| 3242 |
Suppose the bug is that the `"c"` in the third `EXPECT_CALL` is a typo and |
| 3243 |
should actually be `"a"`. With the above message, you should see that the actual |
| 3244 |
`F("a", "good")` call is matched by the first `EXPECT_CALL`, not the third as |
| 3245 |
you thought. From that it should be obvious that the third `EXPECT_CALL` is |
| 3246 |
written wrong. Case solved. |
| 3247 |
|
| 3248 |
If you are interested in the mock call trace but not the stack traces, you can |
| 3249 |
combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test |
| 3250 |
command line. |
| 3251 |
|
| 3252 |
### Running Tests in Emacs |
| 3253 |
|
| 3254 |
If you build and run your tests in Emacs using the `M-x google-compile` command |
| 3255 |
(as many googletest users do), the source file locations of gMock and googletest |
| 3256 |
errors will be highlighted. Just press `<Enter>` on one of them and you'll be |
| 3257 |
taken to the offending line. Or, you can just type `C-x`` to jump to the next |
| 3258 |
error. |
| 3259 |
|
| 3260 |
To make it even easier, you can add the following lines to your `~/.emacs` file: |
| 3261 |
|
| 3262 |
```text |
| 3263 |
(global-set-key "\M-m" 'google-compile) ; m is for make |
| 3264 |
(global-set-key [M-down] 'next-error) |
| 3265 |
(global-set-key [M-up] '(lambda () (interactive) (next-error -1))) |
| 3266 |
``` |
| 3267 |
|
| 3268 |
Then you can type `M-m` to start a build (if you want to run the test as well, |
| 3269 |
just make sure `foo_test.run` or `runtests` is in the build command you supply |
| 3270 |
after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors. |
| 3271 |
|
| 3272 |
## Extending gMock |
| 3273 |
|
| 3274 |
### Writing New Matchers Quickly {#NewMatchers} |
| 3275 |
|
| 3276 |
{: .callout .warning} |
| 3277 |
WARNING: gMock does not guarantee when or how many times a matcher will be |
| 3278 |
invoked. Therefore, all matchers must be functionally pure. See |
| 3279 |
[this section](#PureMatchers) for more details. |
| 3280 |
|
| 3281 |
The `MATCHER*` family of macros can be used to define custom matchers easily. |
| 3282 |
The syntax: |
| 3283 |
|
| 3284 |
```cpp |
| 3285 |
MATCHER(name, description_string_expression) { statements; } |
| 3286 |
``` |
| 3287 |
|
| 3288 |
will define a matcher with the given name that executes the statements, which |
| 3289 |
must return a `bool` to indicate if the match succeeds. Inside the statements, |
| 3290 |
you can refer to the value being matched by `arg`, and refer to its type by |
| 3291 |
`arg_type`. |
| 3292 |
|
| 3293 |
The *description string* is a `string`-typed expression that documents what the |
| 3294 |
matcher does, and is used to generate the failure message when the match fails. |
| 3295 |
It can (and should) reference the special `bool` variable `negation`, and should |
| 3296 |
evaluate to the description of the matcher when `negation` is `false`, or that |
| 3297 |
of the matcher's negation when `negation` is `true`. |
| 3298 |
|
| 3299 |
For convenience, we allow the description string to be empty (`""`), in which |
| 3300 |
case gMock will use the sequence of words in the matcher name as the |
| 3301 |
description. |
| 3302 |
|
| 3303 |
For example: |
| 3304 |
|
| 3305 |
```cpp |
| 3306 |
MATCHER(IsDivisibleBy7, "") { return (arg % 7) == 0; } |
| 3307 |
``` |
| 3308 |
|
| 3309 |
allows you to write |
| 3310 |
|
| 3311 |
```cpp |
| 3312 |
// Expects mock_foo.Bar(n) to be called where n is divisible by 7. |
| 3313 |
EXPECT_CALL(mock_foo, Bar(IsDivisibleBy7())); |
| 3314 |
``` |
| 3315 |
|
| 3316 |
or, |
| 3317 |
|
| 3318 |
```cpp |
| 3319 |
using ::testing::Not; |
| 3320 |
... |
| 3321 |
// Verifies that a value is divisible by 7 and the other is not. |
| 3322 |
EXPECT_THAT(some_expression, IsDivisibleBy7()); |
| 3323 |
EXPECT_THAT(some_other_expression, Not(IsDivisibleBy7())); |
| 3324 |
``` |
| 3325 |
|
| 3326 |
If the above assertions fail, they will print something like: |
| 3327 |
|
| 3328 |
```shell |
| 3329 |
Value of: some_expression |
| 3330 |
Expected: is divisible by 7 |
| 3331 |
Actual: 27 |
| 3332 |
... |
| 3333 |
Value of: some_other_expression |
| 3334 |
Expected: not (is divisible by 7) |
| 3335 |
Actual: 21 |
| 3336 |
``` |
| 3337 |
|
| 3338 |
where the descriptions `"is divisible by 7"` and `"not (is divisible by 7)"` are |
| 3339 |
automatically calculated from the matcher name `IsDivisibleBy7`. |
| 3340 |
|
| 3341 |
As you may have noticed, the auto-generated descriptions (especially those for |
| 3342 |
the negation) may not be so great. You can always override them with a `string` |
| 3343 |
expression of your own: |
| 3344 |
|
| 3345 |
```cpp |
| 3346 |
MATCHER(IsDivisibleBy7, |
| 3347 |
absl::StrCat(negation ? "isn't" : "is", " divisible by 7")) { |
| 3348 |
return (arg % 7) == 0; |
| 3349 |
} |
| 3350 |
``` |
| 3351 |
|
| 3352 |
Optionally, you can stream additional information to a hidden argument named |
| 3353 |
`result_listener` to explain the match result. For example, a better definition |
| 3354 |
of `IsDivisibleBy7` is: |
| 3355 |
|
| 3356 |
```cpp |
| 3357 |
MATCHER(IsDivisibleBy7, "") { |
| 3358 |
if ((arg % 7) == 0) |
| 3359 |
return true; |
| 3360 |
|
| 3361 |
*result_listener << "the remainder is " << (arg % 7); |
| 3362 |
return false; |
| 3363 |
} |
| 3364 |
``` |
| 3365 |
|
| 3366 |
With this definition, the above assertion will give a better message: |
| 3367 |
|
| 3368 |
```shell |
| 3369 |
Value of: some_expression |
| 3370 |
Expected: is divisible by 7 |
| 3371 |
Actual: 27 (the remainder is 6) |
| 3372 |
``` |
| 3373 |
|
| 3374 |
You should let `MatchAndExplain()` print *any additional information* that can |
| 3375 |
help a user understand the match result. Note that it should explain why the |
| 3376 |
match succeeds in case of a success (unless it's obvious) - this is useful when |
| 3377 |
the matcher is used inside `Not()`. There is no need to print the argument value |
| 3378 |
itself, as gMock already prints it for you. |
| 3379 |
|
| 3380 |
{: .callout .note} |
| 3381 |
NOTE: The type of the value being matched (`arg_type`) is determined by the |
| 3382 |
context in which you use the matcher and is supplied to you by the compiler, so |
| 3383 |
you don't need to worry about declaring it (nor can you). This allows the |
| 3384 |
matcher to be polymorphic. For example, `IsDivisibleBy7()` can be used to match |
| 3385 |
any type where the value of `(arg % 7) == 0` can be implicitly converted to a |
| 3386 |
`bool`. In the `Bar(IsDivisibleBy7())` example above, if method `Bar()` takes an |
| 3387 |
`int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will |
| 3388 |
be `unsigned long`; and so on. |
| 3389 |
|
| 3390 |
### Writing New Parameterized Matchers Quickly |
| 3391 |
|
| 3392 |
Sometimes you'll want to define a matcher that has parameters. For that you can |
| 3393 |
use the macro: |
| 3394 |
|
| 3395 |
```cpp |
| 3396 |
MATCHER_P(name, param_name, description_string) { statements; } |
| 3397 |
``` |
| 3398 |
|
| 3399 |
where the description string can be either `""` or a `string` expression that |
| 3400 |
references `negation` and `param_name`. |
| 3401 |
|
| 3402 |
For example: |
| 3403 |
|
| 3404 |
```cpp |
| 3405 |
MATCHER_P(HasAbsoluteValue, value, "") { return abs(arg) == value; } |
| 3406 |
``` |
| 3407 |
|
| 3408 |
will allow you to write: |
| 3409 |
|
| 3410 |
```cpp |
| 3411 |
EXPECT_THAT(Blah("a"), HasAbsoluteValue(n)); |
| 3412 |
``` |
| 3413 |
|
| 3414 |
which may lead to this message (assuming `n` is 10): |
| 3415 |
|
| 3416 |
```shell |
| 3417 |
Value of: Blah("a") |
| 3418 |
Expected: has absolute value 10 |
| 3419 |
Actual: -9 |
| 3420 |
``` |
| 3421 |
|
| 3422 |
Note that both the matcher description and its parameter are printed, making the |
| 3423 |
message human-friendly. |
| 3424 |
|
| 3425 |
In the matcher definition body, you can write `foo_type` to reference the type |
| 3426 |
of a parameter named `foo`. For example, in the body of |
| 3427 |
`MATCHER_P(HasAbsoluteValue, value)` above, you can write `value_type` to refer |
| 3428 |
to the type of `value`. |
| 3429 |
|
| 3430 |
gMock also provides `MATCHER_P2`, `MATCHER_P3`, ..., up to `MATCHER_P10` to |
| 3431 |
support multi-parameter matchers: |
| 3432 |
|
| 3433 |
```cpp |
| 3434 |
MATCHER_Pk(name, param_1, ..., param_k, description_string) { statements; } |
| 3435 |
``` |
| 3436 |
|
| 3437 |
Please note that the custom description string is for a particular *instance* of |
| 3438 |
the matcher, where the parameters have been bound to actual values. Therefore |
| 3439 |
usually you'll want the parameter values to be part of the description. gMock |
| 3440 |
lets you do that by referencing the matcher parameters in the description string |
| 3441 |
expression. |
| 3442 |
|
| 3443 |
For example, |
| 3444 |
|
| 3445 |
```cpp |
| 3446 |
using ::testing::PrintToString; |
| 3447 |
MATCHER_P2(InClosedRange, low, hi, |
| 3448 |
absl::StrFormat("%s in range [%s, %s]", negation ? "isn't" : "is", |
| 3449 |
PrintToString(low), PrintToString(hi))) { |
| 3450 |
return low <= arg && arg <= hi; |
| 3451 |
} |
| 3452 |
... |
| 3453 |
EXPECT_THAT(3, InClosedRange(4, 6)); |
| 3454 |
``` |
| 3455 |
|
| 3456 |
would generate a failure that contains the message: |
| 3457 |
|
| 3458 |
```shell |
| 3459 |
Expected: is in range [4, 6] |
| 3460 |
``` |
| 3461 |
|
| 3462 |
If you specify `""` as the description, the failure message will contain the |
| 3463 |
sequence of words in the matcher name followed by the parameter values printed |
| 3464 |
as a tuple. For example, |
| 3465 |
|
| 3466 |
```cpp |
| 3467 |
MATCHER_P2(InClosedRange, low, hi, "") { ... } |
| 3468 |
... |
| 3469 |
EXPECT_THAT(3, InClosedRange(4, 6)); |
| 3470 |
``` |
| 3471 |
|
| 3472 |
would generate a failure that contains the text: |
| 3473 |
|
| 3474 |
```shell |
| 3475 |
Expected: in closed range (4, 6) |
| 3476 |
``` |
| 3477 |
|
| 3478 |
For the purpose of typing, you can view |
| 3479 |
|
| 3480 |
```cpp |
| 3481 |
MATCHER_Pk(Foo, p1, ..., pk, description_string) { ... } |
| 3482 |
``` |
| 3483 |
|
| 3484 |
as shorthand for |
| 3485 |
|
| 3486 |
```cpp |
| 3487 |
template <typename p1_type, ..., typename pk_type> |
| 3488 |
FooMatcherPk<p1_type, ..., pk_type> |
| 3489 |
Foo(p1_type p1, ..., pk_type pk) { ... } |
| 3490 |
``` |
| 3491 |
|
| 3492 |
When you write `Foo(v1, ..., vk)`, the compiler infers the types of the |
| 3493 |
parameters `v1`, ..., and `vk` for you. If you are not happy with the result of |
| 3494 |
the type inference, you can specify the types by explicitly instantiating the |
| 3495 |
template, as in `Foo<long, bool>(5, false)`. As said earlier, you don't get to |
| 3496 |
(or need to) specify `arg_type` as that's determined by the context in which the |
| 3497 |
matcher is used. |
| 3498 |
|
| 3499 |
You can assign the result of expression `Foo(p1, ..., pk)` to a variable of type |
| 3500 |
`FooMatcherPk<p1_type, ..., pk_type>`. This can be useful when composing |
| 3501 |
matchers. Matchers that don't have a parameter or have only one parameter have |
| 3502 |
special types: you can assign `Foo()` to a `FooMatcher`-typed variable, and |
| 3503 |
assign `Foo(p)` to a `FooMatcherP<p_type>`-typed variable. |
| 3504 |
|
| 3505 |
While you can instantiate a matcher template with reference types, passing the |
| 3506 |
parameters by pointer usually makes your code more readable. If, however, you |
| 3507 |
still want to pass a parameter by reference, be aware that in the failure |
| 3508 |
message generated by the matcher you will see the value of the referenced object |
| 3509 |
but not its address. |
| 3510 |
|
| 3511 |
You can overload matchers with different numbers of parameters: |
| 3512 |
|
| 3513 |
```cpp |
| 3514 |
MATCHER_P(Blah, a, description_string_1) { ... } |
| 3515 |
MATCHER_P2(Blah, a, b, description_string_2) { ... } |
| 3516 |
``` |
| 3517 |
|
| 3518 |
While it's tempting to always use the `MATCHER*` macros when defining a new |
| 3519 |
matcher, you should also consider implementing the matcher interface directly |
| 3520 |
instead (see the recipes that follow), especially if you need to use the matcher |
| 3521 |
a lot. While these approaches require more work, they give you more control on |
| 3522 |
the types of the value being matched and the matcher parameters, which in |
| 3523 |
general leads to better compiler error messages that pay off in the long run. |
| 3524 |
They also allow overloading matchers based on parameter types (as opposed to |
| 3525 |
just based on the number of parameters). |
| 3526 |
|
| 3527 |
### Writing New Monomorphic Matchers |
| 3528 |
|
| 3529 |
A matcher of argument type `T` implements the matcher interface for `T` and does |
| 3530 |
two things: it tests whether a value of type `T` matches the matcher, and can |
| 3531 |
describe what kind of values it matches. The latter ability is used for |
| 3532 |
generating readable error messages when expectations are violated. |
| 3533 |
|
| 3534 |
A matcher of `T` must declare a typedef like: |
| 3535 |
|
| 3536 |
```cpp |
| 3537 |
using is_gtest_matcher = void; |
| 3538 |
``` |
| 3539 |
|
| 3540 |
and supports the following operations: |
| 3541 |
|
| 3542 |
```cpp |
| 3543 |
// Match a value and optionally explain into an ostream. |
| 3544 |
bool matched = matcher.MatchAndExplain(value, maybe_os); |
| 3545 |
// where `value` is of type `T` and |
| 3546 |
// `maybe_os` is of type `std::ostream*`, where it can be null if the caller |
| 3547 |
// is not interested in there textual explanation. |
| 3548 |
|
| 3549 |
matcher.DescribeTo(os); |
| 3550 |
matcher.DescribeNegationTo(os); |
| 3551 |
// where `os` is of type `std::ostream*`. |
| 3552 |
``` |
| 3553 |
|
| 3554 |
If you need a custom matcher but `Truly()` is not a good option (for example, |
| 3555 |
you may not be happy with the way `Truly(predicate)` describes itself, or you |
| 3556 |
may want your matcher to be polymorphic as `Eq(value)` is), you can define a |
| 3557 |
matcher to do whatever you want in two steps: first implement the matcher |
| 3558 |
interface, and then define a factory function to create a matcher instance. The |
| 3559 |
second step is not strictly needed but it makes the syntax of using the matcher |
| 3560 |
nicer. |
| 3561 |
|
| 3562 |
For example, you can define a matcher to test whether an `int` is divisible by 7 |
| 3563 |
and then use it like this: |
| 3564 |
|
| 3565 |
```cpp |
| 3566 |
using ::testing::Matcher; |
| 3567 |
|
| 3568 |
class DivisibleBy7Matcher { |
| 3569 |
public: |
| 3570 |
using is_gtest_matcher = void; |
| 3571 |
|
| 3572 |
bool MatchAndExplain(int n, std::ostream*) const { |
| 3573 |
return (n % 7) == 0; |
| 3574 |
} |
| 3575 |
|
| 3576 |
void DescribeTo(std::ostream* os) const { |
| 3577 |
*os << "is divisible by 7"; |
| 3578 |
} |
| 3579 |
|
| 3580 |
void DescribeNegationTo(std::ostream* os) const { |
| 3581 |
*os << "is not divisible by 7"; |
| 3582 |
} |
| 3583 |
}; |
| 3584 |
|
| 3585 |
Matcher<int> DivisibleBy7() { |
| 3586 |
return DivisibleBy7Matcher(); |
| 3587 |
} |
| 3588 |
|
| 3589 |
... |
| 3590 |
EXPECT_CALL(foo, Bar(DivisibleBy7())); |
| 3591 |
``` |
| 3592 |
|
| 3593 |
You may improve the matcher message by streaming additional information to the |
| 3594 |
`os` argument in `MatchAndExplain()`: |
| 3595 |
|
| 3596 |
```cpp |
| 3597 |
class DivisibleBy7Matcher { |
| 3598 |
public: |
| 3599 |
bool MatchAndExplain(int n, std::ostream* os) const { |
| 3600 |
const int remainder = n % 7; |
| 3601 |
if (remainder != 0 && os != nullptr) { |
| 3602 |
*os << "the remainder is " << remainder; |
| 3603 |
} |
| 3604 |
return remainder == 0; |
| 3605 |
} |
| 3606 |
... |
| 3607 |
}; |
| 3608 |
``` |
| 3609 |
|
| 3610 |
Then, `EXPECT_THAT(x, DivisibleBy7());` may generate a message like this: |
| 3611 |
|
| 3612 |
```shell |
| 3613 |
Value of: x |
| 3614 |
Expected: is divisible by 7 |
| 3615 |
Actual: 23 (the remainder is 2) |
| 3616 |
``` |
| 3617 |
|
| 3618 |
{: .callout .tip} |
| 3619 |
Tip: for convenience, `MatchAndExplain()` can take a `MatchResultListener*` |
| 3620 |
instead of `std::ostream*`. |
| 3621 |
|
| 3622 |
### Writing New Polymorphic Matchers |
| 3623 |
|
| 3624 |
Expanding what we learned above to *polymorphic* matchers is now just as simple |
| 3625 |
as adding templates in the right place. |
| 3626 |
|
| 3627 |
```cpp |
| 3628 |
|
| 3629 |
class NotNullMatcher { |
| 3630 |
public: |
| 3631 |
using is_gtest_matcher = void; |
| 3632 |
|
| 3633 |
// To implement a polymorphic matcher, we just need to make MatchAndExplain a |
| 3634 |
// template on its first argument. |
| 3635 |
|
| 3636 |
// In this example, we want to use NotNull() with any pointer, so |
| 3637 |
// MatchAndExplain() accepts a pointer of any type as its first argument. |
| 3638 |
// In general, you can define MatchAndExplain() as an ordinary method or |
| 3639 |
// a method template, or even overload it. |
| 3640 |
template <typename T> |
| 3641 |
bool MatchAndExplain(T* p, std::ostream*) const { |
| 3642 |
return p != nullptr; |
| 3643 |
} |
| 3644 |
|
| 3645 |
// Describes the property of a value matching this matcher. |
| 3646 |
void DescribeTo(std::ostream* os) const { *os << "is not NULL"; } |
| 3647 |
|
| 3648 |
// Describes the property of a value NOT matching this matcher. |
| 3649 |
void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; } |
| 3650 |
}; |
| 3651 |
|
| 3652 |
NotNullMatcher NotNull() { |
| 3653 |
return NotNullMatcher(); |
| 3654 |
} |
| 3655 |
|
| 3656 |
... |
| 3657 |
|
| 3658 |
EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer. |
| 3659 |
``` |
| 3660 |
|
| 3661 |
### Legacy Matcher Implementation |
| 3662 |
|
| 3663 |
Defining matchers used to be somewhat more complicated, in which it required |
| 3664 |
several supporting classes and virtual functions. To implement a matcher for |
| 3665 |
type `T` using the legacy API you have to derive from `MatcherInterface<T>` and |
| 3666 |
call `MakeMatcher` to construct the object. |
| 3667 |
|
| 3668 |
The interface looks like this: |
| 3669 |
|
| 3670 |
```cpp |
| 3671 |
class MatchResultListener { |
| 3672 |
public: |
| 3673 |
... |
| 3674 |
// Streams x to the underlying ostream; does nothing if the ostream |
| 3675 |
// is NULL. |
| 3676 |
template <typename T> |
| 3677 |
MatchResultListener& operator<<(const T& x); |
| 3678 |
|
| 3679 |
// Returns the underlying ostream. |
| 3680 |
std::ostream* stream(); |
| 3681 |
}; |
| 3682 |
|
| 3683 |
template <typename T> |
| 3684 |
class MatcherInterface { |
| 3685 |
public: |
| 3686 |
virtual ~MatcherInterface(); |
| 3687 |
|
| 3688 |
// Returns true if and only if the matcher matches x; also explains the match |
| 3689 |
// result to 'listener'. |
| 3690 |
virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0; |
| 3691 |
|
| 3692 |
// Describes this matcher to an ostream. |
| 3693 |
virtual void DescribeTo(std::ostream* os) const = 0; |
| 3694 |
|
| 3695 |
// Describes the negation of this matcher to an ostream. |
| 3696 |
virtual void DescribeNegationTo(std::ostream* os) const; |
| 3697 |
}; |
| 3698 |
``` |
| 3699 |
|
| 3700 |
Fortunately, most of the time you can define a polymorphic matcher easily with |
| 3701 |
the help of `MakePolymorphicMatcher()`. Here's how you can define `NotNull()` as |
| 3702 |
an example: |
| 3703 |
|
| 3704 |
```cpp |
| 3705 |
using ::testing::MakePolymorphicMatcher; |
| 3706 |
using ::testing::MatchResultListener; |
| 3707 |
using ::testing::PolymorphicMatcher; |
| 3708 |
|
| 3709 |
class NotNullMatcher { |
| 3710 |
public: |
| 3711 |
// To implement a polymorphic matcher, first define a COPYABLE class |
| 3712 |
// that has three members MatchAndExplain(), DescribeTo(), and |
| 3713 |
// DescribeNegationTo(), like the following. |
| 3714 |
|
| 3715 |
// In this example, we want to use NotNull() with any pointer, so |
| 3716 |
// MatchAndExplain() accepts a pointer of any type as its first argument. |
| 3717 |
// In general, you can define MatchAndExplain() as an ordinary method or |
| 3718 |
// a method template, or even overload it. |
| 3719 |
template <typename T> |
| 3720 |
bool MatchAndExplain(T* p, |
| 3721 |
MatchResultListener* /* listener */) const { |
| 3722 |
return p != NULL; |
| 3723 |
} |
| 3724 |
|
| 3725 |
// Describes the property of a value matching this matcher. |
| 3726 |
void DescribeTo(std::ostream* os) const { *os << "is not NULL"; } |
| 3727 |
|
| 3728 |
// Describes the property of a value NOT matching this matcher. |
| 3729 |
void DescribeNegationTo(std::ostream* os) const { *os << "is NULL"; } |
| 3730 |
}; |
| 3731 |
|
| 3732 |
// To construct a polymorphic matcher, pass an instance of the class |
| 3733 |
// to MakePolymorphicMatcher(). Note the return type. |
| 3734 |
PolymorphicMatcher<NotNullMatcher> NotNull() { |
| 3735 |
return MakePolymorphicMatcher(NotNullMatcher()); |
| 3736 |
} |
| 3737 |
|
| 3738 |
... |
| 3739 |
|
| 3740 |
EXPECT_CALL(foo, Bar(NotNull())); // The argument must be a non-NULL pointer. |
| 3741 |
``` |
| 3742 |
|
| 3743 |
{: .callout .note} |
| 3744 |
**Note:** Your polymorphic matcher class does **not** need to inherit from |
| 3745 |
`MatcherInterface` or any other class, and its methods do **not** need to be |
| 3746 |
virtual. |
| 3747 |
|
| 3748 |
Like in a monomorphic matcher, you may explain the match result by streaming |
| 3749 |
additional information to the `listener` argument in `MatchAndExplain()`. |
| 3750 |
|
| 3751 |
### Writing New Cardinalities |
| 3752 |
|
| 3753 |
A cardinality is used in `Times()` to tell gMock how many times you expect a |
| 3754 |
call to occur. It doesn't have to be exact. For example, you can say |
| 3755 |
`AtLeast(5)` or `Between(2, 4)`. |
| 3756 |
|
| 3757 |
If the [built-in set](gmock_cheat_sheet.md#CardinalityList) of cardinalities |
| 3758 |
doesn't suit you, you are free to define your own by implementing the following |
| 3759 |
interface (in namespace `testing`): |
| 3760 |
|
| 3761 |
```cpp |
| 3762 |
class CardinalityInterface { |
| 3763 |
public: |
| 3764 |
virtual ~CardinalityInterface(); |
| 3765 |
|
| 3766 |
// Returns true if and only if call_count calls will satisfy this cardinality. |
| 3767 |
virtual bool IsSatisfiedByCallCount(int call_count) const = 0; |
| 3768 |
|
| 3769 |
// Returns true if and only if call_count calls will saturate this |
| 3770 |
// cardinality. |
| 3771 |
virtual bool IsSaturatedByCallCount(int call_count) const = 0; |
| 3772 |
|
| 3773 |
// Describes self to an ostream. |
| 3774 |
virtual void DescribeTo(std::ostream* os) const = 0; |
| 3775 |
}; |
| 3776 |
``` |
| 3777 |
|
| 3778 |
For example, to specify that a call must occur even number of times, you can |
| 3779 |
write |
| 3780 |
|
| 3781 |
```cpp |
| 3782 |
using ::testing::Cardinality; |
| 3783 |
using ::testing::CardinalityInterface; |
| 3784 |
using ::testing::MakeCardinality; |
| 3785 |
|
| 3786 |
class EvenNumberCardinality : public CardinalityInterface { |
| 3787 |
public: |
| 3788 |
bool IsSatisfiedByCallCount(int call_count) const override { |
| 3789 |
return (call_count % 2) == 0; |
| 3790 |
} |
| 3791 |
|
| 3792 |
bool IsSaturatedByCallCount(int call_count) const override { |
| 3793 |
return false; |
| 3794 |
} |
| 3795 |
|
| 3796 |
void DescribeTo(std::ostream* os) const { |
| 3797 |
*os << "called even number of times"; |
| 3798 |
} |
| 3799 |
}; |
| 3800 |
|
| 3801 |
Cardinality EvenNumber() { |
| 3802 |
return MakeCardinality(new EvenNumberCardinality); |
| 3803 |
} |
| 3804 |
|
| 3805 |
... |
| 3806 |
EXPECT_CALL(foo, Bar(3)) |
| 3807 |
.Times(EvenNumber()); |
| 3808 |
``` |
| 3809 |
|
| 3810 |
### Writing New Actions Quickly {#QuickNewActions} |
| 3811 |
|
| 3812 |
If the built-in actions don't work for you, you can easily define your own one. |
| 3813 |
Just define a functor class with a (possibly templated) call operator, matching |
| 3814 |
the signature of your action. |
| 3815 |
|
| 3816 |
```cpp |
| 3817 |
struct Increment { |
| 3818 |
template <typename T> |
| 3819 |
T operator()(T* arg) { |
| 3820 |
return ++(*arg); |
| 3821 |
} |
| 3822 |
} |
| 3823 |
``` |
| 3824 |
|
| 3825 |
The same approach works with stateful functors (or any callable, really): |
| 3826 |
|
| 3827 |
``` |
| 3828 |
struct MultiplyBy { |
| 3829 |
template <typename T> |
| 3830 |
T operator()(T arg) { return arg * multiplier; } |
| 3831 |
|
| 3832 |
int multiplier; |
| 3833 |
} |
| 3834 |
|
| 3835 |
// Then use: |
| 3836 |
// EXPECT_CALL(...).WillOnce(MultiplyBy{7}); |
| 3837 |
``` |
| 3838 |
|
| 3839 |
#### Legacy macro-based Actions |
| 3840 |
|
| 3841 |
Before C++11, the functor-based actions were not supported; the old way of |
| 3842 |
writing actions was through a set of `ACTION*` macros. We suggest to avoid them |
| 3843 |
in new code; they hide a lot of logic behind the macro, potentially leading to |
| 3844 |
harder-to-understand compiler errors. Nevertheless, we cover them here for |
| 3845 |
completeness. |
| 3846 |
|
| 3847 |
By writing |
| 3848 |
|
| 3849 |
```cpp |
| 3850 |
ACTION(name) { statements; } |
| 3851 |
``` |
| 3852 |
|
| 3853 |
in a namespace scope (i.e. not inside a class or function), you will define an |
| 3854 |
action with the given name that executes the statements. The value returned by |
| 3855 |
`statements` will be used as the return value of the action. Inside the |
| 3856 |
statements, you can refer to the K-th (0-based) argument of the mock function as |
| 3857 |
`argK`. For example: |
| 3858 |
|
| 3859 |
```cpp |
| 3860 |
ACTION(IncrementArg1) { return ++(*arg1); } |
| 3861 |
``` |
| 3862 |
|
| 3863 |
allows you to write |
| 3864 |
|
| 3865 |
```cpp |
| 3866 |
... WillOnce(IncrementArg1()); |
| 3867 |
``` |
| 3868 |
|
| 3869 |
Note that you don't need to specify the types of the mock function arguments. |
| 3870 |
Rest assured that your code is type-safe though: you'll get a compiler error if |
| 3871 |
`*arg1` doesn't support the `++` operator, or if the type of `++(*arg1)` isn't |
| 3872 |
compatible with the mock function's return type. |
| 3873 |
|
| 3874 |
Another example: |
| 3875 |
|
| 3876 |
```cpp |
| 3877 |
ACTION(Foo) { |
| 3878 |
(*arg2)(5); |
| 3879 |
Blah(); |
| 3880 |
*arg1 = 0; |
| 3881 |
return arg0; |
| 3882 |
} |
| 3883 |
``` |
| 3884 |
|
| 3885 |
defines an action `Foo()` that invokes argument #2 (a function pointer) with 5, |
| 3886 |
calls function `Blah()`, sets the value pointed to by argument #1 to 0, and |
| 3887 |
returns argument #0. |
| 3888 |
|
| 3889 |
For more convenience and flexibility, you can also use the following pre-defined |
| 3890 |
symbols in the body of `ACTION`: |
| 3891 |
|
| 3892 |
`argK_type` | The type of the K-th (0-based) argument of the mock function |
| 3893 |
:-------------- | :----------------------------------------------------------- |
| 3894 |
`args` | All arguments of the mock function as a tuple |
| 3895 |
`args_type` | The type of all arguments of the mock function as a tuple |
| 3896 |
`return_type` | The return type of the mock function |
| 3897 |
`function_type` | The type of the mock function |
| 3898 |
|
| 3899 |
For example, when using an `ACTION` as a stub action for mock function: |
| 3900 |
|
| 3901 |
```cpp |
| 3902 |
int DoSomething(bool flag, int* ptr); |
| 3903 |
``` |
| 3904 |
|
| 3905 |
we have: |
| 3906 |
|
| 3907 |
Pre-defined Symbol | Is Bound To |
| 3908 |
------------------ | --------------------------------- |
| 3909 |
`arg0` | the value of `flag` |
| 3910 |
`arg0_type` | the type `bool` |
| 3911 |
`arg1` | the value of `ptr` |
| 3912 |
`arg1_type` | the type `int*` |
| 3913 |
`args` | the tuple `(flag, ptr)` |
| 3914 |
`args_type` | the type `std::tuple<bool, int*>` |
| 3915 |
`return_type` | the type `int` |
| 3916 |
`function_type` | the type `int(bool, int*)` |
| 3917 |
|
| 3918 |
#### Legacy macro-based parameterized Actions |
| 3919 |
|
| 3920 |
Sometimes you'll want to parameterize an action you define. For that we have |
| 3921 |
another macro |
| 3922 |
|
| 3923 |
```cpp |
| 3924 |
ACTION_P(name, param) { statements; } |
| 3925 |
``` |
| 3926 |
|
| 3927 |
For example, |
| 3928 |
|
| 3929 |
```cpp |
| 3930 |
ACTION_P(Add, n) { return arg0 + n; } |
| 3931 |
``` |
| 3932 |
|
| 3933 |
will allow you to write |
| 3934 |
|
| 3935 |
```cpp |
| 3936 |
// Returns argument #0 + 5. |
| 3937 |
... WillOnce(Add(5)); |
| 3938 |
``` |
| 3939 |
|
| 3940 |
For convenience, we use the term *arguments* for the values used to invoke the |
| 3941 |
mock function, and the term *parameters* for the values used to instantiate an |
| 3942 |
action. |
| 3943 |
|
| 3944 |
Note that you don't need to provide the type of the parameter either. Suppose |
| 3945 |
the parameter is named `param`, you can also use the gMock-defined symbol |
| 3946 |
`param_type` to refer to the type of the parameter as inferred by the compiler. |
| 3947 |
For example, in the body of `ACTION_P(Add, n)` above, you can write `n_type` for |
| 3948 |
the type of `n`. |
| 3949 |
|
| 3950 |
gMock also provides `ACTION_P2`, `ACTION_P3`, and etc to support multi-parameter |
| 3951 |
actions. For example, |
| 3952 |
|
| 3953 |
```cpp |
| 3954 |
ACTION_P2(ReturnDistanceTo, x, y) { |
| 3955 |
double dx = arg0 - x; |
| 3956 |
double dy = arg1 - y; |
| 3957 |
return sqrt(dx*dx + dy*dy); |
| 3958 |
} |
| 3959 |
``` |
| 3960 |
|
| 3961 |
lets you write |
| 3962 |
|
| 3963 |
```cpp |
| 3964 |
... WillOnce(ReturnDistanceTo(5.0, 26.5)); |
| 3965 |
``` |
| 3966 |
|
| 3967 |
You can view `ACTION` as a degenerated parameterized action where the number of |
| 3968 |
parameters is 0. |
| 3969 |
|
| 3970 |
You can also easily define actions overloaded on the number of parameters: |
| 3971 |
|
| 3972 |
```cpp |
| 3973 |
ACTION_P(Plus, a) { ... } |
| 3974 |
ACTION_P2(Plus, a, b) { ... } |
| 3975 |
``` |
| 3976 |
|
| 3977 |
### Restricting the Type of an Argument or Parameter in an ACTION |
| 3978 |
|
| 3979 |
For maximum brevity and reusability, the `ACTION*` macros don't ask you to |
| 3980 |
provide the types of the mock function arguments and the action parameters. |
| 3981 |
Instead, we let the compiler infer the types for us. |
| 3982 |
|
| 3983 |
Sometimes, however, we may want to be more explicit about the types. There are |
| 3984 |
several tricks to do that. For example: |
| 3985 |
|
| 3986 |
```cpp |
| 3987 |
ACTION(Foo) { |
| 3988 |
// Makes sure arg0 can be converted to int. |
| 3989 |
int n = arg0; |
| 3990 |
... use n instead of arg0 here ... |
| 3991 |
} |
| 3992 |
|
| 3993 |
ACTION_P(Bar, param) { |
| 3994 |
// Makes sure the type of arg1 is const char*. |
| 3995 |
::testing::StaticAssertTypeEq<const char*, arg1_type>(); |
| 3996 |
|
| 3997 |
// Makes sure param can be converted to bool. |
| 3998 |
bool flag = param; |
| 3999 |
} |
| 4000 |
``` |
| 4001 |
|
| 4002 |
where `StaticAssertTypeEq` is a compile-time assertion in googletest that |
| 4003 |
verifies two types are the same. |
| 4004 |
|
| 4005 |
### Writing New Action Templates Quickly |
| 4006 |
|
| 4007 |
Sometimes you want to give an action explicit template parameters that cannot be |
| 4008 |
inferred from its value parameters. `ACTION_TEMPLATE()` supports that and can be |
| 4009 |
viewed as an extension to `ACTION()` and `ACTION_P*()`. |
| 4010 |
|
| 4011 |
The syntax: |
| 4012 |
|
| 4013 |
```cpp |
| 4014 |
ACTION_TEMPLATE(ActionName, |
| 4015 |
HAS_m_TEMPLATE_PARAMS(kind1, name1, ..., kind_m, name_m), |
| 4016 |
AND_n_VALUE_PARAMS(p1, ..., p_n)) { statements; } |
| 4017 |
``` |
| 4018 |
|
| 4019 |
defines an action template that takes *m* explicit template parameters and *n* |
| 4020 |
value parameters, where *m* is in [1, 10] and *n* is in [0, 10]. `name_i` is the |
| 4021 |
name of the *i*-th template parameter, and `kind_i` specifies whether it's a |
| 4022 |
`typename`, an integral constant, or a template. `p_i` is the name of the *i*-th |
| 4023 |
value parameter. |
| 4024 |
|
| 4025 |
Example: |
| 4026 |
|
| 4027 |
```cpp |
| 4028 |
// DuplicateArg<k, T>(output) converts the k-th argument of the mock |
| 4029 |
// function to type T and copies it to *output. |
| 4030 |
ACTION_TEMPLATE(DuplicateArg, |
| 4031 |
// Note the comma between int and k: |
| 4032 |
HAS_2_TEMPLATE_PARAMS(int, k, typename, T), |
| 4033 |
AND_1_VALUE_PARAMS(output)) { |
| 4034 |
*output = T(std::get<k>(args)); |
| 4035 |
} |
| 4036 |
``` |
| 4037 |
|
| 4038 |
To create an instance of an action template, write: |
| 4039 |
|
| 4040 |
```cpp |
| 4041 |
ActionName<t1, ..., t_m>(v1, ..., v_n) |
| 4042 |
``` |
| 4043 |
|
| 4044 |
where the `t`s are the template arguments and the `v`s are the value arguments. |
| 4045 |
The value argument types are inferred by the compiler. For example: |
| 4046 |
|
| 4047 |
```cpp |
| 4048 |
using ::testing::_; |
| 4049 |
... |
| 4050 |
int n; |
| 4051 |
EXPECT_CALL(mock, Foo).WillOnce(DuplicateArg<1, unsigned char>(&n)); |
| 4052 |
``` |
| 4053 |
|
| 4054 |
If you want to explicitly specify the value argument types, you can provide |
| 4055 |
additional template arguments: |
| 4056 |
|
| 4057 |
```cpp |
| 4058 |
ActionName<t1, ..., t_m, u1, ..., u_k>(v1, ..., v_n) |
| 4059 |
``` |
| 4060 |
|
| 4061 |
where `u_i` is the desired type of `v_i`. |
| 4062 |
|
| 4063 |
`ACTION_TEMPLATE` and `ACTION`/`ACTION_P*` can be overloaded on the number of |
| 4064 |
value parameters, but not on the number of template parameters. Without the |
| 4065 |
restriction, the meaning of the following is unclear: |
| 4066 |
|
| 4067 |
```cpp |
| 4068 |
OverloadedAction<int, bool>(x); |
| 4069 |
``` |
| 4070 |
|
| 4071 |
Are we using a single-template-parameter action where `bool` refers to the type |
| 4072 |
of `x`, or a two-template-parameter action where the compiler is asked to infer |
| 4073 |
the type of `x`? |
| 4074 |
|
| 4075 |
### Using the ACTION Object's Type |
| 4076 |
|
| 4077 |
If you are writing a function that returns an `ACTION` object, you'll need to |
| 4078 |
know its type. The type depends on the macro used to define the action and the |
| 4079 |
parameter types. The rule is relatively simple: |
| 4080 |
|
| 4081 |
|
| 4082 |
| Given Definition | Expression | Has Type | |
| 4083 |
| ----------------------------- | ------------------- | --------------------- | |
| 4084 |
| `ACTION(Foo)` | `Foo()` | `FooAction` | |
| 4085 |
| `ACTION_TEMPLATE(Foo, HAS_m_TEMPLATE_PARAMS(...), AND_0_VALUE_PARAMS())` | `Foo<t1, ..., t_m>()` | `FooAction<t1, ..., t_m>` | |
| 4086 |
| `ACTION_P(Bar, param)` | `Bar(int_value)` | `BarActionP<int>` | |
| 4087 |
| `ACTION_TEMPLATE(Bar, HAS_m_TEMPLATE_PARAMS(...), AND_1_VALUE_PARAMS(p1))` | `Bar<t1, ..., t_m>(int_value)` | `BarActionP<t1, ..., t_m, int>` | |
| 4088 |
| `ACTION_P2(Baz, p1, p2)` | `Baz(bool_value, int_value)` | `BazActionP2<bool, int>` | |
| 4089 |
| `ACTION_TEMPLATE(Baz, HAS_m_TEMPLATE_PARAMS(...), AND_2_VALUE_PARAMS(p1, p2))` | `Baz<t1, ..., t_m>(bool_value, int_value)` | `BazActionP2<t1, ..., t_m, bool, int>` | |
| 4090 |
| ... | ... | ... | |
| 4091 |
|
| 4092 |
|
| 4093 |
Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`, |
| 4094 |
and etc) for actions with different numbers of value parameters, or the action |
| 4095 |
definitions cannot be overloaded on the number of them. |
| 4096 |
|
| 4097 |
### Writing New Monomorphic Actions {#NewMonoActions} |
| 4098 |
|
| 4099 |
While the `ACTION*` macros are very convenient, sometimes they are |
| 4100 |
inappropriate. For example, despite the tricks shown in the previous recipes, |
| 4101 |
they don't let you directly specify the types of the mock function arguments and |
| 4102 |
the action parameters, which in general leads to unoptimized compiler error |
| 4103 |
messages that can baffle unfamiliar users. They also don't allow overloading |
| 4104 |
actions based on parameter types without jumping through some hoops. |
| 4105 |
|
| 4106 |
An alternative to the `ACTION*` macros is to implement |
| 4107 |
`::testing::ActionInterface<F>`, where `F` is the type of the mock function in |
| 4108 |
which the action will be used. For example: |
| 4109 |
|
| 4110 |
```cpp |
| 4111 |
template <typename F> |
| 4112 |
class ActionInterface { |
| 4113 |
public: |
| 4114 |
virtual ~ActionInterface(); |
| 4115 |
|
| 4116 |
// Performs the action. Result is the return type of function type |
| 4117 |
// F, and ArgumentTuple is the tuple of arguments of F. |
| 4118 |
// |
| 4119 |
|
| 4120 |
// For example, if F is int(bool, const string&), then Result would |
| 4121 |
// be int, and ArgumentTuple would be std::tuple<bool, const string&>. |
| 4122 |
virtual Result Perform(const ArgumentTuple& args) = 0; |
| 4123 |
}; |
| 4124 |
``` |
| 4125 |
|
| 4126 |
```cpp |
| 4127 |
using ::testing::_; |
| 4128 |
using ::testing::Action; |
| 4129 |
using ::testing::ActionInterface; |
| 4130 |
using ::testing::MakeAction; |
| 4131 |
|
| 4132 |
typedef int IncrementMethod(int*); |
| 4133 |
|
| 4134 |
class IncrementArgumentAction : public ActionInterface<IncrementMethod> { |
| 4135 |
public: |
| 4136 |
int Perform(const std::tuple<int*>& args) override { |
| 4137 |
int* p = std::get<0>(args); // Grabs the first argument. |
| 4138 |
return *p++; |
| 4139 |
} |
| 4140 |
}; |
| 4141 |
|
| 4142 |
Action<IncrementMethod> IncrementArgument() { |
| 4143 |
return MakeAction(new IncrementArgumentAction); |
| 4144 |
} |
| 4145 |
|
| 4146 |
... |
| 4147 |
EXPECT_CALL(foo, Baz(_)) |
| 4148 |
.WillOnce(IncrementArgument()); |
| 4149 |
|
| 4150 |
int n = 5; |
| 4151 |
foo.Baz(&n); // Should return 5 and change n to 6. |
| 4152 |
``` |
| 4153 |
|
| 4154 |
### Writing New Polymorphic Actions {#NewPolyActions} |
| 4155 |
|
| 4156 |
The previous recipe showed you how to define your own action. This is all good, |
| 4157 |
except that you need to know the type of the function in which the action will |
| 4158 |
be used. Sometimes that can be a problem. For example, if you want to use the |
| 4159 |
action in functions with *different* types (e.g. like `Return()` and |
| 4160 |
`SetArgPointee()`). |
| 4161 |
|
| 4162 |
If an action can be used in several types of mock functions, we say it's |
| 4163 |
*polymorphic*. The `MakePolymorphicAction()` function template makes it easy to |
| 4164 |
define such an action: |
| 4165 |
|
| 4166 |
```cpp |
| 4167 |
namespace testing { |
| 4168 |
template <typename Impl> |
| 4169 |
PolymorphicAction<Impl> MakePolymorphicAction(const Impl& impl); |
| 4170 |
} // namespace testing |
| 4171 |
``` |
| 4172 |
|
| 4173 |
As an example, let's define an action that returns the second argument in the |
| 4174 |
mock function's argument list. The first step is to define an implementation |
| 4175 |
class: |
| 4176 |
|
| 4177 |
```cpp |
| 4178 |
class ReturnSecondArgumentAction { |
| 4179 |
public: |
| 4180 |
template <typename Result, typename ArgumentTuple> |
| 4181 |
Result Perform(const ArgumentTuple& args) const { |
| 4182 |
// To get the i-th (0-based) argument, use std::get(args). |
| 4183 |
return std::get<1>(args); |
| 4184 |
} |
| 4185 |
}; |
| 4186 |
``` |
| 4187 |
|
| 4188 |
This implementation class does *not* need to inherit from any particular class. |
| 4189 |
What matters is that it must have a `Perform()` method template. This method |
| 4190 |
template takes the mock function's arguments as a tuple in a **single** |
| 4191 |
argument, and returns the result of the action. It can be either `const` or not, |
| 4192 |
but must be invocable with exactly one template argument, which is the result |
| 4193 |
type. In other words, you must be able to call `Perform<R>(args)` where `R` is |
| 4194 |
the mock function's return type and `args` is its arguments in a tuple. |
| 4195 |
|
| 4196 |
Next, we use `MakePolymorphicAction()` to turn an instance of the implementation |
| 4197 |
class into the polymorphic action we need. It will be convenient to have a |
| 4198 |
wrapper for this: |
| 4199 |
|
| 4200 |
```cpp |
| 4201 |
using ::testing::MakePolymorphicAction; |
| 4202 |
using ::testing::PolymorphicAction; |
| 4203 |
|
| 4204 |
PolymorphicAction<ReturnSecondArgumentAction> ReturnSecondArgument() { |
| 4205 |
return MakePolymorphicAction(ReturnSecondArgumentAction()); |
| 4206 |
} |
| 4207 |
``` |
| 4208 |
|
| 4209 |
Now, you can use this polymorphic action the same way you use the built-in ones: |
| 4210 |
|
| 4211 |
```cpp |
| 4212 |
using ::testing::_; |
| 4213 |
|
| 4214 |
class MockFoo : public Foo { |
| 4215 |
public: |
| 4216 |
MOCK_METHOD(int, DoThis, (bool flag, int n), (override)); |
| 4217 |
MOCK_METHOD(string, DoThat, (int x, const char* str1, const char* str2), |
| 4218 |
(override)); |
| 4219 |
}; |
| 4220 |
|
| 4221 |
... |
| 4222 |
MockFoo foo; |
| 4223 |
EXPECT_CALL(foo, DoThis).WillOnce(ReturnSecondArgument()); |
| 4224 |
EXPECT_CALL(foo, DoThat).WillOnce(ReturnSecondArgument()); |
| 4225 |
... |
| 4226 |
foo.DoThis(true, 5); // Will return 5. |
| 4227 |
foo.DoThat(1, "Hi", "Bye"); // Will return "Hi". |
| 4228 |
``` |
| 4229 |
|
| 4230 |
### Teaching gMock How to Print Your Values |
| 4231 |
|
| 4232 |
When an uninteresting or unexpected call occurs, gMock prints the argument |
| 4233 |
values and the stack trace to help you debug. Assertion macros like |
| 4234 |
`EXPECT_THAT` and `EXPECT_EQ` also print the values in question when the |
| 4235 |
assertion fails. gMock and googletest do this using googletest's user-extensible |
| 4236 |
value printer. |
| 4237 |
|
| 4238 |
This printer knows how to print built-in C++ types, native arrays, STL |
| 4239 |
containers, and any type that supports the `<<` operator. For other types, it |
| 4240 |
prints the raw bytes in the value and hopes that you the user can figure it out. |
| 4241 |
[The GoogleTest advanced guide](advanced.md#teaching-googletest-how-to-print-your-values) |
| 4242 |
explains how to extend the printer to do a better job at printing your |
| 4243 |
particular type than to dump the bytes. |
| 4244 |
|
| 4245 |
## Useful Mocks Created Using gMock |
| 4246 |
|
| 4247 |
<!--#include file="includes/g3_testing_LOGs.md"--> |
| 4248 |
<!--#include file="includes/g3_mock_callbacks.md"--> |
| 4249 |
|
| 4250 |
### Mock std::function {#MockFunction} |
| 4251 |
|
| 4252 |
`std::function` is a general function type introduced in C++11. It is a |
| 4253 |
preferred way of passing callbacks to new interfaces. Functions are copiable, |
| 4254 |
and are not usually passed around by pointer, which makes them tricky to mock. |
| 4255 |
But fear not - `MockFunction` can help you with that. |
| 4256 |
|
| 4257 |
`MockFunction<R(T1, ..., Tn)>` has a mock method `Call()` with the signature: |
| 4258 |
|
| 4259 |
```cpp |
| 4260 |
R Call(T1, ..., Tn); |
| 4261 |
``` |
| 4262 |
|
| 4263 |
It also has a `AsStdFunction()` method, which creates a `std::function` proxy |
| 4264 |
forwarding to Call: |
| 4265 |
|
| 4266 |
```cpp |
| 4267 |
std::function<R(T1, ..., Tn)> AsStdFunction(); |
| 4268 |
``` |
| 4269 |
|
| 4270 |
To use `MockFunction`, first create `MockFunction` object and set up |
| 4271 |
expectations on its `Call` method. Then pass proxy obtained from |
| 4272 |
`AsStdFunction()` to the code you are testing. For example: |
| 4273 |
|
| 4274 |
```cpp |
| 4275 |
TEST(FooTest, RunsCallbackWithBarArgument) { |
| 4276 |
// 1. Create a mock object. |
| 4277 |
MockFunction<int(string)> mock_function; |
| 4278 |
|
| 4279 |
// 2. Set expectations on Call() method. |
| 4280 |
EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1)); |
| 4281 |
|
| 4282 |
// 3. Exercise code that uses std::function. |
| 4283 |
Foo(mock_function.AsStdFunction()); |
| 4284 |
// Foo's signature can be either of: |
| 4285 |
// void Foo(const std::function<int(string)>& fun); |
| 4286 |
// void Foo(std::function<int(string)> fun); |
| 4287 |
|
| 4288 |
// 4. All expectations will be verified when mock_function |
| 4289 |
// goes out of scope and is destroyed. |
| 4290 |
} |
| 4291 |
``` |
| 4292 |
|
| 4293 |
Remember that function objects created with `AsStdFunction()` are just |
| 4294 |
forwarders. If you create multiple of them, they will share the same set of |
| 4295 |
expectations. |
| 4296 |
|
| 4297 |
Although `std::function` supports unlimited number of arguments, `MockFunction` |
| 4298 |
implementation is limited to ten. If you ever hit that limit... well, your |
| 4299 |
callback has bigger problems than being mockable. :-) |