|
|
# Actions Reference
[**Actions**](../gmock_for_dummies.md#actions-what-should-it-do) specify what amock function should do when invoked. This page lists the built-in actionsprovided by GoogleTest. All actions are defined in the `::testing` namespace.
## Returning a Value
| | || :-------------------------------- | :-------------------------------------------- || `Return()` | Return from a `void` mock function. || `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. || `ReturnArg<N>()` | Return the `N`-th (0-based) argument. || `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. || `ReturnNull()` | Return a null pointer. || `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. || `ReturnRef(variable)` | Return a reference to `variable`. || `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. || `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. |
## Side Effects
| | || :--------------------------------- | :-------------------------------------- || `Assign(&variable, value)` | Assign `value` to variable. || `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. || `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. || `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. || `SetArgReferee<N>(value)` | Assign `value` to the variable referenced by the `N`-th (0-based) argument. || `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. || `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. || `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. || `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. || `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. |
## Using a Function, Functor, or Lambda as an Action
In the following, by "callable" we mean a free function, `std::function`,functor, or lambda.
| | || :---------------------------------- | :------------------------------------- || `f` | Invoke f with the arguments passed to the mock function, where f is a callable. || `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. || `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. || `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. || `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. || `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. |
The return value of the invoked function is used as the return value of theaction.
When defining a callable to be used with `Invoke*()`, you can declare any unusedparameters as `Unused`:
```cppusing ::testing::Invoke;double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); }...EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance));```
`Invoke(callback)` and `InvokeWithoutArgs(callback)` take ownership of`callback`, which must be permanent. The type of `callback` must be a basecallback type instead of a derived one, e.g.
```cpp BlockingClosure* done = new BlockingClosure; ... Invoke(done) ...; // This won't compile!
Closure* done2 = new BlockingClosure; ... Invoke(done2) ...; // This works.```
In `InvokeArgument<N>(...)`, if an argument needs to be passed by reference,wrap it inside `std::ref()`. For example,
```cppusing ::testing::InvokeArgument;...InvokeArgument<2>(5, string("Hi"), std::ref(foo))```
calls the mock function's #2 argument, passing to it `5` and `string("Hi")` byvalue, and `foo` by reference.
## Default Action
| Matcher | Description || :------------ | :----------------------------------------------------- || `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). |
{: .callout .note}**Note:** due to technical reasons, `DoDefault()` cannot be used inside acomposite action - trying to do so will result in a run-time error.
## Composite Actions
| | || :----------------------------- | :------------------------------------------ || `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. || `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. || `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. || `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. || `WithoutArgs(a)` | Perform action `a` without any arguments. |
## Defining Actions
| | || :--------------------------------- | :-------------------------------------- || `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. || `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`. || `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. |
The `ACTION*` macros cannot be used inside a function or class.
|
