| 1 |
# Actions Reference |
| 2 |
|
| 3 |
[**Actions**](../gmock_for_dummies.md#actions-what-should-it-do) specify what a |
| 4 |
mock function should do when invoked. This page lists the built-in actions |
| 5 |
provided by GoogleTest. All actions are defined in the `::testing` namespace. |
| 6 |
|
| 7 |
## Returning a Value |
| 8 |
|
| 9 |
| Action | Description | |
| 10 |
| :-------------------------------- | :-------------------------------------------- | |
| 11 |
| `Return()` | Return from a `void` mock function. | |
| 12 |
| `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. | |
| 13 |
| `ReturnArg<N>()` | Return the `N`-th (0-based) argument. | |
| 14 |
| `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. | |
| 15 |
| `ReturnNull()` | Return a null pointer. | |
| 16 |
| `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. | |
| 17 |
| `ReturnRef(variable)` | Return a reference to `variable`. | |
| 18 |
| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. | |
| 19 |
| `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. | |
| 20 |
|
| 21 |
## Side Effects |
| 22 |
|
| 23 |
| Action | Description | |
| 24 |
| :--------------------------------- | :-------------------------------------- | |
| 25 |
| `Assign(&variable, value)` | Assign `value` to variable. | |
| 26 |
| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. | |
| 27 |
| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. | |
| 28 |
| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. | |
| 29 |
| `SetArgReferee<N>(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. | |
| 30 |
| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. | |
| 31 |
| `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. | |
| 32 |
| `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. | |
| 33 |
| `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. | |
| 34 |
| `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. | |
| 35 |
|
| 36 |
## Using a Function, Functor, or Lambda as an Action |
| 37 |
|
| 38 |
In the following, by "callable" we mean a free function, `std::function`, |
| 39 |
functor, or lambda. |
| 40 |
|
| 41 |
| Action | Description | |
| 42 |
| :---------------------------------- | :------------------------------------- | |
| 43 |
| `f` | Invoke `f` with the arguments passed to the mock function, where `f` is a callable. | |
| 44 |
| `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. | |
| 45 |
| `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. | |
| 46 |
| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. | |
| 47 |
| `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. | |
| 48 |
| `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. | |
| 49 |
|
| 50 |
The return value of the invoked function is used as the return value of the |
| 51 |
action. |
| 52 |
|
| 53 |
When defining a callable to be used with `Invoke*()`, you can declare any unused |
| 54 |
parameters as `Unused`: |
| 55 |
|
| 56 |
```cpp |
| 57 |
using ::testing::Invoke; |
| 58 |
double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); } |
| 59 |
... |
| 60 |
EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance)); |
| 61 |
``` |
| 62 |
|
| 63 |
`Invoke(callback)` and `InvokeWithoutArgs(callback)` take ownership of |
| 64 |
`callback`, which must be permanent. The type of `callback` must be a base |
| 65 |
callback type instead of a derived one, e.g. |
| 66 |
|
| 67 |
```cpp |
| 68 |
BlockingClosure* done = new BlockingClosure; |
| 69 |
... Invoke(done) ...; // This won't compile! |
| 70 |
|
| 71 |
Closure* done2 = new BlockingClosure; |
| 72 |
... Invoke(done2) ...; // This works. |
| 73 |
``` |
| 74 |
|
| 75 |
In `InvokeArgument<N>(...)`, if an argument needs to be passed by reference, |
| 76 |
wrap it inside `std::ref()`. For example, |
| 77 |
|
| 78 |
```cpp |
| 79 |
using ::testing::InvokeArgument; |
| 80 |
... |
| 81 |
InvokeArgument<2>(5, string("Hi"), std::ref(foo)) |
| 82 |
``` |
| 83 |
|
| 84 |
calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by |
| 85 |
value, and `foo` by reference. |
| 86 |
|
| 87 |
## Default Action |
| 88 |
|
| 89 |
| Action | Description | |
| 90 |
| :------------ | :----------------------------------------------------- | |
| 91 |
| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). | |
| 92 |
|
| 93 |
{: .callout .note} |
| 94 |
**Note:** due to technical reasons, `DoDefault()` cannot be used inside a |
| 95 |
composite action - trying to do so will result in a run-time error. |
| 96 |
|
| 97 |
## Composite Actions |
| 98 |
|
| 99 |
| Action | Description | |
| 100 |
| :----------------------------- | :------------------------------------------ | |
| 101 |
| `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 and will receive a readonly view of the arguments. | |
| 102 |
| `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. | |
| 103 |
| `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. | |
| 104 |
| `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. | |
| 105 |
| `WithoutArgs(a)` | Perform action `a` without any arguments. | |
| 106 |
|
| 107 |
## Defining Actions |
| 108 |
|
| 109 |
| Macro | Description | |
| 110 |
| :--------------------------------- | :-------------------------------------- | |
| 111 |
| `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. | |
| 112 |
| `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`. | |
| 113 |
| `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. | |
| 114 |
|
| 115 |
The `ACTION*` macros cannot be used inside a function or class. |