docs/reference/actions.md

   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.