| 1 |
# gMock for Dummies |
| 2 |
|
| 3 |
## What Is gMock? |
| 4 |
|
| 5 |
When you write a prototype or test, often it's not feasible or wise to rely on |
| 6 |
real objects entirely. A **mock object** implements the same interface as a real |
| 7 |
object (so it can be used as one), but lets you specify at run time how it will |
| 8 |
be used and what it should do (which methods will be called? in which order? how |
| 9 |
many times? with what arguments? what will they return? etc). |
| 10 |
|
| 11 |
It is easy to confuse the term *fake objects* with mock objects. Fakes and mocks |
| 12 |
actually mean very different things in the Test-Driven Development (TDD) |
| 13 |
community: |
| 14 |
|
| 15 |
* **Fake** objects have working implementations, but usually take some |
| 16 |
shortcut (perhaps to make the operations less expensive), which makes them |
| 17 |
not suitable for production. An in-memory file system would be an example of |
| 18 |
a fake. |
| 19 |
* **Mocks** are objects pre-programmed with *expectations*, which form a |
| 20 |
specification of the calls they are expected to receive. |
| 21 |
|
| 22 |
If all this seems too abstract for you, don't worry - the most important thing |
| 23 |
to remember is that a mock allows you to check the *interaction* between itself |
| 24 |
and code that uses it. The difference between fakes and mocks shall become much |
| 25 |
clearer once you start to use mocks. |
| 26 |
|
| 27 |
**gMock** is a library (sometimes we also call it a "framework" to make it sound |
| 28 |
cool) for creating mock classes and using them. It does to C++ what |
| 29 |
jMock/EasyMock does to Java (well, more or less). |
| 30 |
|
| 31 |
When using gMock, |
| 32 |
|
| 33 |
1. first, you use some simple macros to describe the interface you want to |
| 34 |
mock, and they will expand to the implementation of your mock class; |
| 35 |
2. next, you create some mock objects and specify its expectations and behavior |
| 36 |
using an intuitive syntax; |
| 37 |
3. then you exercise code that uses the mock objects. gMock will catch any |
| 38 |
violation to the expectations as soon as it arises. |
| 39 |
|
| 40 |
## Why gMock? |
| 41 |
|
| 42 |
While mock objects help you remove unnecessary dependencies in tests and make |
| 43 |
them fast and reliable, using mocks manually in C++ is *hard*: |
| 44 |
|
| 45 |
* Someone has to implement the mocks. The job is usually tedious and |
| 46 |
error-prone. No wonder people go great distance to avoid it. |
| 47 |
* The quality of those manually written mocks is a bit, uh, unpredictable. You |
| 48 |
may see some really polished ones, but you may also see some that were |
| 49 |
hacked up in a hurry and have all sorts of ad hoc restrictions. |
| 50 |
* The knowledge you gained from using one mock doesn't transfer to the next |
| 51 |
one. |
| 52 |
|
| 53 |
In contrast, Java and Python programmers have some fine mock frameworks (jMock, |
| 54 |
EasyMock, etc), which automate the creation of mocks. As a result, mocking is a |
| 55 |
proven effective technique and widely adopted practice in those communities. |
| 56 |
Having the right tool absolutely makes the difference. |
| 57 |
|
| 58 |
gMock was built to help C++ programmers. It was inspired by jMock and EasyMock, |
| 59 |
but designed with C++'s specifics in mind. It is your friend if any of the |
| 60 |
following problems is bothering you: |
| 61 |
|
| 62 |
* You are stuck with a sub-optimal design and wish you had done more |
| 63 |
prototyping before it was too late, but prototyping in C++ is by no means |
| 64 |
"rapid". |
| 65 |
* Your tests are slow as they depend on too many libraries or use expensive |
| 66 |
resources (e.g. a database). |
| 67 |
* Your tests are brittle as some resources they use are unreliable (e.g. the |
| 68 |
network). |
| 69 |
* You want to test how your code handles a failure (e.g. a file checksum |
| 70 |
error), but it's not easy to cause one. |
| 71 |
* You need to make sure that your module interacts with other modules in the |
| 72 |
right way, but it's hard to observe the interaction; therefore you resort to |
| 73 |
observing the side effects at the end of the action, but it's awkward at |
| 74 |
best. |
| 75 |
* You want to "mock out" your dependencies, except that they don't have mock |
| 76 |
implementations yet; and, frankly, you aren't thrilled by some of those |
| 77 |
hand-written mocks. |
| 78 |
|
| 79 |
We encourage you to use gMock as |
| 80 |
|
| 81 |
* a *design* tool, for it lets you experiment with your interface design early |
| 82 |
and often. More iterations lead to better designs! |
| 83 |
* a *testing* tool to cut your tests' outbound dependencies and probe the |
| 84 |
interaction between your module and its collaborators. |
| 85 |
|
| 86 |
## Getting Started |
| 87 |
|
| 88 |
gMock is bundled with googletest. |
| 89 |
|
| 90 |
## A Case for Mock Turtles |
| 91 |
|
| 92 |
Let's look at an example. Suppose you are developing a graphics program that |
| 93 |
relies on a [LOGO](http://en.wikipedia.org/wiki/Logo_programming_language)-like |
| 94 |
API for drawing. How would you test that it does the right thing? Well, you can |
| 95 |
run it and compare the screen with a golden screen snapshot, but let's admit it: |
| 96 |
tests like this are expensive to run and fragile (What if you just upgraded to a |
| 97 |
shiny new graphics card that has better anti-aliasing? Suddenly you have to |
| 98 |
update all your golden images.). It would be too painful if all your tests are |
| 99 |
like this. Fortunately, you learned about |
| 100 |
[Dependency Injection](http://en.wikipedia.org/wiki/Dependency_injection) and know the right thing |
| 101 |
to do: instead of having your application talk to the system API directly, wrap |
| 102 |
the API in an interface (say, `Turtle`) and code to that interface: |
| 103 |
|
| 104 |
```cpp |
| 105 |
class Turtle { |
| 106 |
... |
| 107 |
virtual ~Turtle() {} |
| 108 |
virtual void PenUp() = 0; |
| 109 |
virtual void PenDown() = 0; |
| 110 |
virtual void Forward(int distance) = 0; |
| 111 |
virtual void Turn(int degrees) = 0; |
| 112 |
virtual void GoTo(int x, int y) = 0; |
| 113 |
virtual int GetX() const = 0; |
| 114 |
virtual int GetY() const = 0; |
| 115 |
}; |
| 116 |
``` |
| 117 |
|
| 118 |
(Note that the destructor of `Turtle` **must** be virtual, as is the case for |
| 119 |
**all** classes you intend to inherit from - otherwise the destructor of the |
| 120 |
derived class will not be called when you delete an object through a base |
| 121 |
pointer, and you'll get corrupted program states like memory leaks.) |
| 122 |
|
| 123 |
You can control whether the turtle's movement will leave a trace using `PenUp()` |
| 124 |
and `PenDown()`, and control its movement using `Forward()`, `Turn()`, and |
| 125 |
`GoTo()`. Finally, `GetX()` and `GetY()` tell you the current position of the |
| 126 |
turtle. |
| 127 |
|
| 128 |
Your program will normally use a real implementation of this interface. In |
| 129 |
tests, you can use a mock implementation instead. This allows you to easily |
| 130 |
check what drawing primitives your program is calling, with what arguments, and |
| 131 |
in which order. Tests written this way are much more robust (they won't break |
| 132 |
because your new machine does anti-aliasing differently), easier to read and |
| 133 |
maintain (the intent of a test is expressed in the code, not in some binary |
| 134 |
images), and run *much, much faster*. |
| 135 |
|
| 136 |
## Writing the Mock Class |
| 137 |
|
| 138 |
If you are lucky, the mocks you need to use have already been implemented by |
| 139 |
some nice people. If, however, you find yourself in the position to write a mock |
| 140 |
class, relax - gMock turns this task into a fun game! (Well, almost.) |
| 141 |
|
| 142 |
### How to Define It |
| 143 |
|
| 144 |
Using the `Turtle` interface as example, here are the simple steps you need to |
| 145 |
follow: |
| 146 |
|
| 147 |
* Derive a class `MockTurtle` from `Turtle`. |
| 148 |
* Take a *virtual* function of `Turtle` (while it's possible to |
| 149 |
[mock non-virtual methods using templates](gmock_cook_book.md#MockingNonVirtualMethods), |
| 150 |
it's much more involved). |
| 151 |
* In the `public:` section of the child class, write `MOCK_METHOD();` |
| 152 |
* Now comes the fun part: you take the function signature, cut-and-paste it |
| 153 |
into the macro, and add two commas - one between the return type and the |
| 154 |
name, another between the name and the argument list. |
| 155 |
* If you're mocking a const method, add a 4th parameter containing `(const)` |
| 156 |
(the parentheses are required). |
| 157 |
* Since you're overriding a virtual method, we suggest adding the `override` |
| 158 |
keyword. For const methods the 4th parameter becomes `(const, override)`, |
| 159 |
for non-const methods just `(override)`. This isn't mandatory. |
| 160 |
* Repeat until all virtual functions you want to mock are done. (It goes |
| 161 |
without saying that *all* pure virtual methods in your abstract class must |
| 162 |
be either mocked or overridden.) |
| 163 |
|
| 164 |
After the process, you should have something like: |
| 165 |
|
| 166 |
```cpp |
| 167 |
#include "gmock/gmock.h" // Brings in gMock. |
| 168 |
|
| 169 |
class MockTurtle : public Turtle { |
| 170 |
public: |
| 171 |
... |
| 172 |
MOCK_METHOD(void, PenUp, (), (override)); |
| 173 |
MOCK_METHOD(void, PenDown, (), (override)); |
| 174 |
MOCK_METHOD(void, Forward, (int distance), (override)); |
| 175 |
MOCK_METHOD(void, Turn, (int degrees), (override)); |
| 176 |
MOCK_METHOD(void, GoTo, (int x, int y), (override)); |
| 177 |
MOCK_METHOD(int, GetX, (), (const, override)); |
| 178 |
MOCK_METHOD(int, GetY, (), (const, override)); |
| 179 |
}; |
| 180 |
``` |
| 181 |
|
| 182 |
You don't need to define these mock methods somewhere else - the `MOCK_METHOD` |
| 183 |
macro will generate the definitions for you. It's that simple! |
| 184 |
|
| 185 |
### Where to Put It |
| 186 |
|
| 187 |
When you define a mock class, you need to decide where to put its definition. |
| 188 |
Some people put it in a `_test.cc`. This is fine when the interface being mocked |
| 189 |
(say, `Foo`) is owned by the same person or team. Otherwise, when the owner of |
| 190 |
`Foo` changes it, your test could break. (You can't really expect `Foo`'s |
| 191 |
maintainer to fix every test that uses `Foo`, can you?) |
| 192 |
|
| 193 |
Generally, you should not define mock classes you don't own. If you must mock |
| 194 |
such a class owned by others, define the mock class in `Foo`'s Bazel package |
| 195 |
(usually the same directory or a `testing` sub-directory), and put it in a `.h` |
| 196 |
and a `cc_library` with `testonly=True`. Then everyone can reference them from |
| 197 |
their tests. If `Foo` ever changes, there is only one copy of `MockFoo` to |
| 198 |
change, and only tests that depend on the changed methods need to be fixed. |
| 199 |
|
| 200 |
Another way to do it: you can introduce a thin layer `FooAdaptor` on top of |
| 201 |
`Foo` and code to this new interface. Since you own `FooAdaptor`, you can absorb |
| 202 |
changes in `Foo` much more easily. While this is more work initially, carefully |
| 203 |
choosing the adaptor interface can make your code easier to write and more |
| 204 |
readable (a net win in the long run), as you can choose `FooAdaptor` to fit your |
| 205 |
specific domain much better than `Foo` does. |
| 206 |
|
| 207 |
## Using Mocks in Tests |
| 208 |
|
| 209 |
Once you have a mock class, using it is easy. The typical work flow is: |
| 210 |
|
| 211 |
1. Import the gMock names from the `testing` namespace such that you can use |
| 212 |
them unqualified (You only have to do it once per file). Remember that |
| 213 |
namespaces are a good idea. |
| 214 |
2. Create some mock objects. |
| 215 |
3. Specify your expectations on them (How many times will a method be called? |
| 216 |
With what arguments? What should it do? etc.). |
| 217 |
4. Exercise some code that uses the mocks; optionally, check the result using |
| 218 |
googletest assertions. If a mock method is called more than expected or with |
| 219 |
wrong arguments, you'll get an error immediately. |
| 220 |
5. When a mock is destructed, gMock will automatically check whether all |
| 221 |
expectations on it have been satisfied. |
| 222 |
|
| 223 |
Here's an example: |
| 224 |
|
| 225 |
```cpp |
| 226 |
#include "path/to/mock-turtle.h" |
| 227 |
#include "gmock/gmock.h" |
| 228 |
#include "gtest/gtest.h" |
| 229 |
|
| 230 |
using ::testing::AtLeast; // #1 |
| 231 |
|
| 232 |
TEST(PainterTest, CanDrawSomething) { |
| 233 |
MockTurtle turtle; // #2 |
| 234 |
EXPECT_CALL(turtle, PenDown()) // #3 |
| 235 |
.Times(AtLeast(1)); |
| 236 |
|
| 237 |
Painter painter(&turtle); // #4 |
| 238 |
|
| 239 |
EXPECT_TRUE(painter.DrawCircle(0, 0, 10)); // #5 |
| 240 |
} |
| 241 |
``` |
| 242 |
|
| 243 |
As you might have guessed, this test checks that `PenDown()` is called at least |
| 244 |
once. If the `painter` object didn't call this method, your test will fail with |
| 245 |
a message like this: |
| 246 |
|
| 247 |
```text |
| 248 |
path/to/my_test.cc:119: Failure |
| 249 |
Actual function call count doesn't match this expectation: |
| 250 |
Actually: never called; |
| 251 |
Expected: called at least once. |
| 252 |
Stack trace: |
| 253 |
... |
| 254 |
``` |
| 255 |
|
| 256 |
**Tip 1:** If you run the test from an Emacs buffer, you can hit `<Enter>` on |
| 257 |
the line number to jump right to the failed expectation. |
| 258 |
|
| 259 |
**Tip 2:** If your mock objects are never deleted, the final verification won't |
| 260 |
happen. Therefore it's a good idea to turn on the heap checker in your tests |
| 261 |
when you allocate mocks on the heap. You get that automatically if you use the |
| 262 |
`gtest_main` library already. |
| 263 |
|
| 264 |
**Important note:** gMock requires expectations to be set **before** the mock |
| 265 |
functions are called, otherwise the behavior is **undefined**. Do not alternate |
| 266 |
between calls to `EXPECT_CALL()` and calls to the mock functions, and do not set |
| 267 |
any expectations on a mock after passing the mock to an API. |
| 268 |
|
| 269 |
This means `EXPECT_CALL()` should be read as expecting that a call will occur |
| 270 |
*in the future*, not that a call has occurred. Why does gMock work like that? |
| 271 |
Well, specifying the expectation beforehand allows gMock to report a violation |
| 272 |
as soon as it rises, when the context (stack trace, etc) is still available. |
| 273 |
This makes debugging much easier. |
| 274 |
|
| 275 |
Admittedly, this test is contrived and doesn't do much. You can easily achieve |
| 276 |
the same effect without using gMock. However, as we shall reveal soon, gMock |
| 277 |
allows you to do *so much more* with the mocks. |
| 278 |
|
| 279 |
## Setting Expectations |
| 280 |
|
| 281 |
The key to using a mock object successfully is to set the *right expectations* |
| 282 |
on it. If you set the expectations too strict, your test will fail as the result |
| 283 |
of unrelated changes. If you set them too loose, bugs can slip through. You want |
| 284 |
to do it just right such that your test can catch exactly the kind of bugs you |
| 285 |
intend it to catch. gMock provides the necessary means for you to do it "just |
| 286 |
right." |
| 287 |
|
| 288 |
### General Syntax |
| 289 |
|
| 290 |
In gMock we use the `EXPECT_CALL()` macro to set an expectation on a mock |
| 291 |
method. The general syntax is: |
| 292 |
|
| 293 |
```cpp |
| 294 |
EXPECT_CALL(mock_object, method(matchers)) |
| 295 |
.Times(cardinality) |
| 296 |
.WillOnce(action) |
| 297 |
.WillRepeatedly(action); |
| 298 |
``` |
| 299 |
|
| 300 |
The macro has two arguments: first the mock object, and then the method and its |
| 301 |
arguments. Note that the two are separated by a comma (`,`), not a period (`.`). |
| 302 |
(Why using a comma? The answer is that it was necessary for technical reasons.) |
| 303 |
If the method is not overloaded, the macro can also be called without matchers: |
| 304 |
|
| 305 |
```cpp |
| 306 |
EXPECT_CALL(mock_object, non-overloaded-method) |
| 307 |
.Times(cardinality) |
| 308 |
.WillOnce(action) |
| 309 |
.WillRepeatedly(action); |
| 310 |
``` |
| 311 |
|
| 312 |
This syntax allows the test writer to specify "called with any arguments" |
| 313 |
without explicitly specifying the number or types of arguments. To avoid |
| 314 |
unintended ambiguity, this syntax may only be used for methods that are not |
| 315 |
overloaded. |
| 316 |
|
| 317 |
Either form of the macro can be followed by some optional *clauses* that provide |
| 318 |
more information about the expectation. We'll discuss how each clause works in |
| 319 |
the coming sections. |
| 320 |
|
| 321 |
This syntax is designed to make an expectation read like English. For example, |
| 322 |
you can probably guess that |
| 323 |
|
| 324 |
```cpp |
| 325 |
using ::testing::Return; |
| 326 |
... |
| 327 |
EXPECT_CALL(turtle, GetX()) |
| 328 |
.Times(5) |
| 329 |
.WillOnce(Return(100)) |
| 330 |
.WillOnce(Return(150)) |
| 331 |
.WillRepeatedly(Return(200)); |
| 332 |
``` |
| 333 |
|
| 334 |
says that the `turtle` object's `GetX()` method will be called five times, it |
| 335 |
will return 100 the first time, 150 the second time, and then 200 every time. |
| 336 |
Some people like to call this style of syntax a Domain-Specific Language (DSL). |
| 337 |
|
| 338 |
{: .callout .note} |
| 339 |
**Note:** Why do we use a macro to do this? Well it serves two purposes: first |
| 340 |
it makes expectations easily identifiable (either by `grep` or by a human |
| 341 |
reader), and second it allows gMock to include the source file location of a |
| 342 |
failed expectation in messages, making debugging easier. |
| 343 |
|
| 344 |
### Matchers: What Arguments Do We Expect? |
| 345 |
|
| 346 |
When a mock function takes arguments, we may specify what arguments we are |
| 347 |
expecting, for example: |
| 348 |
|
| 349 |
```cpp |
| 350 |
// Expects the turtle to move forward by 100 units. |
| 351 |
EXPECT_CALL(turtle, Forward(100)); |
| 352 |
``` |
| 353 |
|
| 354 |
Oftentimes you do not want to be too specific. Remember that talk about tests |
| 355 |
being too rigid? Over specification leads to brittle tests and obscures the |
| 356 |
intent of tests. Therefore we encourage you to specify only what's necessary—no |
| 357 |
more, no less. If you aren't interested in the value of an argument, write `_` |
| 358 |
as the argument, which means "anything goes": |
| 359 |
|
| 360 |
```cpp |
| 361 |
using ::testing::_; |
| 362 |
... |
| 363 |
// Expects that the turtle jumps to somewhere on the x=50 line. |
| 364 |
EXPECT_CALL(turtle, GoTo(50, _)); |
| 365 |
``` |
| 366 |
|
| 367 |
`_` is an instance of what we call **matchers**. A matcher is like a predicate |
| 368 |
and can test whether an argument is what we'd expect. You can use a matcher |
| 369 |
inside `EXPECT_CALL()` wherever a function argument is expected. `_` is a |
| 370 |
convenient way of saying "any value". |
| 371 |
|
| 372 |
In the above examples, `100` and `50` are also matchers; implicitly, they are |
| 373 |
the same as `Eq(100)` and `Eq(50)`, which specify that the argument must be |
| 374 |
equal (using `operator==`) to the matcher argument. There are many |
| 375 |
[built-in matchers](reference/matchers.md) for common types (as well as |
| 376 |
[custom matchers](gmock_cook_book.md#NewMatchers)); for example: |
| 377 |
|
| 378 |
```cpp |
| 379 |
using ::testing::Ge; |
| 380 |
... |
| 381 |
// Expects the turtle moves forward by at least 100. |
| 382 |
EXPECT_CALL(turtle, Forward(Ge(100))); |
| 383 |
``` |
| 384 |
|
| 385 |
If you don't care about *any* arguments, rather than specify `_` for each of |
| 386 |
them you may instead omit the parameter list: |
| 387 |
|
| 388 |
```cpp |
| 389 |
// Expects the turtle to move forward. |
| 390 |
EXPECT_CALL(turtle, Forward); |
| 391 |
// Expects the turtle to jump somewhere. |
| 392 |
EXPECT_CALL(turtle, GoTo); |
| 393 |
``` |
| 394 |
|
| 395 |
This works for all non-overloaded methods; if a method is overloaded, you need |
| 396 |
to help gMock resolve which overload is expected by specifying the number of |
| 397 |
arguments and possibly also the |
| 398 |
[types of the arguments](gmock_cook_book.md#SelectOverload). |
| 399 |
|
| 400 |
### Cardinalities: How Many Times Will It Be Called? |
| 401 |
|
| 402 |
The first clause we can specify following an `EXPECT_CALL()` is `Times()`. We |
| 403 |
call its argument a **cardinality** as it tells *how many times* the call should |
| 404 |
occur. It allows us to repeat an expectation many times without actually writing |
| 405 |
it as many times. More importantly, a cardinality can be "fuzzy", just like a |
| 406 |
matcher can be. This allows a user to express the intent of a test exactly. |
| 407 |
|
| 408 |
An interesting special case is when we say `Times(0)`. You may have guessed - it |
| 409 |
means that the function shouldn't be called with the given arguments at all, and |
| 410 |
gMock will report a googletest failure whenever the function is (wrongfully) |
| 411 |
called. |
| 412 |
|
| 413 |
We've seen `AtLeast(n)` as an example of fuzzy cardinalities earlier. For the |
| 414 |
list of built-in cardinalities you can use, see |
| 415 |
[here](gmock_cheat_sheet.md#CardinalityList). |
| 416 |
|
| 417 |
The `Times()` clause can be omitted. **If you omit `Times()`, gMock will infer |
| 418 |
the cardinality for you.** The rules are easy to remember: |
| 419 |
|
| 420 |
* If **neither** `WillOnce()` **nor** `WillRepeatedly()` is in the |
| 421 |
`EXPECT_CALL()`, the inferred cardinality is `Times(1)`. |
| 422 |
* If there are *n* `WillOnce()`'s but **no** `WillRepeatedly()`, where *n* >= |
| 423 |
1, the cardinality is `Times(n)`. |
| 424 |
* If there are *n* `WillOnce()`'s and **one** `WillRepeatedly()`, where *n* >= |
| 425 |
0, the cardinality is `Times(AtLeast(n))`. |
| 426 |
|
| 427 |
**Quick quiz:** what do you think will happen if a function is expected to be |
| 428 |
called twice but actually called four times? |
| 429 |
|
| 430 |
### Actions: What Should It Do? |
| 431 |
|
| 432 |
Remember that a mock object doesn't really have a working implementation? We as |
| 433 |
users have to tell it what to do when a method is invoked. This is easy in |
| 434 |
gMock. |
| 435 |
|
| 436 |
First, if the return type of a mock function is a built-in type or a pointer, |
| 437 |
the function has a **default action** (a `void` function will just return, a |
| 438 |
`bool` function will return `false`, and other functions will return 0). In |
| 439 |
addition, in C++ 11 and above, a mock function whose return type is |
| 440 |
default-constructible (i.e. has a default constructor) has a default action of |
| 441 |
returning a default-constructed value. If you don't say anything, this behavior |
| 442 |
will be used. |
| 443 |
|
| 444 |
Second, if a mock function doesn't have a default action, or the default action |
| 445 |
doesn't suit you, you can specify the action to be taken each time the |
| 446 |
expectation matches using a series of `WillOnce()` clauses followed by an |
| 447 |
optional `WillRepeatedly()`. For example, |
| 448 |
|
| 449 |
```cpp |
| 450 |
using ::testing::Return; |
| 451 |
... |
| 452 |
EXPECT_CALL(turtle, GetX()) |
| 453 |
.WillOnce(Return(100)) |
| 454 |
.WillOnce(Return(200)) |
| 455 |
.WillOnce(Return(300)); |
| 456 |
``` |
| 457 |
|
| 458 |
says that `turtle.GetX()` will be called *exactly three times* (gMock inferred |
| 459 |
this from how many `WillOnce()` clauses we've written, since we didn't |
| 460 |
explicitly write `Times()`), and will return 100, 200, and 300 respectively. |
| 461 |
|
| 462 |
```cpp |
| 463 |
using ::testing::Return; |
| 464 |
... |
| 465 |
EXPECT_CALL(turtle, GetY()) |
| 466 |
.WillOnce(Return(100)) |
| 467 |
.WillOnce(Return(200)) |
| 468 |
.WillRepeatedly(Return(300)); |
| 469 |
``` |
| 470 |
|
| 471 |
says that `turtle.GetY()` will be called *at least twice* (gMock knows this as |
| 472 |
we've written two `WillOnce()` clauses and a `WillRepeatedly()` while having no |
| 473 |
explicit `Times()`), will return 100 and 200 respectively the first two times, |
| 474 |
and 300 from the third time on. |
| 475 |
|
| 476 |
Of course, if you explicitly write a `Times()`, gMock will not try to infer the |
| 477 |
cardinality itself. What if the number you specified is larger than there are |
| 478 |
`WillOnce()` clauses? Well, after all `WillOnce()`s are used up, gMock will do |
| 479 |
the *default* action for the function every time (unless, of course, you have a |
| 480 |
`WillRepeatedly()`.). |
| 481 |
|
| 482 |
What can we do inside `WillOnce()` besides `Return()`? You can return a |
| 483 |
reference using `ReturnRef(`*`variable`*`)`, or invoke a pre-defined function, |
| 484 |
among [others](gmock_cook_book.md#using-actions). |
| 485 |
|
| 486 |
**Important note:** The `EXPECT_CALL()` statement evaluates the action clause |
| 487 |
only once, even though the action may be performed many times. Therefore you |
| 488 |
must be careful about side effects. The following may not do what you want: |
| 489 |
|
| 490 |
```cpp |
| 491 |
using ::testing::Return; |
| 492 |
... |
| 493 |
int n = 100; |
| 494 |
EXPECT_CALL(turtle, GetX()) |
| 495 |
.Times(4) |
| 496 |
.WillRepeatedly(Return(n++)); |
| 497 |
``` |
| 498 |
|
| 499 |
Instead of returning 100, 101, 102, ..., consecutively, this mock function will |
| 500 |
always return 100 as `n++` is only evaluated once. Similarly, `Return(new Foo)` |
| 501 |
will create a new `Foo` object when the `EXPECT_CALL()` is executed, and will |
| 502 |
return the same pointer every time. If you want the side effect to happen every |
| 503 |
time, you need to define a custom action, which we'll teach in the |
| 504 |
[cook book](gmock_cook_book.md). |
| 505 |
|
| 506 |
Time for another quiz! What do you think the following means? |
| 507 |
|
| 508 |
```cpp |
| 509 |
using ::testing::Return; |
| 510 |
... |
| 511 |
EXPECT_CALL(turtle, GetY()) |
| 512 |
.Times(4) |
| 513 |
.WillOnce(Return(100)); |
| 514 |
``` |
| 515 |
|
| 516 |
Obviously `turtle.GetY()` is expected to be called four times. But if you think |
| 517 |
it will return 100 every time, think twice! Remember that one `WillOnce()` |
| 518 |
clause will be consumed each time the function is invoked and the default action |
| 519 |
will be taken afterwards. So the right answer is that `turtle.GetY()` will |
| 520 |
return 100 the first time, but **return 0 from the second time on**, as |
| 521 |
returning 0 is the default action for `int` functions. |
| 522 |
|
| 523 |
### Using Multiple Expectations {#MultiExpectations} |
| 524 |
|
| 525 |
So far we've only shown examples where you have a single expectation. More |
| 526 |
realistically, you'll specify expectations on multiple mock methods which may be |
| 527 |
from multiple mock objects. |
| 528 |
|
| 529 |
By default, when a mock method is invoked, gMock will search the expectations in |
| 530 |
the **reverse order** they are defined, and stop when an active expectation that |
| 531 |
matches the arguments is found (you can think of it as "newer rules override |
| 532 |
older ones."). If the matching expectation cannot take any more calls, you will |
| 533 |
get an upper-bound-violated failure. Here's an example: |
| 534 |
|
| 535 |
```cpp |
| 536 |
using ::testing::_; |
| 537 |
... |
| 538 |
EXPECT_CALL(turtle, Forward(_)); // #1 |
| 539 |
EXPECT_CALL(turtle, Forward(10)) // #2 |
| 540 |
.Times(2); |
| 541 |
``` |
| 542 |
|
| 543 |
If `Forward(10)` is called three times in a row, the third time it will be an |
| 544 |
error, as the last matching expectation (#2) has been saturated. If, however, |
| 545 |
the third `Forward(10)` call is replaced by `Forward(20)`, then it would be OK, |
| 546 |
as now #1 will be the matching expectation. |
| 547 |
|
| 548 |
{: .callout .note} |
| 549 |
**Note:** Why does gMock search for a match in the *reverse* order of the |
| 550 |
expectations? The reason is that this allows a user to set up the default |
| 551 |
expectations in a mock object's constructor or the test fixture's set-up phase |
| 552 |
and then customize the mock by writing more specific expectations in the test |
| 553 |
body. So, if you have two expectations on the same method, you want to put the |
| 554 |
one with more specific matchers **after** the other, or the more specific rule |
| 555 |
would be shadowed by the more general one that comes after it. |
| 556 |
|
| 557 |
{: .callout .tip} |
| 558 |
**Tip:** It is very common to start with a catch-all expectation for a method |
| 559 |
and `Times(AnyNumber())` (omitting arguments, or with `_` for all arguments, if |
| 560 |
overloaded). This makes any calls to the method expected. This is not necessary |
| 561 |
for methods that are not mentioned at all (these are "uninteresting"), but is |
| 562 |
useful for methods that have some expectations, but for which other calls are |
| 563 |
ok. See |
| 564 |
[Understanding Uninteresting vs Unexpected Calls](gmock_cook_book.md#uninteresting-vs-unexpected). |
| 565 |
|
| 566 |
### Ordered vs Unordered Calls {#OrderedCalls} |
| 567 |
|
| 568 |
By default, an expectation can match a call even though an earlier expectation |
| 569 |
hasn't been satisfied. In other words, the calls don't have to occur in the |
| 570 |
order the expectations are specified. |
| 571 |
|
| 572 |
Sometimes, you may want all the expected calls to occur in a strict order. To |
| 573 |
say this in gMock is easy: |
| 574 |
|
| 575 |
```cpp |
| 576 |
using ::testing::InSequence; |
| 577 |
... |
| 578 |
TEST(FooTest, DrawsLineSegment) { |
| 579 |
... |
| 580 |
{ |
| 581 |
InSequence seq; |
| 582 |
|
| 583 |
EXPECT_CALL(turtle, PenDown()); |
| 584 |
EXPECT_CALL(turtle, Forward(100)); |
| 585 |
EXPECT_CALL(turtle, PenUp()); |
| 586 |
} |
| 587 |
Foo(); |
| 588 |
} |
| 589 |
``` |
| 590 |
|
| 591 |
By creating an object of type `InSequence`, all expectations in its scope are |
| 592 |
put into a *sequence* and have to occur *sequentially*. Since we are just |
| 593 |
relying on the constructor and destructor of this object to do the actual work, |
| 594 |
its name is really irrelevant. |
| 595 |
|
| 596 |
In this example, we test that `Foo()` calls the three expected functions in the |
| 597 |
order as written. If a call is made out-of-order, it will be an error. |
| 598 |
|
| 599 |
(What if you care about the relative order of some of the calls, but not all of |
| 600 |
them? Can you specify an arbitrary partial order? The answer is ... yes! The |
| 601 |
details can be found [here](gmock_cook_book.md#OrderedCalls).) |
| 602 |
|
| 603 |
### All Expectations Are Sticky (Unless Said Otherwise) {#StickyExpectations} |
| 604 |
|
| 605 |
Now let's do a quick quiz to see how well you can use this mock stuff already. |
| 606 |
How would you test that the turtle is asked to go to the origin *exactly twice* |
| 607 |
(you want to ignore any other instructions it receives)? |
| 608 |
|
| 609 |
After you've come up with your answer, take a look at ours and compare notes |
| 610 |
(solve it yourself first - don't cheat!): |
| 611 |
|
| 612 |
```cpp |
| 613 |
using ::testing::_; |
| 614 |
using ::testing::AnyNumber; |
| 615 |
... |
| 616 |
EXPECT_CALL(turtle, GoTo(_, _)) // #1 |
| 617 |
.Times(AnyNumber()); |
| 618 |
EXPECT_CALL(turtle, GoTo(0, 0)) // #2 |
| 619 |
.Times(2); |
| 620 |
``` |
| 621 |
|
| 622 |
Suppose `turtle.GoTo(0, 0)` is called three times. In the third time, gMock will |
| 623 |
see that the arguments match expectation #2 (remember that we always pick the |
| 624 |
last matching expectation). Now, since we said that there should be only two |
| 625 |
such calls, gMock will report an error immediately. This is basically what we've |
| 626 |
told you in the [Using Multiple Expectations](#MultiExpectations) section above. |
| 627 |
|
| 628 |
This example shows that **expectations in gMock are "sticky" by default**, in |
| 629 |
the sense that they remain active even after we have reached their invocation |
| 630 |
upper bounds. This is an important rule to remember, as it affects the meaning |
| 631 |
of the spec, and is **different** to how it's done in many other mocking |
| 632 |
frameworks (Why'd we do that? Because we think our rule makes the common cases |
| 633 |
easier to express and understand.). |
| 634 |
|
| 635 |
Simple? Let's see if you've really understood it: what does the following code |
| 636 |
say? |
| 637 |
|
| 638 |
```cpp |
| 639 |
using ::testing::Return; |
| 640 |
... |
| 641 |
for (int i = n; i > 0; i--) { |
| 642 |
EXPECT_CALL(turtle, GetX()) |
| 643 |
.WillOnce(Return(10*i)); |
| 644 |
} |
| 645 |
``` |
| 646 |
|
| 647 |
If you think it says that `turtle.GetX()` will be called `n` times and will |
| 648 |
return 10, 20, 30, ..., consecutively, think twice! The problem is that, as we |
| 649 |
said, expectations are sticky. So, the second time `turtle.GetX()` is called, |
| 650 |
the last (latest) `EXPECT_CALL()` statement will match, and will immediately |
| 651 |
lead to an "upper bound violated" error - this piece of code is not very useful! |
| 652 |
|
| 653 |
One correct way of saying that `turtle.GetX()` will return 10, 20, 30, ..., is |
| 654 |
to explicitly say that the expectations are *not* sticky. In other words, they |
| 655 |
should *retire* as soon as they are saturated: |
| 656 |
|
| 657 |
```cpp |
| 658 |
using ::testing::Return; |
| 659 |
... |
| 660 |
for (int i = n; i > 0; i--) { |
| 661 |
EXPECT_CALL(turtle, GetX()) |
| 662 |
.WillOnce(Return(10*i)) |
| 663 |
.RetiresOnSaturation(); |
| 664 |
} |
| 665 |
``` |
| 666 |
|
| 667 |
And, there's a better way to do it: in this case, we expect the calls to occur |
| 668 |
in a specific order, and we line up the actions to match the order. Since the |
| 669 |
order is important here, we should make it explicit using a sequence: |
| 670 |
|
| 671 |
```cpp |
| 672 |
using ::testing::InSequence; |
| 673 |
using ::testing::Return; |
| 674 |
... |
| 675 |
{ |
| 676 |
InSequence s; |
| 677 |
|
| 678 |
for (int i = 1; i <= n; i++) { |
| 679 |
EXPECT_CALL(turtle, GetX()) |
| 680 |
.WillOnce(Return(10*i)) |
| 681 |
.RetiresOnSaturation(); |
| 682 |
} |
| 683 |
} |
| 684 |
``` |
| 685 |
|
| 686 |
By the way, the other situation where an expectation may *not* be sticky is when |
| 687 |
it's in a sequence - as soon as another expectation that comes after it in the |
| 688 |
sequence has been used, it automatically retires (and will never be used to |
| 689 |
match any call). |
| 690 |
|
| 691 |
### Uninteresting Calls |
| 692 |
|
| 693 |
A mock object may have many methods, and not all of them are that interesting. |
| 694 |
For example, in some tests we may not care about how many times `GetX()` and |
| 695 |
`GetY()` get called. |
| 696 |
|
| 697 |
In gMock, if you are not interested in a method, just don't say anything about |
| 698 |
it. If a call to this method occurs, you'll see a warning in the test output, |
| 699 |
but it won't be a failure. This is called "naggy" behavior; to change, see |
| 700 |
[The Nice, the Strict, and the Naggy](gmock_cook_book.md#NiceStrictNaggy). |