generic-library/googletest
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Googletest export

Browse Source 
Remove markdown extension which isn't supported on github.

PiperOrigin-RevId: 261321329
This commit is contained in:
Abseil Team 2019-08-02 10:58:20 -04:00 committed by Gennadiy Civil
parent c8d338c629
commit 6a2adc0eed
2 changed files with 137 additions and 294 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

426
googlemock/docs/cheat_sheet.md
View File

@ -223,14 +223,12 @@ and the default action will be taken each time.
A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
`EXPECT_CALL()`, or use it to validate a value directly:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Matcher | Description |
| :----------------------------------- | :------------------------------------ |
| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches |
: : `matcher`. :
| `ASSERT_THAT(actual_value, matcher)` | The same as |
: : `EXPECT_THAT(actual_value, matcher)`, :
: : except that it generates a **fatal** :
: : failure. :
| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. |
| `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. |
<!-- mdformat on -->
Built-in matchers (where `argument` is the function argument) are divided into
several categories:
@ -244,6 +242,7 @@ Matcher | Description
#### Generic Comparison
<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :--------------------- | :-------------------------------------------------- |
| `Eq(value)` or `value` | `argument == value` |
@ -254,14 +253,11 @@ Matcher | Description
| `Ne(value)` | `argument != value` |
| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). |
| `NotNull()` | `argument` is a non-null pointer (raw or smart). |
| `Optional(m)` | `argument` is `optional<>` that contains a value |
: : matching `m`. :
| `VariantWith<T>(m)` | `argument` is `variant<>` that holds the |
: : alternative of type T with a value matching `m`. :
| `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. |
| `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. :
| `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. |
<!-- mdformat on -->
Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or
destructed later. If the compiler complains that `value` doesn't have a public
@ -271,20 +267,14 @@ is not changed afterwards, or the meaning of your matcher will be changed.
#### Floating-Point Matchers {#FpMatchers}
<!-- mdformat off(no multiline tables) -->
| 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. :
| `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. |
<!-- mdformat on -->
The above matchers use ULP-based comparison (the same as used in googletest).
They automatically pick a reasonable error bound based on the absolute value of
@ -293,43 +283,32 @@ 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, | `argument` is a `double` value close |
: max_abs_error)` : 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, | `argument` is a `double` value close |
: max_abs_error)` : to `a_double` (absolute error <= :
: : `max_abs_error`), treating two NaNs as :
: : equal. :
| `NanSensitiveFloatNear(a_float, | `argument` is a `float` value close to |
: max_abs_error)` : `a_float` (absolute error <= :
: : `max_abs_error`), treating two NaNs as :
: : equal. :
<!-- mdformat off(no multiline tables) -->
| 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. |
<!-- mdformat on -->
#### String Matchers
The `argument` can be either a C string or a C++ string object:
<!-- mdformat off(no multiline tables) -->
| 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. :
| `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. |
| `StrCaseNe(string)` | `argument` is not 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`. |
<!-- mdformat on -->
`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They
use the regular expression syntax defined
@ -343,99 +322,28 @@ or simply `expected_container` to match a container exactly. If you want to
write the elements in-line, match them more flexibly, or get more informative
messages, you can use:
<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :---------------------------------------- | :------------------------------- |
| `BeginEndDistanceIs(m)` | `argument` is a container whose |
: : `begin()` and `end()` iterators :
: : are separated by a number of :
: : increments matching `m`. E.g. :
: : `BeginEndDistanceIs(2)` or :
: : `BeginEndDistanceIs(Lt(2))`. For :
: : containers that define a :
: : `size()` method, `SizeIs(m)` may :
: : be more efficient. :
| `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. :
| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, |
: : where the *i*-th element matches :
: : `ei`, which can be a value or a :
: : matcher. :
| `ElementsAreArray({e0, e1, ..., en})`, | The same as `ElementsAre()` |
: `ElementsAreArray(a_container)`, : except that the expected element :
: `ElementsAreArray(begin, end)`, : values/matchers come from an :
: `ElementsAreArray(array)`, or : initializer list, STL-style :
: `ElementsAreArray(array, count)` : container, iterator range, or :
: : C-style array. :
| `IsEmpty()` | `argument` is an empty container |
: : (`container.empty()`). :
| `IsFalse()` | `argument` evaluates to `false` |
: : in a Boolean context. :
| `IsSubsetOf({e0, e1, ..., en})`, | `argument` matches |
: `IsSubsetOf(a_container)`, : `UnorderedElementsAre(x0, x1, :
: `IsSubsetOf(begin, end)`, : ..., xk)` for some subset `{x0, :
: `IsSubsetOf(array)`, or : x1, ..., xk}` of the expected :
: `IsSubsetOf(array, count)` : matchers. :
| `IsSupersetOf({e0, e1, ..., en})`, | Some subset of `argument` |
: `IsSupersetOf(a_container)`, : matches :
: `IsSupersetOf(begin, end)`, : `UnorderedElementsAre(`expected :
: `IsSupersetOf(array)`, or : matchers`)`. :
: `IsSupersetOf(array, count)` : :
| `IsTrue()` | `argument` evaluates to `true` |
: : in a Boolean context. :
| `Pointwise(m, container)`, `Pointwise(m, | `argument` contains the same |
: {e0, e1, ..., en})` : 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))`. :
| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, |
: : and under *some* permutation of :
: : the elements, each element :
: : matches an `ei` (for a different :
: : `i`), which can be a value or a :
: : matcher. :
| `UnorderedElementsAreArray({e0, e1, ..., | The same as |
: en})`, : `UnorderedElementsAre()` except :
: `UnorderedElementsAreArray(a_container)`, : that the expected element :
: `UnorderedElementsAreArray(begin, end)`, : values/matchers come from an :
: `UnorderedElementsAreArray(array)`, or : initializer list, STL-style :
: `UnorderedElementsAreArray(array, count)` : container, iterator range, or :
: : C-style array. :
| `UnorderedPointwise(m, container)`, | Like `Pointwise(m, container)`, |
: `UnorderedPointwise(m, {e0, e1, ..., : but ignores the order of :
: en})` : elements. :
| `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(), :
: : ElementsAre(3, 2, 1))`. :
| `BeginEndDistanceIs(m)` | `argument` is a container whose `begin()` and `end()` iterators are separated by a number of increments matching `m`. E.g. `BeginEndDistanceIs(2)` or `BeginEndDistanceIs(Lt(2))`. For containers that define a `size()` method, `SizeIs(m)` may be more efficient. |
| `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. |
| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. |
| `ElementsAreArray({e0, e1, ..., en})`, `ElementsAreArray(a_container)`, `ElementsAreArray(begin, end)`, `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, iterator range, or C-style array. |
| `IsEmpty()` | `argument` is an empty container (`container.empty()`). |
| `IsFalse()` | `argument` evaluates to `false` in a Boolean context. |
| `IsSubsetOf({e0, e1, ..., en})`, `IsSubsetOf(a_container)`, `IsSubsetOf(begin, end)`, `IsSubsetOf(array)`, or `IsSubsetOf(array, count)` | `argument` matches `UnorderedElementsAre(x0, x1, ..., xk)` for some subset `{x0, x1, ..., xk}` of the expected matchers. |
| `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. |
| `IsTrue()` | `argument` evaluates to `true` in a Boolean context. |
| `Pointwise(m, container)`, `Pointwise(m, {e0, e1, ..., en})` | `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))`. |
| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, and under *some* permutation of the elements, each element matches an `ei` (for a different `i`), which can be a value or a matcher. |
| `UnorderedElementsAreArray({e0, e1, ..., en})`, `UnorderedElementsAreArray(a_container)`, `UnorderedElementsAreArray(begin, end)`, `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, iterator range, or C-style array. |
| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. |
| `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(), ElementsAre(3, 2, 1))`. |
<!-- mdformat on -->
**Notes:**
@ -462,41 +370,31 @@ messages, you can use:
#### Member Matchers
<!-- mdformat off(no multiline tables) -->
| 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`. :
| `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_. :
| `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`. |
| `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_. |
<!-- mdformat on -->
#### Matching the Result of a Function, Functor, or Callback
<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :--------------- | :------------------------------------------------ |
| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a |
: : function or functor. :
| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. |
<!-- mdformat on -->
#### Pointer Matchers
<!-- mdformat off(no multiline tables) -->
| 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`. :
| `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`. |
<!-- mdformat on -->
<!-- GOOGLETEST_CM0026 DO NOT DELETE -->
@ -520,82 +418,61 @@ Matcher | Description
You can use the following selectors to pick a subset of the arguments (or
reorder them) to participate in the matching:
<!-- mdformat off(no multiline tables) -->
| 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())`. :
| `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())`. |
<!-- mdformat on -->
#### Composite Matchers
You can make a matcher from one or more other matchers:
<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------------------------- | :-------------------------------------- |
| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers |
: : `m1` to `mn`. :
| `AllOfArray({m0, m1, ..., mn})`, | The same as `AllOf()` except that the |
: `AllOfArray(a_container)`, : matchers come from an initializer list, :
: `AllOfArray(begin, end)`, : STL-style container, iterator range, or :
: `AllOfArray(array)`, or : C-style array. :
: `AllOfArray(array, count)` : :
| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the |
: : matchers `m1` to `mn`. :
| `AnyOfArray({m0, m1, ..., mn})`, | The same as `AnyOf()` except that the |
: `AnyOfArray(a_container)`, : matchers come from an initializer list, :
: `AnyOfArray(begin, end)`, : STL-style container, iterator range, or :
: `AnyOfArray(array)`, or : C-style array. :
: `AnyOfArray(array, count)` : :
| `Not(m)` | `argument` doesn't match matcher `m`. |
| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. |
| `AllOfArray({m0, m1, ..., mn})`, `AllOfArray(a_container)`, `AllOfArray(begin, end)`, `AllOfArray(array)`, or `AllOfArray(array, count)` | The same as `AllOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. |
| `AnyOfArray({m0, m1, ..., mn})`, `AnyOfArray(a_container)`, `AnyOfArray(begin, end)`, `AnyOfArray(array)`, or `AnyOfArray(array, count)` | The same as `AnyOf()` except that the matchers come from an initializer list, STL-style container, iterator range, or C-style array. |
| `Not(m)` | `argument` doesn't match matcher `m`. |
<!-- mdformat on -->
<!-- GOOGLETEST_CM0028 DO NOT DELETE -->
#### Adapters for Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :---------------------- | :------------------------------------ |
| `MatcherCast<T>(m)` | casts matcher `m` to type |
: : `Matcher<T>`. :
| `SafeMatcherCast<T>(m)` | [safely |
: : casts](cook_book.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. :
| `MatcherCast<T>(m)` | casts matcher `m` to type `Matcher<T>`. |
| `SafeMatcherCast<T>(m)` | [safely casts](cook_book.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. |
<!-- mdformat on -->
`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`,
which must be a permanent callback.
#### Using Matchers as Predicates {#MatchersAsPredicatesCheat}
<!-- mdformat off(no multiline tables) -->
| 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, | evaluates to `true` if `value` matches `m`, |
: result_listener)` : explaining the result to `result_listener`. :
| `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
| `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`. |
<!-- mdformat on -->
#### Defining Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :----------------------------------- | :------------------------------------ |
| `MATCHER(IsEven, "") { return (arg % | Defines a matcher `IsEven()` to match |
: 2) == 0; }` : an even number. :
| `MATCHER_P(IsDivisibleBy, n, "") { | Defines a macher `IsDivisibleBy(n)` |
: *result_listener << "where the : to match a number divisible by `n`. :
: remainder is " << (arg % n); return : :
: (arg % n) == 0; }` : :
| `MATCHER_P2(IsBetween, a, b, | Defines a matcher `IsBetween(a, b)` |
: std\:\:string(negation ? "isn't" \: : to match a value in the range [`a`, :
: "is") + " between " + : `b`]. :
: PrintToString(a) + " and " + : :
: PrintToString(b)) { return a <= arg : :
: && arg <= b; }` : :
| `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`]. |
<!-- mdformat on -->
**Notes:**
@ -612,78 +489,51 @@ which must be a permanent callback.
#### Returning a Value
<!-- mdformat off(no multiline tables) -->
| | |
| :-------------------------- | :-------------------------------------------- |
| `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. :
| `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. :
| `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. :
| `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. |
<!-- mdformat on -->
#### Side Effects
<!-- mdformat off(no multiline tables) -->
| | |
| :--------------------------------- | :-------------------------------------- |
| `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. :
| `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. |
<!-- mdformat on -->
#### Using a Function, Functor, or Lambda as an Action
In the following, by "callable" we mean a free function, `std::function`,
functor, or lambda.
<!-- mdformat off(no multiline tables) -->
| | |
| :---------------------------------- | :------------------------------------- |
| `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, | Invoke the method on the object with |
: &class\:\:method)` : 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, | Invoke the method on the object, which |
: &class\:\:method)` : takes no arguments. :
| `InvokeArgument<N>(arg1, arg2, ..., | Invoke the mock function's `N`-th |
: argk)` : (0-based) argument, which must be a :
: : function or a functor, with the `k` :
: : arguments. :
| `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. |
<!-- mdformat on -->
The return value of the invoked function is used as the return value of the
action.
@ -725,10 +575,11 @@ value, and `foo` by reference.
#### Default Action
<!-- mdformat off(no multiline tables) -->
| Matcher | Description |
| :------------ | :----------------------------------------------------- |
| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the |
: : built-in one). :
| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). |
<!-- mdformat on -->
**Note:** due to technical reasons, `DoDefault()` cannot be used inside a
composite action - trying to do so will result in a run-time error.
@ -737,19 +588,15 @@ composite action - trying to do so will result in a run-time error.
#### Composite Actions
<!-- mdformat off(no multiline tables) -->
| | |
| :----------------------------- | :------------------------------------------ |
| `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. |
| `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. |
<!-- mdformat on -->
#### Defining Actions
@ -766,17 +613,13 @@ composite action - trying to do so will result in a run-time error.
</tr>
</table>
<!-- mdformat off(no multiline tables) -->
| | |
| :--------------------------------- | :-------------------------------------- |
| `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 + | Defines an action `Plus(n)` to return |
: n; }` : the sum of the mock function's :
: : argument #0 and `n`. :
| `ACTION_Pk(Foo, p1, ..., pk) { | Defines a parameterized action `Foo(p1, |
: statements; }` : ..., pk)` to execute the given :
: : `statements`. :
| `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`. |
<!-- mdformat on -->
The `ACTION*` macros cannot be used inside a function or class.
@ -785,15 +628,15 @@ 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:
<!-- mdformat off(no multiline tables) -->
| | |
| :---------------- | :----------------------------------------------------- |
| `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. |
| `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. :
| `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. |
<!-- mdformat on -->
### Expectation Order
@ -918,10 +761,9 @@ See this [recipe](cook_book.md#using-check-points) for one application of it.
### Flags
<!-- mdformat off(no multiline tables) -->
| 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_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. |
<!-- mdformat on -->

5
googlemock/docs/cook_book.md
View File

@ -1195,11 +1195,12 @@ that satisfies matcher `m`.
For example:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Expression | Description |
| :--------------------------- | :--------------------------------------- |
| `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. |
| `Property(&Foo::name, | Matches `x` where `x.name()` starts with |
: StartsWith("John "))` : `"John "`. :
| `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. |
<!-- mdformat on -->
Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument
and be declared as `const`.