docs/gmock_faq.md

   1 # Legacy gMock FAQ
   2
   3 ### When I call a method on my mock object, the method for the real object is invoked instead. What's the problem?
   4
   5 In order for a method to be mocked, it must be *virtual*, unless you use the
   6 [high-perf dependency injection technique](gmock_cook_book.md#MockingNonVirtualMethods).
   7
   8 ### Can I mock a variadic function?
   9
  10 You cannot mock a variadic function (i.e. a function taking ellipsis (`...`)
  11 arguments) directly in gMock.
  12
  13 The problem is that in general, there is *no way* for a mock object to know how
  14 many arguments are passed to the variadic method, and what the arguments' types
  15 are. Only the *author of the base class* knows the protocol, and we cannot look
  16 into his or her head.
  17
  18 Therefore, to mock such a function, the *user* must teach the mock object how to
  19 figure out the number of arguments and their types. One way to do it is to
  20 provide overloaded versions of the function.
  21
  22 Ellipsis arguments are inherited from C and not really a C++ feature. They are
  23 unsafe to use and don't work with arguments that have constructors or
  24 destructors. Therefore we recommend to avoid them in C++ as much as possible.
  25
  26 ### MSVC gives me warning C4301 or C4373 when I define a mock method with a const parameter. Why?
  27
  28 If you compile this using Microsoft Visual C++ 2005 SP1:
  29
  30 ```cpp
  31 class Foo {
  32   ...
  33   virtual void Bar(const int i) = 0;
  34 };
  35
  36 class MockFoo : public Foo {
  37   ...
  38   MOCK_METHOD(void, Bar, (const int i), (override));
  39 };
  40 ```
  41
  42 You may get the following warning:
  43
  44 ```shell
  45 warning C4301: 'MockFoo::Bar': overriding virtual function only differs from 'Foo::Bar' by const/volatile qualifier
  46 ```
  47
  48 This is a MSVC bug. The same code compiles fine with gcc, for example. If you
  49 use Visual C++ 2008 SP1, you would get the warning:
  50
  51 ```shell
  52 warning C4373: 'MockFoo::Bar': virtual function overrides 'Foo::Bar', previous versions of the compiler did not override when parameters only differed by const/volatile qualifiers
  53 ```
  54
  55 In C++, if you *declare* a function with a `const` parameter, the `const`
  56 modifier is ignored. Therefore, the `Foo` base class above is equivalent to:
  57
  58 ```cpp
  59 class Foo {
  60   ...
  61   virtual void Bar(int i) = 0;  // int or const int?  Makes no difference.
  62 };
  63 ```
  64
  65 In fact, you can *declare* `Bar()` with an `int` parameter, and define it with a
  66 `const int` parameter. The compiler will still match them up.
  67
  68 Since making a parameter `const` is meaningless in the method declaration, we
  69 recommend to remove it in both `Foo` and `MockFoo`. That should workaround the
  70 VC bug.
  71
  72 Note that we are talking about the *top-level* `const` modifier here. If the
  73 function parameter is passed by pointer or reference, declaring the pointee or
  74 referee as `const` is still meaningful. For example, the following two
  75 declarations are *not* equivalent:
  76
  77 ```cpp
  78 void Bar(int* p);         // Neither p nor *p is const.
  79 void Bar(const int* p);  // p is not const, but *p is.
  80 ```
  81
  82 ### I can't figure out why gMock thinks my expectations are not satisfied. What should I do?
  83
  84 You might want to run your test with `--gmock_verbose=info`. This flag lets
  85 gMock print a trace of every mock function call it receives. By studying the
  86 trace, you'll gain insights on why the expectations you set are not met.
  87
  88 If you see the message "The mock function has no default action set, and its
  89 return type has no default value set.", then try
  90 [adding a default action](gmock_cheat_sheet.md#OnCall). Due to a known issue,
  91 unexpected calls on mocks without default actions don't print out a detailed
  92 comparison between the actual arguments and the expected arguments.
  93
  94 ### My program crashed and `ScopedMockLog` spit out tons of messages. Is it a gMock bug?
  95
  96 gMock and `ScopedMockLog` are likely doing the right thing here.
  97
  98 When a test crashes, the failure signal handler will try to log a lot of
  99 information (the stack trace, and the address map, for example). The messages
 100 are compounded if you have many threads with depth stacks. When `ScopedMockLog`
 101 intercepts these messages and finds that they don't match any expectations, it
 102 prints an error for each of them.
 103
 104 You can learn to ignore the errors, or you can rewrite your expectations to make
 105 your test more robust, for example, by adding something like:
 106
 107 ```cpp
 108 using ::testing::AnyNumber;
 109 using ::testing::Not;
 110 ...
 111   // Ignores any log not done by us.
 112   EXPECT_CALL(log, Log(_, Not(EndsWith("/my_file.cc")), _))
 113       .Times(AnyNumber());
 114 ```
 115
 116 ### How can I assert that a function is NEVER called?
 117
 118 ```cpp
 119 using ::testing::_;
 120 ...
 121   EXPECT_CALL(foo, Bar(_))
 122       .Times(0);
 123 ```
 124
 125 ### I have a failed test where gMock tells me TWICE that a particular expectation is not satisfied. Isn't this redundant?
 126
 127 When gMock detects a failure, it prints relevant information (the mock function
 128 arguments, the state of relevant expectations, and etc) to help the user debug.
 129 If another failure is detected, gMock will do the same, including printing the
 130 state of relevant expectations.
 131
 132 Sometimes an expectation's state didn't change between two failures, and you'll
 133 see the same description of the state twice. They are however *not* redundant,
 134 as they refer to *different points in time*. The fact they are the same *is*
 135 interesting information.
 136
 137 ### I get a heapcheck failure when using a mock object, but using a real object is fine. What can be wrong?
 138
 139 Does the class (hopefully a pure interface) you are mocking have a virtual
 140 destructor?
 141
 142 Whenever you derive from a base class, make sure its destructor is virtual.
 143 Otherwise Bad Things will happen. Consider the following code:
 144
 145 ```cpp
 146 class Base {
 147  public:
 148   // Not virtual, but should be.
 149   ~Base() { ... }
 150   ...
 151 };
 152
 153 class Derived : public Base {
 154  public:
 155   ...
 156  private:
 157   std::string value_;
 158 };
 159
 160 ...
 161   Base* p = new Derived;
 162   ...
 163   delete p;  // Surprise! ~Base() will be called, but ~Derived() will not
 164                  // - value_ is leaked.
 165 ```
 166
 167 By changing `~Base()` to virtual, `~Derived()` will be correctly called when
 168 `delete p` is executed, and the heap checker will be happy.
 169
 170 ### The "newer expectations override older ones" rule makes writing expectations awkward. Why does gMock do that?
 171
 172 When people complain about this, often they are referring to code like:
 173
 174 ```cpp
 175 using ::testing::Return;
 176 ...
 177   // foo.Bar() should be called twice, return 1 the first time, and return
 178   // 2 the second time.  However, I have to write the expectations in the
 179   // reverse order.  This sucks big time!!!
 180   EXPECT_CALL(foo, Bar())
 181       .WillOnce(Return(2))
 182       .RetiresOnSaturation();
 183   EXPECT_CALL(foo, Bar())
 184       .WillOnce(Return(1))
 185       .RetiresOnSaturation();
 186 ```
 187
 188 The problem, is that they didn't pick the **best** way to express the test's
 189 intent.
 190
 191 By default, expectations don't have to be matched in *any* particular order. If
 192 you want them to match in a certain order, you need to be explicit. This is
 193 gMock's (and jMock's) fundamental philosophy: it's easy to accidentally
 194 over-specify your tests, and we want to make it harder to do so.
 195
 196 There are two better ways to write the test spec. You could either put the
 197 expectations in sequence:
 198
 199 ```cpp
 200 using ::testing::Return;
 201 ...
 202   // foo.Bar() should be called twice, return 1 the first time, and return
 203   // 2 the second time.  Using a sequence, we can write the expectations
 204   // in their natural order.
 205   {
 206     InSequence s;
 207     EXPECT_CALL(foo, Bar())
 208         .WillOnce(Return(1))
 209         .RetiresOnSaturation();
 210     EXPECT_CALL(foo, Bar())
 211         .WillOnce(Return(2))
 212         .RetiresOnSaturation();
 213   }
 214 ```
 215
 216 or you can put the sequence of actions in the same expectation:
 217
 218 ```cpp
 219 using ::testing::Return;
 220 ...
 221   // foo.Bar() should be called twice, return 1 the first time, and return
 222   // 2 the second time.
 223   EXPECT_CALL(foo, Bar())
 224       .WillOnce(Return(1))
 225       .WillOnce(Return(2))
 226       .RetiresOnSaturation();
 227 ```
 228
 229 Back to the original questions: why does gMock search the expectations (and
 230 `ON_CALL`s) from back to front? Because this allows a user to set up a mock's
 231 behavior for the common case early (e.g. in the mock's constructor or the test
 232 fixture's set-up phase) and customize it with more specific rules later. If
 233 gMock searches from front to back, this very useful pattern won't be possible.
 234
 235 ### gMock prints a warning when a function without EXPECT_CALL is called, even if I have set its behavior using ON_CALL. Would it be reasonable not to show the warning in this case?
 236
 237 When choosing between being neat and being safe, we lean toward the latter. So
 238 the answer is that we think it's better to show the warning.
 239
 240 Often people write `ON_CALL`s in the mock object's constructor or `SetUp()`, as
 241 the default behavior rarely changes from test to test. Then in the test body
 242 they set the expectations, which are often different for each test. Having an
 243 `ON_CALL` in the set-up part of a test doesn't mean that the calls are expected.
 244 If there's no `EXPECT_CALL` and the method is called, it's possibly an error. If
 245 we quietly let the call go through without notifying the user, bugs may creep in
 246 unnoticed.
 247
 248 If, however, you are sure that the calls are OK, you can write
 249
 250 ```cpp
 251 using ::testing::_;
 252 ...
 253   EXPECT_CALL(foo, Bar(_))
 254       .WillRepeatedly(...);
 255 ```
 256
 257 instead of
 258
 259 ```cpp
 260 using ::testing::_;
 261 ...
 262   ON_CALL(foo, Bar(_))
 263       .WillByDefault(...);
 264 ```
 265
 266 This tells gMock that you do expect the calls and no warning should be printed.
 267
 268 Also, you can control the verbosity by specifying `--gmock_verbose=error`. Other
 269 values are `info` and `warning`. If you find the output too noisy when
 270 debugging, just choose a less verbose level.
 271
 272 ### How can I delete the mock function's argument in an action?
 273
 274 If your mock function takes a pointer argument and you want to delete that
 275 argument, you can use testing::DeleteArg<N>() to delete the N'th (zero-indexed)
 276 argument:
 277
 278 ```cpp
 279 using ::testing::_;
 280   ...
 281   MOCK_METHOD(void, Bar, (X* x, const Y& y));
 282   ...
 283   EXPECT_CALL(mock_foo_, Bar(_, _))
 284       .WillOnce(testing::DeleteArg<0>()));
 285 ```
 286
 287 ### How can I perform an arbitrary action on a mock function's argument?
 288
 289 If you find yourself needing to perform some action that's not supported by
 290 gMock directly, remember that you can define your own actions using
 291 [`MakeAction()`](#NewMonoActions) or
 292 [`MakePolymorphicAction()`](#NewPolyActions), or you can write a stub function
 293 and invoke it using [`Invoke()`](#FunctionsAsActions).
 294
 295 ```cpp
 296 using ::testing::_;
 297 using ::testing::Invoke;
 298   ...
 299   MOCK_METHOD(void, Bar, (X* p));
 300   ...
 301   EXPECT_CALL(mock_foo_, Bar(_))
 302       .WillOnce(Invoke(MyAction(...)));
 303 ```
 304
 305 ### My code calls a static/global function. Can I mock it?
 306
 307 You can, but you need to make some changes.
 308
 309 In general, if you find yourself needing to mock a static function, it's a sign
 310 that your modules are too tightly coupled (and less flexible, less reusable,
 311 less testable, etc). You are probably better off defining a small interface and
 312 call the function through that interface, which then can be easily mocked. It's
 313 a bit of work initially, but usually pays for itself quickly.
 314
 315 This Google Testing Blog
 316 [post](https://testing.googleblog.com/2008/06/defeat-static-cling.html) says it
 317 excellently. Check it out.
 318
 319 ### My mock object needs to do complex stuff. It's a lot of pain to specify the actions. gMock sucks!
 320
 321 I know it's not a question, but you get an answer for free any way. :-)
 322
 323 With gMock, you can create mocks in C++ easily. And people might be tempted to
 324 use them everywhere. Sometimes they work great, and sometimes you may find them,
 325 well, a pain to use. So, what's wrong in the latter case?
 326
 327 When you write a test without using mocks, you exercise the code and assert that
 328 it returns the correct value or that the system is in an expected state. This is
 329 sometimes called "state-based testing".
 330
 331 Mocks are great for what some call "interaction-based" testing: instead of
 332 checking the system state at the very end, mock objects verify that they are
 333 invoked the right way and report an error as soon as it arises, giving you a
 334 handle on the precise context in which the error was triggered. This is often
 335 more effective and economical to do than state-based testing.
 336
 337 If you are doing state-based testing and using a test double just to simulate
 338 the real object, you are probably better off using a fake. Using a mock in this
 339 case causes pain, as it's not a strong point for mocks to perform complex
 340 actions. If you experience this and think that mocks suck, you are just not
 341 using the right tool for your problem. Or, you might be trying to solve the
 342 wrong problem. :-)
 343
 344 ### I got a warning "Uninteresting function call encountered - default action taken.." Should I panic?
 345
 346 By all means, NO! It's just an FYI. :-)
 347
 348 What it means is that you have a mock function, you haven't set any expectations
 349 on it (by gMock's rule this means that you are not interested in calls to this
 350 function and therefore it can be called any number of times), and it is called.
 351 That's OK - you didn't say it's not OK to call the function!
 352
 353 What if you actually meant to disallow this function to be called, but forgot to
 354 write `EXPECT_CALL(foo, Bar()).Times(0)`? While one can argue that it's the
 355 user's fault, gMock tries to be nice and prints you a note.
 356
 357 So, when you see the message and believe that there shouldn't be any
 358 uninteresting calls, you should investigate what's going on. To make your life
 359 easier, gMock dumps the stack trace when an uninteresting call is encountered.
 360 From that you can figure out which mock function it is, and how it is called.
 361
 362 ### I want to define a custom action. Should I use Invoke() or implement the ActionInterface interface?
 363
 364 Either way is fine - you want to choose the one that's more convenient for your
 365 circumstance.
 366
 367 Usually, if your action is for a particular function type, defining it using
 368 `Invoke()` should be easier; if your action can be used in functions of
 369 different types (e.g. if you are defining `Return(*value*)`),
 370 `MakePolymorphicAction()` is easiest. Sometimes you want precise control on what
 371 types of functions the action can be used in, and implementing `ActionInterface`
 372 is the way to go here. See the implementation of `Return()` in
 373 `testing/base/public/gmock-actions.h` for an example.
 374
 375 ### I use SetArgPointee() in WillOnce(), but gcc complains about "conflicting return type specified". What does it mean?
 376
 377 You got this error as gMock has no idea what value it should return when the
 378 mock method is called. `SetArgPointee()` says what the side effect is, but
 379 doesn't say what the return value should be. You need `DoAll()` to chain a
 380 `SetArgPointee()` with a `Return()` that provides a value appropriate to the API
 381 being mocked.
 382
 383 See this [recipe](gmock_cook_book.md#mocking-side-effects) for more details and
 384 an example.
 385
 386 ### I have a huge mock class, and Microsoft Visual C++ runs out of memory when compiling it. What can I do?
 387
 388 We've noticed that when the `/clr` compiler flag is used, Visual C++ uses 5~6
 389 times as much memory when compiling a mock class. We suggest to avoid `/clr`
 390 when compiling native C++ mocks.