diff options
Diffstat (limited to 'googlemock/docs/CheatSheet.md')
| -rw-r--r-- | googlemock/docs/CheatSheet.md | 224 |
1 files changed, 125 insertions, 99 deletions
diff --git a/googlemock/docs/CheatSheet.md b/googlemock/docs/CheatSheet.md index ef4451b..d5757b2 100644 --- a/googlemock/docs/CheatSheet.md +++ b/googlemock/docs/CheatSheet.md @@ -5,7 +5,7 @@ ## Mocking a Normal Class ## Given -``` +```cpp class Foo { ... virtual ~Foo(); @@ -16,7 +16,7 @@ class Foo { }; ``` (note that `~Foo()` **must** be virtual) we can define its mock as -``` +```cpp #include "gmock/gmock.h" class MockFoo : public Foo { @@ -29,7 +29,7 @@ class MockFoo : public Foo { To create a "nice" mock object which ignores all uninteresting calls, or a "strict" mock object, which treats them as failures: -``` +```cpp NiceMock<MockFoo> nice_foo; // The type is a subclass of MockFoo. StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo. ``` @@ -37,7 +37,7 @@ StrictMock<MockFoo> strict_foo; // The type is a subclass of MockFoo. ## Mocking a Class Template ## To mock -``` +```cpp template <typename Elem> class StackInterface { public: @@ -48,7 +48,7 @@ class StackInterface { }; ``` (note that `~StackInterface()` **must** be virtual) just append `_T` to the `MOCK_*` macros: -``` +```cpp template <typename Elem> class MockStack : public StackInterface<Elem> { public: @@ -64,8 +64,8 @@ If your mock function doesn't use the default calling convention, you can specify it by appending `_WITH_CALLTYPE` to any of the macros described in the previous two sections and supplying the calling convention as the first argument to the macro. For example, -``` - MOCK_METHOD_1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int n)); +```cpp + MOCK_METHOD1_WITH_CALLTYPE(STDMETHODCALLTYPE, Foo, bool(int n)); MOCK_CONST_METHOD2_WITH_CALLTYPE(STDMETHODCALLTYPE, Bar, int(double x, double y)); ``` where `STDMETHODCALLTYPE` is defined by `<objbase.h>` on Windows. @@ -81,8 +81,8 @@ The typical flow is: 1. When a mock objects is destructed, Google Mock automatically verifies that all expectations on it have been satisfied. Here is an example: -``` -using ::testing::Return; // #1 +```cpp +using ::testing::Return; // #1 TEST(BarTest, DoesThis) { MockFoo foo; // #2 @@ -106,7 +106,7 @@ Google Mock has a **built-in default action** for any function that returns `void`, `bool`, a numeric value, or a pointer. To customize the default action for functions with return type `T` globally: -``` +```cpp using ::testing::DefaultValue; // Sets the default value to be returned. T must be CopyConstructible. @@ -120,7 +120,7 @@ DefaultValue<T>::Clear(); ``` To customize the default action for a particular method, use `ON_CALL()`: -``` +```cpp ON_CALL(mock_object, method(matchers)) .With(multi_argument_matcher) ? .WillByDefault(action); @@ -130,7 +130,7 @@ ON_CALL(mock_object, method(matchers)) `EXPECT_CALL()` sets **expectations** on a mock method (How will it be called? What will it do?): -``` +```cpp EXPECT_CALL(mock_object, method(matchers)) .With(multi_argument_matcher) ? .Times(cardinality) ? @@ -155,22 +155,25 @@ A **matcher** matches a _single_ argument. You can use it inside `ON_CALL()` or `EXPECT_CALL()`, or use it to validate a value directly: +| Matcher | Description | +|:--------|:------------| | `EXPECT_THAT(value, matcher)` | Asserts that `value` matches `matcher`. | -|:------------------------------|:----------------------------------------| | `ASSERT_THAT(value, matcher)` | The same as `EXPECT_THAT(value, matcher)`, except that it generates a **fatal** failure. | Built-in matchers (where `argument` is the function argument) are divided into several categories: ## Wildcard ## +| Matcher | Description | +|:--------|:------------| |`_`|`argument` can be any value of the correct type.| -|:--|:-----------------------------------------------| |`A<type>()` or `An<type>()`|`argument` can be any value of type `type`. | ## Generic Comparison ## -|`Eq(value)` or `value`|`argument == value`| +| Matcher | Description | |:---------------------|:------------------| +|`Eq(value)` or `value`|`argument == value`| |`Ge(value)` |`argument >= value`| |`Gt(value)` |`argument > value` | |`Le(value)` |`argument <= value`| @@ -178,6 +181,7 @@ divided into several categories: |`Ne(value)` |`argument != value`| |`IsNull()` |`argument` is a `NULL` pointer (raw or smart).| |`NotNull()` |`argument` is a non-null pointer (raw or smart).| +|`VariantWith<T>(m)` |`argument` is `variant<>` that holds the alternative of type T with a value matching `m`.| |`Ref(variable)` |`argument` is a reference to `variable`.| |`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.| @@ -190,11 +194,12 @@ matcher will be changed. ## Floating-Point Matchers ## -|`DoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal.| -|:-------------------|:----------------------------------------------------------------------------------------------| -|`FloatEq(a_float)` |`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. | -|`NanSensitiveDoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | -|`NanSensitiveFloatEq(a_float)`|`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. | +| Matcher | Description | +|:-------------------|:---------------------------------------------------------------------------------------------------------| +|`DoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. | +|`FloatEq(a_float)` |`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. | +|`NanSensitiveDoubleEq(a_double)`|`argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | +|`NanSensitiveFloatEq(a_float)`|`argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. | The above matchers use ULP-based comparison (the same as used in [Google Test](../../googletest/)). They @@ -204,30 +209,32 @@ the IEEE standard, which requires comparing two NaNs for equality to return false. The `NanSensitive*` version instead treats two NaNs as equal, which is often what a user wants. +| Matcher | Description | +|:--------|:------------| |`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.| -|:------------------------------------|:--------------------------------------------------------------------------------------------------------------------| -|`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. | -|`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. | -|`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. | +|`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.| +|`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.| +|`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.| ## String Matchers ## The `argument` can be either a C string or a C++ string object: -|`ContainsRegex(string)`|`argument` matches the given regular expression.| -|:----------------------|:-----------------------------------------------| -|`EndsWith(suffix)` |`argument` ends with string `suffix`. | -|`HasSubstr(string)` |`argument` contains `string` as a sub-string. | +| Matcher | Description | +|:----------------------|:--------------------------------------------------| +|`ContainsRegex(string)`|`argument` matches the given regular expression. | +|`EndsWith(suffix)` |`argument` ends with string `suffix`. | +|`HasSubstr(string)` |`argument` contains `string` as a sub-string. | |`MatchesRegex(string)` |`argument` matches the given regular expression with the match starting at the first character and ending at the last character.| -|`StartsWith(prefix)` |`argument` starts with string `prefix`. | -|`StrCaseEq(string)` |`argument` is equal to `string`, ignoring case. | +|`StartsWith(prefix)` |`argument` starts with string `prefix`. | +|`StrCaseEq(string)` |`argument` is equal to `string`, ignoring case. | |`StrCaseNe(string)` |`argument` is not equal to `string`, ignoring case.| -|`StrEq(string)` |`argument` is equal to `string`. | -|`StrNe(string)` |`argument` is not equal to `string`. | +|`StrEq(string)` |`argument` is equal to `string`. | +|`StrNe(string)` |`argument` is not equal to `string`. | `ContainsRegex()` and `MatchesRegex()` use the regular expression syntax defined -[here](../../googletest/docs/AdvancedGuide.md#regular-expression-syntax). +[here](../../googletest/docs/advanced.md#regular-expression-syntax). `StrCaseEq()`, `StrCaseNe()`, `StrEq()`, and `StrNe()` work for wide strings as well. @@ -238,29 +245,30 @@ Most STL-style containers support `==`, so you can use container exactly. If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use: +| Matcher | Description | +|:--------|:------------| | `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. | -|:-------------------------|:---------------------------------------------------------------------------------------------------------------------------------| -| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. | -| `Each(e)` | `argument` is a container where _every_ element matches `e`, which can be either a value or a matcher. | +| `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. | +| `Each(e)` | `argument` is a container where _every_ element matches `e`, which can be either a value or a matcher. | | `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. | | `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. | -| `IsEmpty()` | `argument` is an empty container (`container.empty()`). | +| `IsEmpty()` | `argument` is an empty container (`container.empty()`). | | `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. | -| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. | +| `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. | | `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. | | `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. | -| `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. | +| `WhenSorted(m)` | When `argument` is sorted using the `<` operator, it matches container matcher `m`. E.g. `WhenSorted(ElementsAre(1, 2, 3))` verifies that `argument` contains elements `1`, `2`, and `3`, ignoring order. | | `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))`. | Notes: * These matchers can also match: 1. a native array passed by reference (e.g. in `Foo(const int (&a)[5])`), and - 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)). + 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)). * The array being matched may be multi-dimensional (i.e. its elements can be arrays). * `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: -``` +```cpp using ::testing::get; MATCHER(FooEq, "") { return get<0>(arg).Equals(get<1>(arg)); @@ -271,21 +279,24 @@ EXPECT_THAT(actual_foos, Pointwise(FooEq(), expected_foos)); ## Member Matchers ## +| Matcher | Description | +|:--------|:------------| |`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_.| -|:------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------| -|`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`.| -|`Pair(m1, m2)` |`argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. | +|`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`.| +|`Pair(m1, m2)`|`argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`.| |`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_.| ## Matching the Result of a Function or Functor ## -|`ResultOf(f, m)`|`f(argument)` matches matcher `m`, where `f` is a function or functor.| +| Matcher | Description | |:---------------|:---------------------------------------------------------------------| +|`ResultOf(f, m)`|`f(argument)` matches matcher `m`, where `f` is a function or functor.| ## Pointer Matchers ## -|`Pointee(m)`|`argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`.| -|:-----------|:-----------------------------------------------------------------------------------------------| +| Matcher | Description | +|:------------------------|:-----------------------------------------------------------------------------------------------| +|`Pointee(m)` |`argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`.| |`WhenDynamicCastTo<T>(m)`| when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. | ## Multiargument Matchers ## @@ -294,8 +305,9 @@ Technically, all matchers match a _single_ value. A "multi-argument" matcher is just one that matches a _tuple_. The following matchers can be used to match a tuple `(x, y)`: +| Matcher | Description | +|:--------|:------------| |`Eq()`|`x == y`| -|:-----|:-------| |`Ge()`|`x >= y`| |`Gt()`|`x > y` | |`Le()`|`x <= y`| @@ -305,37 +317,42 @@ be used to match a tuple `(x, y)`: You can use the following selectors to pick a subset of the arguments (or reorder them) to participate in the matching: +| Matcher | Description | +|:--------|:------------| |`AllArgs(m)`|Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`.| -|:-----------|:-------------------------------------------------------------------| |`Args<N1, N2, ..., Nk>(m)`|The tuple of the `k` selected (using 0-based indices) arguments matches `m`, e.g. `Args<1, 2>(Eq())`.| ## Composite Matchers ## You can make a matcher from one or more other matchers: -|`AllOf(m1, m2, ..., mn)`|`argument` matches all of the matchers `m1` to `mn`.| -|:-----------------------|:---------------------------------------------------| +| Matcher | Description | +|:-----------------------|:------------------------------------------------------------| +|`AllOf(m1, m2, ..., mn)`|`argument` matches all of the matchers `m1` to `mn`. | |`AnyOf(m1, m2, ..., mn)`|`argument` matches at least one of the matchers `m1` to `mn`.| -|`Not(m)` |`argument` doesn't match matcher `m`. | +|`Not(m)` |`argument` doesn't match matcher `m`. | ## Adapters for Matchers ## +| Matcher | Description | +|:--------|:------------| |`MatcherCast<T>(m)`|casts matcher `m` to type `Matcher<T>`.| -|:------------------|:--------------------------------------| -|`SafeMatcherCast<T>(m)`| [safely casts](CookBook.md#casting-matchers) matcher `m` to type `Matcher<T>`. | -|`Truly(predicate)` |`predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor.| +|`SafeMatcherCast<T>(m)`| [safely casts](CookBook.md#casting-matchers) matcher `m` to type `Matcher<T>`.| +|`Truly(predicate)`|`predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor.| ## Matchers as Predicates ## +| Matcher | Description | +|:--------|:------------| |`Matches(m)(value)`|evaluates to `true` if `value` matches `m`. You can use `Matches(m)` alone as a unary functor.| -|:------------------|:---------------------------------------------------------------------------------------------| -|`ExplainMatchResult(m, value, result_listener)`|evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. | -|`Value(value, m)` |evaluates to `true` if `value` matches `m`. | +|`ExplainMatchResult(m, value, result_listener)`|evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`.| +|`Value(value, m)`|evaluates to `true` if `value` matches `m`.| ## Defining Matchers ## +| Matcher | Description | +|:--------|:------------| | `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. | -|:-------------------------------------------------|:------------------------------------------------------| | `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`. | | `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`]. | @@ -347,9 +364,10 @@ You can make a matcher from one or more other matchers: ## Matchers as Test Assertions ## -|`ASSERT_THAT(expression, m)`|Generates a [fatal failure](../../googletest/docs/Primer.md#assertions) if the value of `expression` doesn't match matcher `m`.| -|:---------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------| -|`EXPECT_THAT(expression, m)`|Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`. | +| Matcher | Description | +|:--------|:------------| +|`ASSERT_THAT(expression, m)`|Generates a [fatal failure](../../googletest/docs/primer.md#assertions) if the value of `expression` doesn't match matcher `m`.| +|`EXPECT_THAT(expression, m)`|Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`.| # Actions # @@ -357,77 +375,83 @@ You can make a matcher from one or more other matchers: ## Returning a Value ## +| Matcher | Description | +|:--------|:------------| |`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. | +|`ReturnNull()`|Return a null pointer.| |`ReturnPointee(ptr)`|Return the value pointed to by `ptr`.| -|`ReturnRef(variable)`|Return a reference to `variable`. | +|`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.| ## Side Effects ## +| Matcher | Description | +|:--------|:------------| |`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. | +|`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.| +|`Throw(exception)`|Throws the given exception, which can be any copyable value. Available since v1.1.0.| ## Using a Function or a Functor as an Action ## +| Matcher | Description | +|:--------|:------------| |`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. | +|`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 the action. When defining a function or functor to be used with `Invoke*()`, you can declare any unused parameters as `Unused`: -``` +```cpp double Distance(Unused, double x, double y) { return sqrt(x*x + y*y); } ... EXPECT_CALL(mock, Foo("Hi", _, _)).WillOnce(Invoke(Distance)); ``` In `InvokeArgument<N>(...)`, if an argument needs to be passed by reference, wrap it inside `ByRef()`. For example, -``` +```cpp InvokeArgument<2>(5, string("Hi"), ByRef(foo)) ``` calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by value, and `foo` by reference. ## Default Action ## +| Matcher | Description | +|:--------|:------------| |`DoDefault()`|Do the default action (specified by `ON_CALL()` or the built-in one).| -|:------------|:--------------------------------------------------------------------| **Note:** due to technical reasons, `DoDefault()` cannot be used inside a composite 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. | -|:-----------------------|:-----------------------------------------------------------------------------------------------------------------------------| -|`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. | +| Matcher | Description | +|:-----------------------------|:-----------------------------------------------------------------------------------------------------------------------------| +|`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. | +|`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. | +|`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`. | +| Matcher | Description | +|:----------------------------------------------|:------------------------------------------------------------------------------------------| +| `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. @@ -435,10 +459,11 @@ The `ACTION*` macros cannot be used inside a function or class. These are used in `Times()` to specify how many times a mock function will be called: +| Matcher | Description | +|:--------|:------------| |`AnyNumber()`|The function can be called any number of times.| -|:------------|:----------------------------------------------| -|`AtLeast(n)` |The call is expected at least `n` times. | -|`AtMost(n)` |The call is expected at most `n` times. | +|`AtLeast(n)`|The call is expected at least `n` times.| +|`AtMost(n)`|The call is expected at most `n` times.| |`Between(m, n)`|The call is expected between `m` and `n` (inclusive) times.| |`Exactly(n) or n`|The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0.| @@ -451,7 +476,7 @@ together. ## The After Clause ## -``` +```cpp using ::testing::Expectation; ... Expectation init_x = EXPECT_CALL(foo, InitX()); @@ -465,7 +490,7 @@ says that `Bar()` can be called only after both `InitX()` and If you don't know how many pre-requisites an expectation has when you write it, you can use an `ExpectationSet` to collect them: -``` +```cpp using ::testing::ExpectationSet; ... ExpectationSet all_inits; @@ -490,7 +515,7 @@ each expectation in the chain a different name. <i>All expected<br> calls</i> in the same sequence must occur in the order they are specified. -``` +```cpp using ::testing::Sequence; Sequence s1, s2; ... @@ -508,7 +533,7 @@ says that `Reset()` must be called before _both_ `GetSize()` _and_ `Describe()`, and the latter two can occur in any order. To put many expectations in a sequence conveniently: -``` +```cpp using ::testing::InSequence; { InSequence dummy; @@ -525,7 +550,7 @@ strict order. The name `dummy` is irrelevant.) # Verifying and Resetting a Mock # Google Mock will verify the expectations on a mock object when it is destructed, or you can do it earlier: -``` +```cpp using ::testing::Mock; ... // Verifies and removes the expectations on mock_obj; @@ -540,14 +565,14 @@ Mock::VerifyAndClear(&mock_obj); You can also tell Google Mock that a mock object can be leaked and doesn't need to be verified: -``` +```cpp Mock::AllowLeak(&mock_obj); ``` # Mock Classes # Google Mock defines a convenient mock class template -``` +```cpp class MockFunction<R(A1, ..., An)> { public: MOCK_METHODn(Call, R(A1, ..., An)); @@ -557,6 +582,7 @@ See this [recipe](CookBook.md#using-check-points) for one application of it. # Flags # +| Flag | Description | +|:--------|:------------| | `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. | -|:-------------------------------|:----------------------------------------------| -| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. | +| `--gmock_verbose=LEVEL` | Sets the default verbosity level (`info`, `warning`, or `error`) of Google Mock messages. | |