]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | |
2 | ||
3 | # Defining a Mock Class # | |
4 | ||
5 | ## Mocking a Normal Class ## | |
6 | ||
7 | Given | |
8 | ``` | |
9 | class Foo { | |
10 | ... | |
11 | virtual ~Foo(); | |
12 | virtual int GetSize() const = 0; | |
13 | virtual string Describe(const char* name) = 0; | |
14 | virtual string Describe(int type) = 0; | |
15 | virtual bool Process(Bar elem, int count) = 0; | |
16 | }; | |
17 | ``` | |
18 | (note that `~Foo()` **must** be virtual) we can define its mock as | |
19 | ``` | |
20 | #include "gmock/gmock.h" | |
21 | ||
22 | class MockFoo : public Foo { | |
23 | MOCK_CONST_METHOD0(GetSize, int()); | |
24 | MOCK_METHOD1(Describe, string(const char* name)); | |
25 | MOCK_METHOD1(Describe, string(int type)); | |
26 | MOCK_METHOD2(Process, bool(Bar elem, int count)); | |
27 | }; | |
28 | ``` | |
29 | ||
30 | To create a "nice" mock object which ignores all uninteresting calls, | |
31 | or a "strict" mock object, which treats them as failures: | |
32 | ``` | |
33 | NiceMock<MockFoo> nice_foo; // The type is a subclass of MockFoo. | |
34 | StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo. | |
35 | ``` | |
36 | ||
37 | ## Mocking a Class Template ## | |
38 | ||
39 | To mock | |
40 | ``` | |
41 | template <typename Elem> | |
42 | class StackInterface { | |
43 | public: | |
44 | ... | |
45 | virtual ~StackInterface(); | |
46 | virtual int GetSize() const = 0; | |
47 | virtual void Push(const Elem& x) = 0; | |
48 | }; | |
49 | ``` | |
50 | (note that `~StackInterface()` **must** be virtual) just append `_T` to the `MOCK_*` macros: | |
51 | ``` | |
52 | template <typename Elem> | |
53 | class MockStack : public StackInterface<Elem> { | |
54 | public: | |
55 | ... | |
56 | MOCK_CONST_METHOD0_T(GetSize, int()); | |
57 | MOCK_METHOD1_T(Push, void(const Elem& x)); | |
58 | }; | |
59 | ``` | |
60 | ||
61 | ## Specifying Calling Conventions for Mock Functions ## | |
62 | ||
63 | If your mock function doesn't use the default calling convention, you | |
64 | can specify it by appending `_WITH_CALLTYPE` to any of the macros | |
65 | described in the previous two sections and supplying the calling | |
66 | convention as the first argument to the macro. For example, | |
67 | ``` | |
68 | MOCK_METHOD_1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int n)); | |
69 | MOCK_CONST_METHOD2_WITH_CALLTYPE(STDMETHODCALLTYPE, Bar, int(double x, double y)); | |
70 | ``` | |
71 | where `STDMETHODCALLTYPE` is defined by `<objbase.h>` on Windows. | |
72 | ||
73 | # Using Mocks in Tests # | |
74 | ||
75 | The typical flow is: | |
76 | 1. Import the Google Mock names you need to use. All Google Mock names are in the `testing` namespace unless they are macros or otherwise noted. | |
77 | 1. Create the mock objects. | |
78 | 1. Optionally, set the default actions of the mock objects. | |
79 | 1. Set your expectations on the mock objects (How will they be called? What wil they do?). | |
80 | 1. Exercise code that uses the mock objects; if necessary, check the result using [Google Test](../../googletest/) assertions. | |
81 | 1. When a mock objects is destructed, Google Mock automatically verifies that all expectations on it have been satisfied. | |
82 | ||
83 | Here is an example: | |
84 | ``` | |
85 | using ::testing::Return; // #1 | |
86 | ||
87 | TEST(BarTest, DoesThis) { | |
88 | MockFoo foo; // #2 | |
89 | ||
90 | ON_CALL(foo, GetSize()) // #3 | |
91 | .WillByDefault(Return(1)); | |
92 | // ... other default actions ... | |
93 | ||
94 | EXPECT_CALL(foo, Describe(5)) // #4 | |
95 | .Times(3) | |
96 | .WillRepeatedly(Return("Category 5")); | |
97 | // ... other expectations ... | |
98 | ||
99 | EXPECT_EQ("good", MyProductionFunction(&foo)); // #5 | |
100 | } // #6 | |
101 | ``` | |
102 | ||
103 | # Setting Default Actions # | |
104 | ||
105 | Google Mock has a **built-in default action** for any function that | |
106 | returns `void`, `bool`, a numeric value, or a pointer. | |
107 | ||
108 | To customize the default action for functions with return type `T` globally: | |
109 | ``` | |
110 | using ::testing::DefaultValue; | |
111 | ||
112 | // Sets the default value to be returned. T must be CopyConstructible. | |
113 | DefaultValue<T>::Set(value); | |
114 | // Sets a factory. Will be invoked on demand. T must be MoveConstructible. | |
115 | // T MakeT(); | |
116 | DefaultValue<T>::SetFactory(&MakeT); | |
117 | // ... use the mocks ... | |
118 | // Resets the default value. | |
119 | DefaultValue<T>::Clear(); | |
120 | ``` | |
121 | ||
122 | To customize the default action for a particular method, use `ON_CALL()`: | |
123 | ``` | |
124 | ON_CALL(mock_object, method(matchers)) | |
125 | .With(multi_argument_matcher) ? | |
126 | .WillByDefault(action); | |
127 | ``` | |
128 | ||
129 | # Setting Expectations # | |
130 | ||
131 | `EXPECT_CALL()` sets **expectations** on a mock method (How will it be | |
132 | called? What will it do?): | |
133 | ``` | |
134 | EXPECT_CALL(mock_object, method(matchers)) | |
135 | .With(multi_argument_matcher) ? | |
136 | .Times(cardinality) ? | |
137 | .InSequence(sequences) * | |
138 | .After(expectations) * | |
139 | .WillOnce(action) * | |
140 | .WillRepeatedly(action) ? | |
141 | .RetiresOnSaturation(); ? | |
142 | ``` | |
143 | ||
144 | If `Times()` is omitted, the cardinality is assumed to be: | |
145 | ||
146 | * `Times(1)` when there is neither `WillOnce()` nor `WillRepeatedly()`; | |
147 | * `Times(n)` when there are `n WillOnce()`s but no `WillRepeatedly()`, where `n` >= 1; or | |
148 | * `Times(AtLeast(n))` when there are `n WillOnce()`s and a `WillRepeatedly()`, where `n` >= 0. | |
149 | ||
150 | A method with no `EXPECT_CALL()` is free to be invoked _any number of times_, and the default action will be taken each time. | |
151 | ||
152 | # Matchers # | |
153 | ||
154 | A **matcher** matches a _single_ argument. You can use it inside | |
155 | `ON_CALL()` or `EXPECT_CALL()`, or use it to validate a value | |
156 | directly: | |
157 | ||
158 | | `EXPECT_THAT(value, matcher)` | Asserts that `value` matches `matcher`. | | |
159 | |:------------------------------|:----------------------------------------| | |
160 | | `ASSERT_THAT(value, matcher)` | The same as `EXPECT_THAT(value, matcher)`, except that it generates a **fatal** failure. | | |
161 | ||
162 | Built-in matchers (where `argument` is the function argument) are | |
163 | divided into several categories: | |
164 | ||
165 | ## Wildcard ## | |
166 | |`_`|`argument` can be any value of the correct type.| | |
167 | |:--|:-----------------------------------------------| | |
168 | |`A<type>()` or `An<type>()`|`argument` can be any value of type `type`. | | |
169 | ||
170 | ## Generic Comparison ## | |
171 | ||
172 | |`Eq(value)` or `value`|`argument == value`| | |
173 | |:---------------------|:------------------| | |
174 | |`Ge(value)` |`argument >= value`| | |
175 | |`Gt(value)` |`argument > value` | | |
176 | |`Le(value)` |`argument <= value`| | |
177 | |`Lt(value)` |`argument < value` | | |
178 | |`Ne(value)` |`argument != value`| | |
179 | |`IsNull()` |`argument` is a `NULL` pointer (raw or smart).| | |
180 | |`NotNull()` |`argument` is a non-null pointer (raw or smart).| | |
181 | |`Ref(variable)` |`argument` is a reference to `variable`.| | |
182 | |`TypedEq<type>(value)`|`argument` has type `type` and is equal to `value`. You may need to use this instead of `Eq(value)` when the mock function is overloaded.| | |
183 | ||
184 | Except `Ref()`, these matchers make a _copy_ of `value` in case it's | |
185 | modified or destructed later. If the compiler complains that `value` | |
186 | doesn't have a public copy constructor, try wrap it in `ByRef()`, | |
187 | e.g. `Eq(ByRef(non_copyable_value))`. If you do that, make sure | |
188 | `non_copyable_value` is not changed afterwards, or the meaning of your | |
189 | matcher will be changed. | |
190 | ||
191 | ## Floating-Point Matchers ## | |
192 | ||
193 | |`DoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal.| | |
194 | |:-------------------|:----------------------------------------------------------------------------------------------| | |
195 | |`FloatEq(a_float)` |`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. | | |
196 | |`NanSensitiveDoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | | |
197 | |`NanSensitiveFloatEq(a_float)`|`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. | | |
198 | ||
199 | The above matchers use ULP-based comparison (the same as used in | |
200 | [Google Test](../../googletest/)). They | |
201 | automatically pick a reasonable error bound based on the absolute | |
202 | value of the expected value. `DoubleEq()` and `FloatEq()` conform to | |
203 | the IEEE standard, which requires comparing two NaNs for equality to | |
204 | return false. The `NanSensitive*` version instead treats two NaNs as | |
205 | equal, which is often what a user wants. | |
206 | ||
207 | |`DoubleNear(a_double, max_abs_error)`|`argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as unequal.| | |
208 | |:------------------------------------|:--------------------------------------------------------------------------------------------------------------------| | |
209 | |`FloatNear(a_float, max_abs_error)` |`argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as unequal. | | |
210 | |`NanSensitiveDoubleNear(a_double, max_abs_error)`|`argument` is a `double` value close to `a_double` (absolute error <= `max_abs_error`), treating two NaNs as equal. | | |
211 | |`NanSensitiveFloatNear(a_float, max_abs_error)`|`argument` is a `float` value close to `a_float` (absolute error <= `max_abs_error`), treating two NaNs as equal. | | |
212 | ||
213 | ## String Matchers ## | |
214 | ||
215 | The `argument` can be either a C string or a C++ string object: | |
216 | ||
217 | |`ContainsRegex(string)`|`argument` matches the given regular expression.| | |
218 | |:----------------------|:-----------------------------------------------| | |
219 | |`EndsWith(suffix)` |`argument` ends with string `suffix`. | | |
220 | |`HasSubstr(string)` |`argument` contains `string` as a sub-string. | | |
221 | |`MatchesRegex(string)` |`argument` matches the given regular expression with the match starting at the first character and ending at the last character.| | |
222 | |`StartsWith(prefix)` |`argument` starts with string `prefix`. | | |
223 | |`StrCaseEq(string)` |`argument` is equal to `string`, ignoring case. | | |
224 | |`StrCaseNe(string)` |`argument` is not equal to `string`, ignoring case.| | |
225 | |`StrEq(string)` |`argument` is equal to `string`. | | |
226 | |`StrNe(string)` |`argument` is not equal to `string`. | | |
227 | ||
228 | `ContainsRegex()` and `MatchesRegex()` use the regular expression | |
229 | syntax defined | |
230 | [here](../../googletest/docs/AdvancedGuide.md#regular-expression-syntax). | |
231 | `StrCaseEq()`, `StrCaseNe()`, `StrEq()`, and `StrNe()` work for wide | |
232 | strings as well. | |
233 | ||
234 | ## Container Matchers ## | |
235 | ||
236 | Most STL-style containers support `==`, so you can use | |
237 | `Eq(expected_container)` or simply `expected_container` to match a | |
238 | container exactly. If you want to write the elements in-line, | |
239 | match them more flexibly, or get more informative messages, you can use: | |
240 | ||
241 | | `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. | | |
242 | |:-------------------------|:---------------------------------------------------------------------------------------------------------------------------------| | |
243 | | `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. | | |
244 | | `Each(e)` | `argument` is a container where _every_ element matches `e`, which can be either a value or a matcher. | | |
245 | | `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the i-th element matches `ei`, which can be a value or a matcher. 0 to 10 arguments are allowed. | | |
246 | | `ElementsAreArray({ e0, e1, ..., en })`, `ElementsAreArray(array)`, or `ElementsAreArray(array, count)` | The same as `ElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, or C-style array. | | |
247 | | `IsEmpty()` | `argument` is an empty container (`container.empty()`). | | |
248 | | `Pointwise(m, container)` | `argument` contains the same number of elements as in `container`, and for all i, (the i-th element in `argument`, the i-th element in `container`) match `m`, which is a matcher on 2-tuples. E.g. `Pointwise(Le(), upper_bounds)` verifies that each element in `argument` doesn't exceed the corresponding element in `upper_bounds`. See more detail below. | | |
249 | | `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. | | |
250 | | `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under some permutation each element matches an `ei` (for a different `i`), which can be a value or a matcher. 0 to 10 arguments are allowed. | | |
251 | | `UnorderedElementsAreArray({ e0, e1, ..., en })`, `UnorderedElementsAreArray(array)`, or `UnorderedElementsAreArray(array, count)` | The same as `UnorderedElementsAre()` except that the expected element values/matchers come from an initializer list, STL-style container, or C-style array. | | |
252 | | `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(UnorderedElementsAre(1, 2, 3))` verifies that `argument` contains elements `1`, `2`, and `3`, ignoring order. | | |
253 | | `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, except that the given comparator instead of `<` is used to sort `argument`. E.g. `WhenSortedBy(std::greater<int>(), ElementsAre(3, 2, 1))`. | | |
254 | ||
255 | Notes: | |
256 | ||
257 | * These matchers can also match: | |
258 | 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`), and | |
259 | 1. an array passed as a pointer and a count (e.g. in `Bar(const T* buffer, int len)` -- see [Multi-argument Matchers](#Multiargument_Matchers.md)). | |
260 | * The array being matched may be multi-dimensional (i.e. its elements can be arrays). | |
261 | * `m` in `Pointwise(m, ...)` should be a matcher for `::testing::tuple<T, U>` where `T` and `U` are the element type of the actual container and the expected container, respectively. For example, to compare two `Foo` containers where `Foo` doesn't support `operator==` but has an `Equals()` method, one might write: | |
262 | ||
263 | ``` | |
264 | using ::testing::get; | |
265 | MATCHER(FooEq, "") { | |
266 | return get<0>(arg).Equals(get<1>(arg)); | |
267 | } | |
268 | ... | |
269 | EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos)); | |
270 | ``` | |
271 | ||
272 | ## Member Matchers ## | |
273 | ||
274 | |`Field(&class::field, m)`|`argument.field` (or `argument->field` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_.| | |
275 | |:------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------| | |
276 | |`Key(e)` |`argument.first` matches `e`, which can be either a value or a matcher. E.g. `Contains(Key(Le(5)))` can verify that a `map` contains a key `<= 5`.| | |
277 | |`Pair(m1, m2)` |`argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. | | |
278 | |`Property(&class::property, m)`|`argument.property()` (or `argument->property()` when `argument` is a plain pointer) matches matcher `m`, where `argument` is an object of type _class_.| | |
279 | ||
280 | ## Matching the Result of a Function or Functor ## | |
281 | ||
282 | |`ResultOf(f, m)`|`f(argument)` matches matcher `m`, where `f` is a function or functor.| | |
283 | |:---------------|:---------------------------------------------------------------------| | |
284 | ||
285 | ## Pointer Matchers ## | |
286 | ||
287 | |`Pointee(m)`|`argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`.| | |
288 | |:-----------|:-----------------------------------------------------------------------------------------------| | |
289 | |`WhenDynamicCastTo<T>(m)`| when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. | | |
290 | ||
291 | ## Multiargument Matchers ## | |
292 | ||
293 | Technically, all matchers match a _single_ value. A "multi-argument" | |
294 | matcher is just one that matches a _tuple_. The following matchers can | |
295 | be used to match a tuple `(x, y)`: | |
296 | ||
297 | |`Eq()`|`x == y`| | |
298 | |:-----|:-------| | |
299 | |`Ge()`|`x >= y`| | |
300 | |`Gt()`|`x > y` | | |
301 | |`Le()`|`x <= y`| | |
302 | |`Lt()`|`x < y` | | |
303 | |`Ne()`|`x != y`| | |
304 | ||
305 | You can use the following selectors to pick a subset of the arguments | |
306 | (or reorder them) to participate in the matching: | |
307 | ||
308 | |`AllArgs(m)`|Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`.| | |
309 | |:-----------|:-------------------------------------------------------------------| | |
310 | |`Args<N1, N2, ..., Nk>(m)`|The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`.| | |
311 | ||
312 | ## Composite Matchers ## | |
313 | ||
314 | You can make a matcher from one or more other matchers: | |
315 | ||
316 | |`AllOf(m1, m2, ..., mn)`|`argument` matches all of the matchers `m1` to `mn`.| | |
317 | |:-----------------------|:---------------------------------------------------| | |
318 | |`AnyOf(m1, m2, ..., mn)`|`argument` matches at least one of the matchers `m1` to `mn`.| | |
319 | |`Not(m)` |`argument` doesn't match matcher `m`. | | |
320 | ||
321 | ## Adapters for Matchers ## | |
322 | ||
323 | |`MatcherCast<T>(m)`|casts matcher `m` to type `Matcher<T>`.| | |
324 | |:------------------|:--------------------------------------| | |
325 | |`SafeMatcherCast<T>(m)`| [safely casts](CookBook.md#casting-matchers) matcher `m` to type `Matcher<T>`. | | |
326 | |`Truly(predicate)` |`predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor.| | |
327 | ||
328 | ## Matchers as Predicates ## | |
329 | ||
330 | |`Matches(m)(value)`|evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor.| | |
331 | |:------------------|:---------------------------------------------------------------------------------------------| | |
332 | |`ExplainMatchResult(m, value, result_listener)`|evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. | | |
333 | |`Value(value, m)` |evaluates to `true` if `value` matches `m`. | | |
334 | ||
335 | ## Defining Matchers ## | |
336 | ||
337 | | `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. | | |
338 | |:-------------------------------------------------|:------------------------------------------------------| | |
339 | | `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a macher `IsDivisibleBy(n)` to match a number divisible by `n`. | | |
340 | | `MATCHER_P2(IsBetween, a, b, std::string(negation ? "isn't" : "is") + " between " + PrintToString(a) + " and " + PrintToString(b)) { return a <= arg && arg <= b; }` | Defines a matcher `IsBetween(a, b)` to match a value in the range [`a`, `b`]. | | |
341 | ||
342 | **Notes:** | |
343 | ||
344 | 1. The `MATCHER*` macros cannot be used inside a function or class. | |
345 | 1. The matcher body must be _purely functional_ (i.e. it cannot have any side effect, and the result must not depend on anything other than the value being matched and the matcher parameters). | |
346 | 1. You can use `PrintToString(x)` to convert a value `x` of any type to a string. | |
347 | ||
348 | ## Matchers as Test Assertions ## | |
349 | ||
350 | |`ASSERT_THAT(expression, m)`|Generates a [fatal failure](../../googletest/docs/Primer.md#assertions) if the value of `expression` doesn't match matcher `m`.| | |
351 | |:---------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------| | |
352 | |`EXPECT_THAT(expression, m)`|Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`. | | |
353 | ||
354 | # Actions # | |
355 | ||
356 | **Actions** specify what a mock function should do when invoked. | |
357 | ||
358 | ## Returning a Value ## | |
359 | ||
360 | |`Return()`|Return from a `void` mock function.| | |
361 | |:---------|:----------------------------------| | |
362 | |`Return(value)`|Return `value`. If the type of `value` is different to the mock function's return type, `value` is converted to the latter type <i>at the time the expectation is set</i>, not when the action is executed.| | |
363 | |`ReturnArg<N>()`|Return the `N`-th (0-based) argument.| | |
364 | |`ReturnNew<T>(a1, ..., ak)`|Return `new T(a1, ..., ak)`; a different object is created each time.| | |
365 | |`ReturnNull()`|Return a null pointer. | | |
366 | |`ReturnPointee(ptr)`|Return the value pointed to by `ptr`.| | |
367 | |`ReturnRef(variable)`|Return a reference to `variable`. | | |
368 | |`ReturnRefOfCopy(value)`|Return a reference to a copy of `value`; the copy lives as long as the action.| | |
369 | ||
370 | ## Side Effects ## | |
371 | ||
372 | |`Assign(&variable, value)`|Assign `value` to variable.| | |
373 | |:-------------------------|:--------------------------| | |
374 | | `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. | | |
375 | | `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. | | |
376 | | `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. | | |
377 | | `SetArgReferee<N>(value)` | Assign value to the variable referenced by the `N`-th (0-based) argument. | | |
378 | |`SetArgPointee<N>(value)` |Assign `value` to the variable pointed by the `N`-th (0-based) argument.| | |
379 | |`SetArgumentPointee<N>(value)`|Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0.| | |
380 | |`SetArrayArgument<N>(first, last)`|Copies the elements in source range [`first`, `last`) to the array pointed to by the `N`-th (0-based) argument, which can be either a pointer or an iterator. The action does not take ownership of the elements in the source range.| | |
381 | |`SetErrnoAndReturn(error, value)`|Set `errno` to `error` and return `value`.| | |
382 | |`Throw(exception)` |Throws the given exception, which can be any copyable value. Available since v1.1.0.| | |
383 | ||
384 | ## Using a Function or a Functor as an Action ## | |
385 | ||
386 | |`Invoke(f)`|Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor.| | |
387 | |:----------|:-----------------------------------------------------------------------------------------------------------------| | |
388 | |`Invoke(object_pointer, &class::method)`|Invoke the {method on the object with the arguments passed to the mock function. | | |
389 | |`InvokeWithoutArgs(f)`|Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. | | |
390 | |`InvokeWithoutArgs(object_pointer, &class::method)`|Invoke the method on the object, which takes no arguments. | | |
391 | |`InvokeArgument<N>(arg1, arg2, ..., argk)`|Invoke the mock function's `N`-th (0-based) argument, which must be a function or a functor, with the `k` arguments.| | |
392 | ||
393 | The return value of the invoked function is used as the return value | |
394 | of the action. | |
395 | ||
396 | When defining a function or functor to be used with `Invoke*()`, you can declare any unused parameters as `Unused`: | |
397 | ``` | |
398 | double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); } | |
399 | ... | |
400 | EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance)); | |
401 | ``` | |
402 | ||
403 | In `InvokeArgument<N>(...)`, if an argument needs to be passed by reference, wrap it inside `ByRef()`. For example, | |
404 | ``` | |
405 | InvokeArgument<2>(5, string("Hi"), ByRef(foo)) | |
406 | ``` | |
407 | calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by value, and `foo` by reference. | |
408 | ||
409 | ## Default Action ## | |
410 | ||
411 | |`DoDefault()`|Do the default action (specified by `ON_CALL()` or the built-in one).| | |
412 | |:------------|:--------------------------------------------------------------------| | |
413 | ||
414 | **Note:** due to technical reasons, `DoDefault()` cannot be used inside a composite action - trying to do so will result in a run-time error. | |
415 | ||
416 | ## Composite Actions ## | |
417 | ||
418 | |`DoAll(a1, a2, ..., an)`|Do all actions `a1` to `an` and return the result of `an` in each invocation. The first `n - 1` sub-actions must return void. | | |
419 | |:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------| | |
420 | |`IgnoreResult(a)` |Perform action `a` and ignore its result. `a` must not return void. | | |
421 | |`WithArg<N>(a)` |Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. | | |
422 | |`WithArgs<N1, N2, ..., Nk>(a)`|Pass the selected (0-based) arguments of the mock function to action `a` and perform it. | | |
423 | |`WithoutArgs(a)` |Perform action `a` without any arguments. | | |
424 | ||
425 | ## Defining Actions ## | |
426 | ||
427 | | `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. | | |
428 | |:--------------------------------------|:---------------------------------------------------------------------------------------| | |
429 | | `ACTION_P(Plus, n) { return arg0 + n; }` | Defines an action `Plus(n)` to return the sum of the mock function's argument #0 and `n`. | | |
430 | | `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. | | |
431 | ||
432 | The `ACTION*` macros cannot be used inside a function or class. | |
433 | ||
434 | # Cardinalities # | |
435 | ||
436 | These are used in `Times()` to specify how many times a mock function will be called: | |
437 | ||
438 | |`AnyNumber()`|The function can be called any number of times.| | |
439 | |:------------|:----------------------------------------------| | |
440 | |`AtLeast(n)` |The call is expected at least `n` times. | | |
441 | |`AtMost(n)` |The call is expected at most `n` times. | | |
442 | |`Between(m, n)`|The call is expected between `m` and `n` (inclusive) times.| | |
443 | |`Exactly(n) or n`|The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0.| | |
444 | ||
445 | # Expectation Order # | |
446 | ||
447 | By default, the expectations can be matched in _any_ order. If some | |
448 | or all expectations must be matched in a given order, there are two | |
449 | ways to specify it. They can be used either independently or | |
450 | together. | |
451 | ||
452 | ## The After Clause ## | |
453 | ||
454 | ``` | |
455 | using ::testing::Expectation; | |
456 | ... | |
457 | Expectation init_x = EXPECT_CALL(foo, InitX()); | |
458 | Expectation init_y = EXPECT_CALL(foo, InitY()); | |
459 | EXPECT_CALL(foo, Bar()) | |
460 | .After(init_x, init_y); | |
461 | ``` | |
462 | says that `Bar()` can be called only after both `InitX()` and | |
463 | `InitY()` have been called. | |
464 | ||
465 | If you don't know how many pre-requisites an expectation has when you | |
466 | write it, you can use an `ExpectationSet` to collect them: | |
467 | ||
468 | ``` | |
469 | using ::testing::ExpectationSet; | |
470 | ... | |
471 | ExpectationSet all_inits; | |
472 | for (int i = 0; i < element_count; i++) { | |
473 | all_inits += EXPECT_CALL(foo, InitElement(i)); | |
474 | } | |
475 | EXPECT_CALL(foo, Bar()) | |
476 | .After(all_inits); | |
477 | ``` | |
478 | says that `Bar()` can be called only after all elements have been | |
479 | initialized (but we don't care about which elements get initialized | |
480 | before the others). | |
481 | ||
482 | Modifying an `ExpectationSet` after using it in an `.After()` doesn't | |
483 | affect the meaning of the `.After()`. | |
484 | ||
485 | ## Sequences ## | |
486 | ||
487 | When you have a long chain of sequential expectations, it's easier to | |
488 | specify the order using **sequences**, which don't require you to given | |
489 | each expectation in the chain a different name. <i>All expected<br> | |
490 | calls</i> in the same sequence must occur in the order they are | |
491 | specified. | |
492 | ||
493 | ``` | |
494 | using ::testing::Sequence; | |
495 | Sequence s1, s2; | |
496 | ... | |
497 | EXPECT_CALL(foo, Reset()) | |
498 | .InSequence(s1, s2) | |
499 | .WillOnce(Return(true)); | |
500 | EXPECT_CALL(foo, GetSize()) | |
501 | .InSequence(s1) | |
502 | .WillOnce(Return(1)); | |
503 | EXPECT_CALL(foo, Describe(A<const char*>())) | |
504 | .InSequence(s2) | |
505 | .WillOnce(Return("dummy")); | |
506 | ``` | |
507 | says that `Reset()` must be called before _both_ `GetSize()` _and_ | |
508 | `Describe()`, and the latter two can occur in any order. | |
509 | ||
510 | To put many expectations in a sequence conveniently: | |
511 | ``` | |
512 | using ::testing::InSequence; | |
513 | { | |
514 | InSequence dummy; | |
515 | ||
516 | EXPECT_CALL(...)...; | |
517 | EXPECT_CALL(...)...; | |
518 | ... | |
519 | EXPECT_CALL(...)...; | |
520 | } | |
521 | ``` | |
522 | says that all expected calls in the scope of `dummy` must occur in | |
523 | strict order. The name `dummy` is irrelevant.) | |
524 | ||
525 | # Verifying and Resetting a Mock # | |
526 | ||
527 | Google Mock will verify the expectations on a mock object when it is destructed, or you can do it earlier: | |
528 | ``` | |
529 | using ::testing::Mock; | |
530 | ... | |
531 | // Verifies and removes the expectations on mock_obj; | |
532 | // returns true iff successful. | |
533 | Mock::VerifyAndClearExpectations(&mock_obj); | |
534 | ... | |
535 | // Verifies and removes the expectations on mock_obj; | |
536 | // also removes the default actions set by ON_CALL(); | |
537 | // returns true iff successful. | |
538 | Mock::VerifyAndClear(&mock_obj); | |
539 | ``` | |
540 | ||
541 | You can also tell Google Mock that a mock object can be leaked and doesn't | |
542 | need to be verified: | |
543 | ``` | |
544 | Mock::AllowLeak(&mock_obj); | |
545 | ``` | |
546 | ||
547 | # Mock Classes # | |
548 | ||
549 | Google Mock defines a convenient mock class template | |
550 | ``` | |
551 | class MockFunction<R(A1, ..., An)> { | |
552 | public: | |
553 | MOCK_METHODn(Call, R(A1, ..., An)); | |
554 | }; | |
555 | ``` | |
556 | See this [recipe](CookBook.md#using-check-points) for one application of it. | |
557 | ||
558 | # Flags # | |
559 | ||
560 | | `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. | | |
561 | |:-------------------------------|:----------------------------------------------| | |
562 | | `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. | |