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 A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
`EXPECT_CALL()`, or use it to validate a value directly: `EXPECT_CALL()`, or use it to validate a value directly:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :----------------------------------- | :------------------------------------ | | :----------------------------------- | :------------------------------------ |
| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches | | `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. |
: : `matcher`. : | `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. |
| `ASSERT_THAT(actual_value, matcher)` | The same as | <!-- mdformat on -->
: : `EXPECT_THAT(actual_value, matcher)`, :
: : except that it generates a **fatal** :
: : failure. :
Built-in matchers (where `argument` is the function argument) are divided into Built-in matchers (where `argument` is the function argument) are divided into
several categories: several categories:
@ -244,6 +242,7 @@ Matcher | Description
#### Generic Comparison #### Generic Comparison
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :--------------------- | :-------------------------------------------------- | | :--------------------- | :-------------------------------------------------- |
| `Eq(value)` or `value` | `argument == value` | | `Eq(value)` or `value` | `argument == value` |
@ -254,14 +253,11 @@ Matcher | Description
| `Ne(value)` | `argument != value` | | `Ne(value)` | `argument != value` |
| `IsNull()` | `argument` is a `NULL` pointer (raw or smart). | | `IsNull()` | `argument` is a `NULL` pointer (raw or smart). |
| `NotNull()` | `argument` is a non-null pointer (raw or smart). | | `NotNull()` | `argument` is a non-null pointer (raw or smart). |
| `Optional(m)` | `argument` is `optional<>` that contains a value | | `Optional(m)` | `argument` is `optional<>` that contains a value matching `m`. |
: : matching `m`. : | `VariantWith<T>(m)` | `argument` is `variant<>` that holds the alternative of type T with 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`. | | `Ref(variable)` | `argument` is a reference to `variable`. |
| `TypedEq<type>(value)` | `argument` has type `type` and is equal to `value`. | | `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. |
: : You may need to use this instead of `Eq(value)` : <!-- mdformat on -->
: : when the mock function is overloaded. :
Except `Ref()`, these matchers make a *copy* of `value` in case it's modified or 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 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} #### Floating-Point Matchers {#FpMatchers}
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :------------------------------- | :--------------------------------- | | :------------------------------- | :--------------------------------- |
| `DoubleEq(a_double)` | `argument` is a `double` value | | `DoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. |
: : approximately equal to `a_double`, : | `FloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as unequal. |
: : treating two NaNs as unequal. : | `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. |
| `FloatEq(a_float)` | `argument` is a `float` value | | `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. |
: : approximately equal to `a_float`, : <!-- mdformat on -->
: : 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 googletest). 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 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 `NanSensitive*` version instead treats two NaNs as equal, which is often what a
user wants. user wants.
| Matcher | Description | <!-- mdformat off(no multiline tables) -->
| :---------------------------------- | :------------------------------------- | | Matcher | Description |
| `DoubleNear(a_double, | `argument` is a `double` value close | | :------------------------------------------------ | :----------------------- |
: max_abs_error)` : to `a_double` (absolute error <= : | `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. |
: : `max_abs_error`), treating two NaNs as : | `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. |
: : 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. |
| `FloatNear(a_float, max_abs_error)` | `argument` is a `float` value close to | | `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. |
: : `a_float` (absolute error <= : <!-- mdformat on -->
: : `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. :
#### String Matchers #### String Matchers
The `argument` can be either a C string or a C++ string object: The `argument` can be either a C string or a C++ string object:
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :---------------------- | :------------------------------------------------- | | :---------------------- | :------------------------------------------------- |
| `ContainsRegex(string)` | `argument` matches the given regular expression. | | `ContainsRegex(string)` | `argument` matches the given regular expression. |
| `EndsWith(suffix)` | `argument` ends with string `suffix`. | | `EndsWith(suffix)` | `argument` ends with string `suffix`. |
| `HasSubstr(string)` | `argument` contains `string` as a sub-string. | | `HasSubstr(string)` | `argument` contains `string` as a sub-string. |
| `MatchesRegex(string)` | `argument` matches the given regular expression | | `MatchesRegex(string)` | `argument` matches the given regular expression with the match starting at the first character and ending at the last character. |
: : with the match starting at the first character and :
: : ending at the last character. :
| `StartsWith(prefix)` | `argument` starts with string `prefix`. | | `StartsWith(prefix)` | `argument` starts with string `prefix`. |
| `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. | | `StrCaseEq(string)` | `argument` is equal to `string`, ignoring case. |
| `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring | | `StrCaseNe(string)` | `argument` is not equal to `string`, ignoring case. |
: : case. :
| `StrEq(string)` | `argument` is equal to `string`. | | `StrEq(string)` | `argument` is equal to `string`. |
| `StrNe(string)` | `argument` is not equal to `string`. | | `StrNe(string)` | `argument` is not equal to `string`. |
<!-- mdformat on -->
`ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They `ContainsRegex()` and `MatchesRegex()` take ownership of the `RE` object. They
use the regular expression syntax defined 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 write the elements in-line, match them more flexibly, or get more informative
messages, you can use: messages, you can use:
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :---------------------------------------- | :------------------------------- | | :---------------------------------------- | :------------------------------- |
| `BeginEndDistanceIs(m)` | `argument` is a container whose | | `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. |
: : `begin()` and `end()` iterators : | `ContainerEq(container)` | The same as `Eq(container)` except that the failure message also includes which elements are in one container but not the other. |
: : are separated by a number of : | `Contains(e)` | `argument` contains an element that matches `e`, which can be either a value or a matcher. |
: : increments matching `m`. E.g. : | `Each(e)` | `argument` is a container where *every* element matches `e`, which can be either a value or a matcher. |
: : `BeginEndDistanceIs(2)` or : | `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, where the *i*-th element matches `ei`, which can be a value or a matcher. |
: : `BeginEndDistanceIs(Lt(2))`. For : | `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. |
: : containers that define a : | `IsEmpty()` | `argument` is an empty container (`container.empty()`). |
: : `size()` method, `SizeIs(m)` may : | `IsFalse()` | `argument` evaluates to `false` in a Boolean context. |
: : be more efficient. : | `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. |
| `ContainerEq(container)` | The same as `Eq(container)` | | `IsSupersetOf({e0, e1, ..., en})`, `IsSupersetOf(a_container)`, `IsSupersetOf(begin, end)`, `IsSupersetOf(array)`, or `IsSupersetOf(array, count)` | Some subset of `argument` matches `UnorderedElementsAre(`expected matchers`)`. |
: : except that the failure message : | `IsTrue()` | `argument` evaluates to `true` in a Boolean context. |
: : also includes which elements are : | `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. |
: : in one container but not the : | `SizeIs(m)` | `argument` is a container whose size matches `m`. E.g. `SizeIs(2)` or `SizeIs(Lt(2))`. |
: : other. : | `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. |
| `Contains(e)` | `argument` contains an element | | `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. |
: : that matches `e`, which can be : | `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. |
: : either a value or a matcher. : | `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. |
| `Each(e)` | `argument` is a container where | | `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))`. |
: : *every* element matches `e`, : <!-- mdformat on -->
: : 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))`. :
**Notes:** **Notes:**
@ -462,41 +370,31 @@ messages, you can use:
#### Member Matchers #### Member Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :------------------------------ | :----------------------------------------- | | :------------------------------ | :----------------------------------------- |
| `Field(&class::field, m)` | `argument.field` (or `argument->field` | | `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_. |
: : when `argument` is a plain pointer) : | `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`. |
: : matches matcher `m`, where `argument` is : | `Pair(m1, m2)` | `argument` is an `std::pair` whose `first` field matches `m1` and `second` field matches `m2`. |
: : an object of type _class_. : | `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_. |
| `Key(e)` | `argument.first` matches `e`, which can be | <!-- mdformat on -->
: : 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, Functor, or Callback #### Matching the Result of a Function, Functor, or Callback
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :--------------- | :------------------------------------------------ | | :--------------- | :------------------------------------------------ |
| `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a | | `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. |
: : function or functor. : <!-- mdformat on -->
#### Pointer Matchers #### Pointer Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :------------------------ | :---------------------------------------------- | | :------------------------ | :---------------------------------------------- |
| `Pointee(m)` | `argument` (either a smart pointer or a raw | | `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. |
: : pointer) points to a value that matches matcher : | `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. |
: : `m`. : <!-- mdformat on -->
| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through |
: : `dynamic_cast<T>()`, it matches matcher `m`. :
<!-- GOOGLETEST_CM0026 DO NOT DELETE --> <!-- 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 You can use the following selectors to pick a subset of the arguments (or
reorder them) to participate in the matching: reorder them) to participate in the matching:
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :------------------------- | :---------------------------------------------- | | :------------------------- | :---------------------------------------------- |
| `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in | | `AllArgs(m)` | Equivalent to `m`. Useful as syntactic sugar in `.With(AllArgs(m))`. |
: : `.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())`. |
| `Args<N1, N2, ..., Nk>(m)` | The tuple of the `k` selected (using 0-based | <!-- mdformat on -->
: : indices) arguments matches `m`, e.g. `Args<1, :
: : 2>(Eq())`. :
#### Composite Matchers #### Composite Matchers
You can make a matcher from one or more other matchers: You can make a matcher from one or more other matchers:
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :------------------------------- | :-------------------------------------- | | :------------------------------- | :-------------------------------------- |
| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers | | `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. |
: : `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. |
| `AllOfArray({m0, m1, ..., mn})`, | The same as `AllOf()` except that the | | `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. |
: `AllOfArray(a_container)`, : matchers come from an initializer list, : | `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. |
: `AllOfArray(begin, end)`, : STL-style container, iterator range, or : | `Not(m)` | `argument` doesn't match matcher `m`. |
: `AllOfArray(array)`, or : C-style array. : <!-- mdformat on -->
: `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`. |
<!-- GOOGLETEST_CM0028 DO NOT DELETE --> <!-- GOOGLETEST_CM0028 DO NOT DELETE -->
#### Adapters for Matchers #### Adapters for Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :---------------------- | :------------------------------------ | | :---------------------- | :------------------------------------ |
| `MatcherCast<T>(m)` | casts matcher `m` to type | | `MatcherCast<T>(m)` | casts matcher `m` to type `Matcher<T>`. |
: : `Matcher<T>`. : | `SafeMatcherCast<T>(m)` | [safely casts](cook_book.md#casting-matchers) matcher `m` to type `Matcher<T>`. |
| `SafeMatcherCast<T>(m)` | [safely | | `Truly(predicate)` | `predicate(argument)` returns something considered by C++ to be true, where `predicate` is a function or functor. |
: : casts](cook_book.md#casting-matchers) : <!-- mdformat on -->
: : 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. :
`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`, `AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`,
which must be a permanent callback. which must be a permanent callback.
#### Using Matchers as Predicates {#MatchersAsPredicatesCheat} #### Using Matchers as Predicates {#MatchersAsPredicatesCheat}
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :---------------------------- | :------------------------------------------ | | :---------------------------- | :------------------------------------------ |
| `Matches(m)(value)` | 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. |
: : You can use `Matches(m)` alone as a unary : | `ExplainMatchResult(m, value, result_listener)` | evaluates to `true` if `value` matches `m`, explaining the result to `result_listener`. |
: : functor. : | `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
| `ExplainMatchResult(m, value, | evaluates to `true` if `value` matches `m`, | <!-- mdformat on -->
: result_listener)` : explaining the result to `result_listener`. :
| `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
#### Defining Matchers #### Defining Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :----------------------------------- | :------------------------------------ | | :----------------------------------- | :------------------------------------ |
| `MATCHER(IsEven, "") { return (arg % | Defines a matcher `IsEven()` to match | | `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. |
: 2) == 0; }` : 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_P(IsDivisibleBy, n, "") { | Defines a macher `IsDivisibleBy(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`]. |
: *result_listener << "where the : to match a number divisible by `n`. : <!-- mdformat on -->
: 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; }` : :
**Notes:** **Notes:**
@ -612,78 +489,51 @@ which must be a permanent callback.
#### Returning a Value #### Returning a Value
<!-- mdformat off(no multiline tables) -->
| | | | | |
| :-------------------------- | :-------------------------------------------- | | :-------------------------- | :-------------------------------------------- |
| `Return()` | Return from a `void` mock function. | | `Return()` | Return from a `void` mock function. |
| `Return(value)` | Return `value`. If the type of `value` is | | `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. |
: : 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. | | `ReturnArg<N>()` | Return the `N`-th (0-based) argument. |
| `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different | | `ReturnNew<T>(a1, ..., ak)` | Return `new T(a1, ..., ak)`; a different object is created each time. |
: : object is created each time. :
| `ReturnNull()` | Return a null pointer. | | `ReturnNull()` | Return a null pointer. |
| `ReturnPointee(ptr)` | Return the value pointed to by `ptr`. | | `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 | | `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. |
: : copy lives as long as the action. : <!-- mdformat on -->
#### Side Effects #### Side Effects
<!-- mdformat off(no multiline tables) -->
| | | | | |
| :--------------------------------- | :-------------------------------------- | | :--------------------------------- | :-------------------------------------- |
| `Assign(&variable, value)` | Assign `value` to variable. | | `Assign(&variable, value)` | Assign `value` to variable. |
| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, | | `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, which must be a pointer. |
: : which must be a pointer. : | `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to `*pointer`. |
| `SaveArg<N>(pointer)` | Save the `N`-th (0-based) argument to | | `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th (0-based) argument to `*pointer`. |
: : `*pointer`. : | `SetArgReferee<N>(value)` | Assign value to the variable referenced by the `N`-th (0-based) argument. |
| `SaveArgPointee<N>(pointer)` | Save the value pointed to by the `N`-th | | `SetArgPointee<N>(value)` | Assign `value` to the variable pointed by the `N`-th (0-based) argument. |
: : (0-based) argument to `*pointer`. : | `SetArgumentPointee<N>(value)` | Same as `SetArgPointee<N>(value)`. Deprecated. Will be removed in v1.7.0. |
| `SetArgReferee<N>(value)` | Assign value to the variable referenced | | `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. |
: : by the `N`-th (0-based) argument. : | `SetErrnoAndReturn(error, value)` | Set `errno` to `error` and return `value`. |
| `SetArgPointee<N>(value)` | Assign `value` to the variable pointed | | `Throw(exception)` | Throws the given exception, which can be any copyable value. Available since v1.1.0. |
: : by the `N`-th (0-based) argument. : <!-- mdformat on -->
| `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 #### Using a Function, Functor, or Lambda as an Action
In the following, by "callable" we mean a free function, `std::function`, In the following, by "callable" we mean a free function, `std::function`,
functor, or lambda. functor, or lambda.
<!-- mdformat off(no multiline tables) -->
| | | | | |
| :---------------------------------- | :------------------------------------- | | :---------------------------------- | :------------------------------------- |
| `f` | Invoke f with the arguments passed to | | `f` | Invoke f with the arguments passed to the mock function, where f is a callable. |
: : the mock function, where f is a : | `Invoke(f)` | Invoke `f` with the arguments passed to the mock function, where `f` can be a global/static function or a functor. |
: : callable. : | `Invoke(object_pointer, &class::method)` | Invoke the method on the object with the arguments passed to the mock function. |
| `Invoke(f)` | Invoke `f` with the arguments passed | | `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. |
: : to the mock function, where `f` can be : | `InvokeWithoutArgs(object_pointer, &class::method)` | Invoke the method on the object, which takes no arguments. |
: : a global/static function or a functor. : | `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. |
| `Invoke(object_pointer, | Invoke the method on the object with | <!-- mdformat on -->
: &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. :
The return value of the invoked function is used as the return value of the The return value of the invoked function is used as the return value of the
action. action.
@ -725,10 +575,11 @@ value, and `foo` by reference.
#### Default Action #### Default Action
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :------------ | :----------------------------------------------------- | | :------------ | :----------------------------------------------------- |
| `DoDefault()` | Do the default action (specified by `ON_CALL()` or the | | `DoDefault()` | Do the default action (specified by `ON_CALL()` or the built-in one). |
: : built-in one). : <!-- mdformat on -->
**Note:** due to technical reasons, `DoDefault()` cannot be used inside a **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 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 #### Composite Actions
<!-- mdformat off(no multiline tables) -->
| | | | | |
| :----------------------------- | :------------------------------------------ | | :----------------------------- | :------------------------------------------ |
| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the | | `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. |
: : result of `an` in each invocation. The : | `IgnoreResult(a)` | Perform action `a` and ignore its result. `a` must not return void. |
: : first `n - 1` sub-actions must return void. : | `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. |
| `IgnoreResult(a)` | Perform action `a` and ignore its result. | | `WithArgs<N1, N2, ..., Nk>(a)` | Pass the selected (0-based) arguments of the mock function to action `a` and perform it. |
: : `a` must not return void. : | `WithoutArgs(a)` | Perform action `a` without any arguments. |
| `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the | <!-- mdformat on -->
: : 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 #### Defining Actions
@ -766,17 +613,13 @@ composite action - trying to do so will result in a run-time error.
</tr> </tr>
</table> </table>
<!-- mdformat off(no multiline tables) -->
| | | | | |
| :--------------------------------- | :-------------------------------------- | | :--------------------------------- | :-------------------------------------- |
| `ACTION(Sum) { return arg0 + arg1; | Defines an action `Sum()` to return the | | `ACTION(Sum) { return arg0 + arg1; }` | Defines an action `Sum()` to return the sum of the mock function's argument #0 and #1. |
: }` : sum of the mock function's argument #0 : | `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`. |
: : and #1. : | `ACTION_Pk(Foo, p1, ..., pk) { statements; }` | Defines a parameterized action `Foo(p1, ..., pk)` to execute the given `statements`. |
| `ACTION_P(Plus, n) { return arg0 + | Defines an action `Plus(n)` to return | <!-- mdformat on -->
: 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`. :
The `ACTION*` macros cannot be used inside a function or class. 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 These are used in `Times()` to specify how many times a mock function will be
called: called:
<!-- mdformat off(no multiline tables) -->
| | | | | |
| :---------------- | :----------------------------------------------------- | | :---------------- | :----------------------------------------------------- |
| `AnyNumber()` | The function can be called any number of times. | | `AnyNumber()` | The function can be called any number of times. |
| `AtLeast(n)` | The call is expected at least `n` times. | | `AtLeast(n)` | The call is expected at least `n` times. |
| `AtMost(n)` | The call is expected at most `n` times. | | `AtMost(n)` | The call is expected at most `n` times. |
| `Between(m, n)` | The call is expected between `m` and `n` (inclusive) | | `Between(m, n)` | The call is expected between `m` and `n` (inclusive) times. |
: : times. : | `Exactly(n) or n` | The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0. |
| `Exactly(n) or n` | The call is expected exactly `n` times. In particular, | <!-- mdformat on -->
: : the call should never happen when `n` is 0. :
### Expectation Order ### Expectation Order
@ -918,10 +761,9 @@ See this [recipe](cook_book.md#using-check-points) for one application of it.
### Flags ### Flags
<!-- mdformat off(no multiline tables) -->
| Flag | Description | | Flag | Description |
| :----------------------------- | :---------------------------------------- | | :----------------------------- | :---------------------------------------- |
| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as | | `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. |
: : 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`, | <!-- mdformat on -->
: : `warning`, or `error`) of Google Mock :
: : messages. :

5
googlemock/docs/cook_book.md
View File

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