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