gitMirror/googletest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Googletest export

Browse Source 
Internal change

PiperOrigin-RevId: 356867746
This commit is contained in:
Abseil Team
2021-02-10 20:39:22 -05:00
committed by Derek Mauro
parent 609281088c
commit e935e6c387
5 changed files with 7 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
docs/advanced.md
View File

@@ -99,7 +99,6 @@ If you already have a function or functor that returns `bool` (or a type that
can be implicitly converted to `bool`), you can use it in a *predicate can be implicitly converted to `bool`), you can use it in a *predicate
assertion* to get the function arguments printed for free: assertion* to get the function arguments printed for free:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| --------------------------------- | --------------------------------- | --------------------------- | | --------------------------------- | --------------------------------- | --------------------------- |
@@ -107,7 +106,6 @@ assertion* to get the function arguments printed for free:
| `ASSERT_PRED2(pred2, val1, val2)` | `EXPECT_PRED2(pred2, val1, val2)` | `pred2(val1, val2)` is true | | `ASSERT_PRED2(pred2, val1, val2)` | `EXPECT_PRED2(pred2, val1, val2)` | `pred2(val1, val2)` is true |
| `...` | `...` | `...` | | `...` | `...` | `...` |
<!-- mdformat on -->
In the above, `predn` is an `n`-ary predicate function or functor, where `val1`, In the above, `predn` is an `n`-ary predicate function or functor, where `val1`,
`val2`, ..., and `valn` are its arguments. The assertion succeeds if the `val2`, ..., and `valn` are its arguments. The assertion succeeds if the
predicate returns `true` when applied to the given arguments, and fails predicate returns `true` when applied to the given arguments, and fails
@@ -329,26 +327,22 @@ want to learn more, see
#### Floating-Point Macros #### Floating-Point Macros
<!-- mdformat off(github rendering does not support multiline tables) -->
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------- | ------------------------------- | ---------------------------------------- | | ------------------------------- | ------------------------------- | ---------------------------------------- |
| `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1, val2);` | the two `float` values are almost equal | | `ASSERT_FLOAT_EQ(val1, val2);` | `EXPECT_FLOAT_EQ(val1, val2);` | the two `float` values are almost equal |
| `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);` | the two `double` values are almost equal | | `ASSERT_DOUBLE_EQ(val1, val2);` | `EXPECT_DOUBLE_EQ(val1, val2);` | the two `double` values are almost equal |
<!-- mdformat on -->
By "almost equal" we mean the values are within 4 ULP's from each other. By "almost equal" we mean the values are within 4 ULP's from each other.
The following assertions allow you to choose the acceptable error bound: The following assertions allow you to choose the acceptable error bound:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- | | ------------------------------------- | ------------------------------------- | -------------------------------------------------------------------------------- |
| `ASSERT_NEAR(val1, val2, abs_error);` | `EXPECT_NEAR(val1, val2, abs_error);` | the difference between `val1` and `val2` doesn't exceed the given absolute error | | `ASSERT_NEAR(val1, val2, abs_error);` | `EXPECT_NEAR(val1, val2, abs_error);` | the difference between `val1` and `val2` doesn't exceed the given absolute error |
<!-- mdformat on -->
#### Floating-Point Predicate-Format Functions #### Floating-Point Predicate-Format Functions
@@ -373,13 +367,11 @@ validating arguments passed to mock objects. A gMock *matcher* is basically a
predicate that knows how to describe itself. It can be used in these assertion predicate that knows how to describe itself. It can be used in these assertion
macros: macros:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| ------------------------------ | ------------------------------ | --------------------- | | ------------------------------ | ------------------------------ | --------------------- |
| `ASSERT_THAT(value, matcher);` | `EXPECT_THAT(value, matcher);` | value matches matcher | | `ASSERT_THAT(value, matcher);` | `EXPECT_THAT(value, matcher);` | value matches matcher |
<!-- mdformat on -->
For example, `StartsWith(prefix)` is a matcher that matches a string starting For example, `StartsWith(prefix)` is a matcher that matches a string starting
with `prefix`, and you can write: with `prefix`, and you can write:
@@ -1355,7 +1347,6 @@ for generating test parameters. They return what we call (surprise!) *parameter
generators*. Here is a summary of them, which are all in the `testing` generators*. Here is a summary of them, which are all in the `testing`
namespace: namespace:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Parameter Generator | Behavior | | Parameter Generator | Behavior |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
@@ -1365,7 +1356,6 @@ namespace:
| `Bool()` | Yields sequence `{false, true}`. | | `Bool()` | Yields sequence `{false, true}`. |
| `Combine(g1, g2, ..., gN)` | Yields all combinations (Cartesian product) as std\:\:tuples of the values generated by the `N` generators. | | `Combine(g1, g2, ..., gN)` | Yields all combinations (Cartesian product) as std\:\:tuples of the values generated by the `N` generators. |
<!-- mdformat on -->
For more details, see the comments at the definitions of these functions. For more details, see the comments at the definitions of these functions.
@@ -1428,8 +1418,8 @@ given test suite, whether their definitions come before or *after* the
You can see [sample7_unittest.cc] and [sample8_unittest.cc] for more examples. You can see [sample7_unittest.cc] and [sample8_unittest.cc] for more examples.
[sample7_unittest.cc]: ../googletest/samples/sample7_unittest.cc "Parameterized Test example" [sample7_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample7_unittest.cc "Parameterized Test example"
[sample8_unittest.cc]: ../googletest/samples/sample8_unittest.cc "Parameterized Test example with multiple parameters" [sample8_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample8_unittest.cc "Parameterized Test example with multiple parameters"
### Creating Value-Parameterized Abstract Tests ### Creating Value-Parameterized Abstract Tests
@@ -1579,7 +1569,7 @@ TYPED_TEST(FooTest, HasPropertyA) { ... }
You can see [sample6_unittest.cc] for a complete example. You can see [sample6_unittest.cc] for a complete example.
[sample6_unittest.cc]: ../googletest/samples/sample6_unittest.cc "Typed Test example" [sample6_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample6_unittest.cc "Typed Test example"
## Type-Parameterized Tests ## Type-Parameterized Tests
@@ -2022,7 +2012,7 @@ You can do so by adding one line:
Now, sit back and enjoy a completely different output from your tests. For more Now, sit back and enjoy a completely different output from your tests. For more
details, see [sample9_unittest.cc]. details, see [sample9_unittest.cc].
[sample9_unittest.cc]: ../googletest/samples/sample9_unittest.cc "Event listener example" [sample9_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample9_unittest.cc "Event listener example"
You may append more than one listener to the list. When an `On*Start()` or You may append more than one listener to the list. When an `On*Start()` or
`OnTestPartResult()` event is fired, the listeners will receive it in the order `OnTestPartResult()` event is fired, the listeners will receive it in the order
@@ -2049,7 +2039,7 @@ by the former.
See [sample10_unittest.cc] for an example of a failure-raising listener. See [sample10_unittest.cc] for an example of a failure-raising listener.
[sample10_unittest.cc]: ../googletest/samples/sample10_unittest.cc "Failure-raising listener example" [sample10_unittest.cc]: https://github.com/google/googletest/blob/master/googletest/samples/sample10_unittest.cc "Failure-raising listener example"
## Running Test Programs: Advanced Options ## Running Test Programs: Advanced Options

4
docs/faq.md
View File

@@ -265,7 +265,7 @@ If necessary, you can continue to derive test fixtures from a derived fixture.
googletest has no limit on how deep the hierarchy can be. googletest has no limit on how deep the hierarchy can be.
For a complete example using derived test fixtures, see For a complete example using derived test fixtures, see
[sample5_unittest.cc](../googletest/samples/sample5_unittest.cc). [sample5_unittest.cc](https://github.com/google/googletest/blob/master/googletest/samples/sample5_unittest.cc).
## My compiler complains "void value not ignored as it ought to be." What does this mean? ## My compiler complains "void value not ignored as it ought to be." What does this mean?
@@ -670,7 +670,7 @@ there is an `std::ostream& operator<<(std::ostream&, const FooType&)` function
defined such that we can print a value of `FooType`. defined such that we can print a value of `FooType`.
In addition, if `FooType` is declared in a name space, the `<<` operator also In addition, if `FooType` is declared in a name space, the `<<` operator also
needs to be defined in the *same* name space. See https://abseil.io/tips/49 for details. needs to be defined in the *same* name space. See abseil.io/tips/49 for details.
## How do I suppress the memory leak messages on Windows? ## How do I suppress the memory leak messages on Windows?

44
docs/gmock_cheat_sheet.md
View File

@@ -226,12 +226,10 @@ 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 using two macros: `EXPECT_CALL()`, or use it to validate a value directly using two macros:
<!-- mdformat off(github rendering does not support multiline tables) -->
| Macro | Description | | Macro | Description |
| :----------------------------------- | :------------------------------------ | | :----------------------------------- | :------------------------------------ |
| `EXPECT_THAT(actual_value, matcher)` | Asserts that `actual_value` matches `matcher`. | | `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. | | `ASSERT_THAT(actual_value, matcher)` | The same as `EXPECT_THAT(actual_value, matcher)`, except that it generates a **fatal** failure. |
<!-- mdformat on -->
**Note:** Although equality matching via `EXPECT_THAT(actual_value, **Note:** Although equality matching via `EXPECT_THAT(actual_value,
expected_value)` is supported, prefer to make the comparison explicit via expected_value)` is supported, prefer to make the comparison explicit via
@@ -252,7 +250,6 @@ 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` |
@@ -269,7 +266,6 @@ Matcher | Description
| `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`. 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 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
@@ -285,7 +281,6 @@ Boolean. In other cases, you can use the basic
### 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 approximately equal to `a_double`, treating two NaNs as unequal. | | `DoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as unequal. |
@@ -293,7 +288,6 @@ Boolean. In other cases, you can use the basic
| `NanSensitiveDoubleEq(a_double)` | `argument` is a `double` value approximately equal to `a_double`, treating two NaNs as equal. | | `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. | | `NanSensitiveFloatEq(a_float)` | `argument` is a `float` value approximately equal to `a_float`, treating two NaNs as equal. |
| `IsNan()` | `argument` is any floating-point type with a NaN value. | | `IsNan()` | `argument` is any floating-point type with a NaN value. |
<!-- mdformat on -->
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
@@ -302,20 +296,17 @@ 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.
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | 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. | | `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. | | `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. | | `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. | | `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 ### 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. |
@@ -328,7 +319,6 @@ The `argument` can be either a C string or a C++ string object:
| `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`. | | `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
@@ -342,7 +332,6 @@ 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 `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. | | `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. |
@@ -361,7 +350,6 @@ messages, you can use:
| `UnorderedPointwise(m, container)`, `UnorderedPointwise(m, {e0, e1, ..., en})` | Like `Pointwise(m, container)`, but ignores the order of elements. | | `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. | | `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))`. | | `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:** **Notes:**
@@ -388,7 +376,6 @@ 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` 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_. |
@@ -398,7 +385,6 @@ messages, you can use:
| `FieldsAre(m...)` | `argument` is a compatible object where each field matches piecewise with `m...`. A compatible object is any that supports the `std::tuple_size<Obj>`+`get<I>(obj)` protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates. | | `FieldsAre(m...)` | `argument` is a compatible object where each field matches piecewise with `m...`. A compatible object is any that supports the `std::tuple_size<Obj>`+`get<I>(obj)` protocol. In C++17 and up this also supports types compatible with structured bindings, like aggregates. |
| `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_. The method `property()` must take no argument and be declared as `const`. | | `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_. The method `property()` must take no argument and be declared as `const`. |
| `Property(property_name, &class::property, m)` | The same as the two-parameter version, but provides a better error message. | `Property(property_name, &class::property, m)` | The same as the two-parameter version, but provides a better error message.
<!-- mdformat on -->
**Notes:** **Notes:**
@@ -408,22 +394,18 @@ messages, you can use:
### 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 function or functor. | | `ResultOf(f, m)` | `f(argument)` matches matcher `m`, where `f` is a function or functor. |
<!-- mdformat on -->
### Pointer Matchers ### Pointer Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :------------------------ | :---------------------------------------------- | | :------------------------ | :---------------------------------------------- |
| `Address(m)` | the result of `std::addressof(argument)` matches `m`. | | `Address(m)` | the result of `std::addressof(argument)` matches `m`. |
| `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. | | `Pointee(m)` | `argument` (either a smart pointer or a raw pointer) points to a value that matches matcher `m`. |
| `Pointer(m)` | `argument` (either a smart pointer or a raw pointer) contains a pointer that matches `m`. `m` will match against the raw pointer regardless of the type of `argument`. | | `Pointer(m)` | `argument` (either a smart pointer or a raw pointer) contains a pointer that matches `m`. `m` will match against the raw pointer regardless of the type of `argument`. |
| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. | | `WhenDynamicCastTo<T>(m)` | when `argument` is passed through `dynamic_cast<T>()`, it matches matcher `m`. |
<!-- mdformat on -->
### Multi-argument Matchers {#MultiArgMatchers} ### Multi-argument Matchers {#MultiArgMatchers}
@@ -443,18 +425,15 @@ 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 `.With(AllArgs(m))`. | | `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())`. | | `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 ### 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 `m1` to `mn`. | | `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to `mn`. |
@@ -462,40 +441,33 @@ You can make a matcher from one or more other matchers:
| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers `m1` to `mn`. | | `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. | | `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`. | | `Not(m)` | `argument` doesn't match matcher `m`. |
<!-- mdformat on -->
### Adapters for Matchers ### Adapters for Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :---------------------- | :------------------------------------ | | :---------------------- | :------------------------------------ |
| `MatcherCast<T>(m)` | casts matcher `m` to type `Matcher<T>`. | | `MatcherCast<T>(m)` | casts matcher `m` to type `Matcher<T>`. |
| `SafeMatcherCast<T>(m)` | [safely casts](gmock_cook_book.md#casting-matchers) matcher `m` to type `Matcher<T>`. | | `SafeMatcherCast<T>(m)` | [safely casts](gmock_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. | | `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`, `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`. You can use `Matches(m)` alone as a unary functor. | | `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`. | | `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`. | | `Value(value, m)` | evaluates to `true` if `value` matches `m`. |
<!-- mdformat on -->
### Defining Matchers ### Defining Matchers
<!-- mdformat off(no multiline tables) -->
| Matcher | Description | | Matcher | Description |
| :----------------------------------- | :------------------------------------ | | :----------------------------------- | :------------------------------------ |
| `MATCHER(IsEven, "") { return (arg % 2) == 0; }` | Defines a matcher `IsEven()` to match an even number. | | `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 matcher `IsDivisibleBy(n)` to match a number divisible by `n`. | | `MATCHER_P(IsDivisibleBy, n, "") { *result_listener << "where the remainder is " << (arg % n); return (arg % n) == 0; }` | Defines a matcher `IsDivisibleBy(n)` to match a number divisible by `n`. |
| `MATCHER_P2(IsBetween, a, b, absl::StrCat(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`]. | | `MATCHER_P2(IsBetween, a, b, absl::StrCat(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:** **Notes:**
@@ -512,7 +484,6 @@ 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. |
@@ -524,11 +495,9 @@ which must be a permanent callback.
| `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. | | `ReturnRefOfCopy(value)` | Return a reference to a copy of `value`; the copy lives as long as the action. |
| `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. | | `ReturnRoundRobin({a1, ..., ak})` | Each call will return the next `ai` in the list, starting at the beginning when the end of the list is reached. |
<!-- 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. |
@@ -541,14 +510,12 @@ which must be a permanent callback.
| `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. | | `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`. | | `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. |
<!-- mdformat on -->
### 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 the mock function, where f is a callable. | | `f` | Invoke f with the arguments passed to the mock function, where f is a callable. |
@@ -557,7 +524,6 @@ functor, or lambda.
| `InvokeWithoutArgs(f)` | Invoke `f`, which can be a global/static function or a functor. `f` must take no arguments. | | `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. | | `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. | | `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 The return value of the invoked function is used as the return value of the
action. action.
@@ -598,18 +564,15 @@ 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 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 **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.
### Composite Actions ### 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 and will receive a readonly view of the 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 and will receive a readonly view of the arguments. |
@@ -617,17 +580,14 @@ composite action - trying to do so will result in a run-time error.
| `WithArg<N>(a)` | Pass the `N`-th (0-based) argument of the mock function to action `a` and perform it. | | `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. | | `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. |
<!-- mdformat on -->
### Defining Actions ### Defining Actions
<!-- 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(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_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`. | | `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. The `ACTION*` macros cannot be used inside a function or class.
@@ -636,7 +596,6 @@ 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. |
@@ -644,7 +603,6 @@ called:
| `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) 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. | | `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 ## Expectation Order
@@ -770,9 +728,7 @@ it.
## Flags ## Flags
<!-- mdformat off(no multiline tables) -->
| Flag | Description | | Flag | Description |
| :----------------------------- | :---------------------------------------- | | :----------------------------- | :---------------------------------------- |
| `--gmock_catch_leaked_mocks=0` | Don't report leaked mock objects as failures. | | `--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. |
<!-- mdformat on -->

4
docs/gmock_cook_book.md
View File

@@ -1250,12 +1250,10 @@ 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, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"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 Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument
and be declared as `const`. Don't use `Property()` against member functions that and be declared as `const`. Don't use `Property()` against member functions that
@@ -4123,7 +4121,6 @@ If you are writing a function that returns an `ACTION` object, you'll need to
know its type. The type depends on the macro used to define the action and the know its type. The type depends on the macro used to define the action and the
parameter types. The rule is relatively simple: parameter types. The rule is relatively simple:
<!-- mdformat off(GitHub does not support multiline tables) -->
| Given Definition | Expression | Has Type | | Given Definition | Expression | Has Type |
| ----------------------------- | ------------------- | --------------------- | | ----------------------------- | ------------------- | --------------------- |
@@ -4135,7 +4132,6 @@ parameter types. The rule is relatively simple:
| `ACTION_TEMPLATE(Baz, HAS_m_TEMPLATE_PARAMS(...), AND_2_VALUE_PARAMS(p1, p2))` | `Baz<t1, ..., t_m>(bool_value, int_value)` | `BazActionP2<t1, ..., t_m, bool, int>` | | `ACTION_TEMPLATE(Baz, HAS_m_TEMPLATE_PARAMS(...), AND_2_VALUE_PARAMS(p1, p2))` | `Baz<t1, ..., t_m>(bool_value, int_value)` | `BazActionP2<t1, ..., t_m, bool, int>` |
| ... | ... | ... | | ... | ... | ... |
<!-- mdformat on -->
Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`, Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`,
and etc) for actions with different numbers of value parameters, or the action and etc) for actions with different numbers of value parameters, or the action

4
docs/primer.md
View File

@@ -66,13 +66,11 @@ deprecated and refactored away.
So please be aware of the different definitions of the terms: So please be aware of the different definitions of the terms:
<!-- mdformat off(github rendering does not support multiline tables) -->
Meaning | googletest Term | [ISTQB](http://www.istqb.org/) Term Meaning | googletest Term | [ISTQB](http://www.istqb.org/) Term
:----------------------------------------------------------------------------------- | :---------------------- | :---------------------------------- :----------------------------------------------------------------------------------- | :---------------------- | :----------------------------------
Exercise a particular program path with specific input values and verify the results | [TEST()](#simple-tests) | [Test Case][istqb test case] Exercise a particular program path with specific input values and verify the results | [TEST()](#simple-tests) | [Test Case][istqb test case]
<!-- mdformat on -->
[istqb test case]: http://glossary.istqb.org/en/search/test%20case [istqb test case]: http://glossary.istqb.org/en/search/test%20case
[istqb test suite]: http://glossary.istqb.org/en/search/test%20suite [istqb test suite]: http://glossary.istqb.org/en/search/test%20suite
@@ -218,7 +216,6 @@ as `ASSERT_EQ(expected, actual)`, so lots of existing code uses this order. Now
The assertions in this group compare two **C strings**. If you want to compare The assertions in this group compare two **C strings**. If you want to compare
two `string` objects, use `EXPECT_EQ`, `EXPECT_NE`, and etc instead. two `string` objects, use `EXPECT_EQ`, `EXPECT_NE`, and etc instead.
<!-- mdformat off(github rendering does not support multiline tables) -->
| Fatal assertion | Nonfatal assertion | Verifies | | Fatal assertion | Nonfatal assertion | Verifies |
| -------------------------- | ------------------------------ | -------------------------------------------------------- | | -------------------------- | ------------------------------ | -------------------------------------------------------- |
@@ -227,7 +224,6 @@ two `string` objects, use `EXPECT_EQ`, `EXPECT_NE`, and etc instead.
| `ASSERT_STRCASEEQ(str1,str2);` | `EXPECT_STRCASEEQ(str1,str2);` | the two C strings have the same content, ignoring case | | `ASSERT_STRCASEEQ(str1,str2);` | `EXPECT_STRCASEEQ(str1,str2);` | the two C strings have the same content, ignoring case |
| `ASSERT_STRCASENE(str1,str2);` | `EXPECT_STRCASENE(str1,str2);` | the two C strings have different contents, ignoring case | | `ASSERT_STRCASENE(str1,str2);` | `EXPECT_STRCASENE(str1,str2);` | the two C strings have different contents, ignoring case |
<!-- mdformat on -->
Note that "CASE" in an assertion name means that case is ignored. A `NULL` Note that "CASE" in an assertion name means that case is ignored. A `NULL`
pointer and an empty string are considered *different*. pointer and an empty string are considered *different*.