3party/googletest
0
0
Fork 0
mirror of https://github.com/google/googletest.git synced 2025-01-14 00:20:57 +08:00
Code Issues Projects Releases Wiki Activity

Manual docs tweaks still in preparation for including docs with code pushes

Browse Source
This commit is contained in:
Gennadiy Civil 2019-07-29 10:53:47 -04:00
parent c4b68b91f8
commit bb481d2da6
4 changed files with 130 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
googlemock/docs/cheat_sheet.md
View File

@ -2,6 +2,8 @@
<!-- GOOGLETEST_CM0019 DO NOT DELETE -->
<!-- GOOGLETEST_CM0033 DO NOT DELETE -->
### Defining a Mock Class
#### Mocking a Normal Class {#MockClass}
@ -232,7 +234,7 @@ A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or
Built-in matchers (where `argument` is the function argument) are divided into
several categories:
## Wildcard
#### Wildcard
Matcher | Description
:-------------------------- | :-----------------------------------------------
@ -495,6 +497,10 @@ messages, you can use:
| `WhenDynamicCastTo<T>(m)` | when `argument` is passed through |
: : `dynamic_cast<T>()`, it matches matcher `m`. :
<!-- GOOGLETEST_CM0026 DO NOT DELETE -->
<!-- GOOGLETEST_CM0027 DO NOT DELETE -->
#### Multi-argument Matchers {#MultiArgMatchers}
Technically, all matchers match a *single* value. A "multi-argument" matcher is
@ -525,13 +531,25 @@ reorder them) to participate in the matching:
You can make a matcher from one or more other matchers:
| Matcher | Description |
| :----------------------- | :---------------------------------------------- |
| `AllOf(m1, m2, ..., mn)` | `argument` matches all of the matchers `m1` to |
: : `mn`. :
| `AnyOf(m1, m2, ..., mn)` | `argument` matches at least one of the matchers |
: : `m1` to `mn`. :
| `Not(m)` | `argument` doesn't match matcher `m`. |
| 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`. |
<!-- GOOGLETEST_CM0028 DO NOT DELETE -->
#### Adapters for Matchers
@ -550,7 +568,7 @@ You can make a matcher from one or more other matchers:
`AddressSatisfies(callback)` and `Truly(callback)` take ownership of `callback`,
which must be a permanent callback.
#### Matchers as Predicates {#MatchersAsPredicatesCheat}
#### Using Matchers as Predicates {#MatchersAsPredicatesCheat}
| Matcher | Description |
| :---------------------------- | :------------------------------------------ |
@ -587,20 +605,13 @@ which must be a permanent callback.
1. You can use `PrintToString(x)` to convert a value `x` of any type to a
string.
## Matchers as Test Assertions
Matcher | Description
:--------------------------- | :----------
`ASSERT_THAT(expression, m)` | Generates a [fatal failure](../../googletest/docs/primer.md#assertions) if the value of `expression` doesn't match matcher `m`.
`EXPECT_THAT(expression, m)` | Generates a non-fatal failure if the value of `expression` doesn't match matcher `m`.
### Actions {#ActionList}
**Actions** specify what a mock function should do when invoked.
#### Returning a Value
| Matcher | Description |
| | |
| :-------------------------- | :-------------------------------------------- |
| `Return()` | Return from a `void` mock function. |
| `Return(value)` | Return `value`. If the type of `value` is |
@ -619,7 +630,7 @@ Matcher | Description
#### Side Effects
| Matcher | Description |
| | |
| :--------------------------------- | :-------------------------------------- |
| `Assign(&variable, value)` | Assign `value` to variable. |
| `DeleteArg<N>()` | Delete the `N`-th (0-based) argument, |
@ -652,8 +663,11 @@ Matcher | Description
In the following, by "callable" we mean a free function, `std::function`,
functor, lambda, or `google3`-style permanent callback.
| Matcher | Description |
| | |
| :---------------------------------- | :------------------------------------- |
| `f` | Invoke f with the arguments passed to |
: : the mock function, where f is a :
: : callable (except of google3 callback). :
| `Invoke(f)` | Invoke `f` with the arguments passed |
: : to the mock function, where `f` can be :
: : a global/static function or a functor. :
@ -708,7 +722,7 @@ InvokeArgument<2>(5, string("Hi"), ByRef(foo))
calls the mock function's #2 argument, passing to it `5` and `string("Hi")` by
value, and `foo` by reference.
## Default Action
#### Default Action
| Matcher | Description |
| :------------ | :----------------------------------------------------- |
@ -718,9 +732,11 @@ value, and `foo` by reference.
**Note:** due to technical reasons, `DoDefault()` cannot be used inside a
composite action - trying to do so will result in a run-time error.
## Composite Actions
<!-- GOOGLETEST_CM0032 DO NOT DELETE -->
| Matcher | Description |
#### Composite Actions
| | |
| :----------------------------- | :------------------------------------------ |
| `DoAll(a1, a2, ..., an)` | Do all actions `a1` to `an` and return the |
: : result of `an` in each invocation. The :
@ -734,9 +750,22 @@ composite action - trying to do so will result in a run-time error.
: : it. :
| `WithoutArgs(a)` | Perform action `a` without any arguments. |
## Defining Actions
#### Defining Actions
| Matcher | Description |
<table border="1" cellspacing="0" cellpadding="1">
<tr>
<td>`struct SumAction {` <br>
&emsp;`template <typename T>` <br>
&emsp;`T operator()(T x, Ty) { return x + y; }` <br>
`};`
</td>
<td> Defines a generic functor that can be used as an action summing its
arguments. </td> </tr>
<tr>
</tr>
</table>
| | |
| :--------------------------------- | :-------------------------------------- |
| `ACTION(Sum) { return arg0 + arg1; | Defines an action `Sum()` to return the |
: }` : sum of the mock function's argument #0 :
@ -755,7 +784,7 @@ The `ACTION*` macros cannot be used inside a function or class.
These are used in `Times()` to specify how many times a mock function will be
called:
| Matcher | Description |
| | |
| :---------------- | :----------------------------------------------------- |
| `AnyNumber()` | The function can be called any number of times. |
| `AtLeast(n)` | The call is expected at least `n` times. |

71
googlemock/docs/cook_book.md
View File

@ -1,4 +1,4 @@
## Googletest Mocking (gMock) Cookbook
## gMock Cookbook
<!-- GOOGLETEST_CM0012 DO NOT DELETE -->
@ -824,6 +824,7 @@ A frequently used matcher is `_`, which matches anything:
```cpp
EXPECT_CALL(foo, DoThat(_, NotNull()));
```
<!-- GOOGLETEST_CM0022 DO NOT DELETE -->
#### Combining Matchers {#CombiningMatchers}
@ -1138,6 +1139,8 @@ Note that the predicate function / functor doesn't have to return `bool`. It
works as long as the return value can be used as the condition in in statement
`if (condition) ...`.
<!-- GOOGLETEST_CM0023 DO NOT DELETE -->
#### Matching Arguments that Are Not Copyable
When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of
@ -2147,7 +2150,11 @@ own precedence order distinct from the `ON_CALL` precedence order.
#### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions}
If the built-in actions don't suit you, you can use an existing callable
(function, `std::function`, method, functor, lambda as an action. ```cpp
(function, `std::function`, method, functor, lambda as an action.
<!-- GOOGLETEST_CM0024 DO NOT DELETE -->
```cpp
using ::testing::_; using ::testing::Invoke;
class MockFoo : public Foo {
@ -3239,6 +3246,8 @@ If you are interested in the mock call trace but not the stack traces, you can
combine `--gmock_verbose=info` with `--gtest_stack_trace_depth=0` on the test
command line.
<!-- GOOGLETEST_CM0025 DO NOT DELETE -->
#### Running Tests in Emacs
If you build and run your tests in Emacs using the `M-x google-compile` command
@ -4175,3 +4184,61 @@ prints the raw bytes in the value and hopes that you the user can figure it out.
[googletest's advanced guide](../../googletest/docs/advanced.md#teaching-googletest-how-to-print-your-values)
explains how to extend the printer to do a better job at printing your
particular type than to dump the bytes.
### Useful Mocks Created Using gMock
<!--#include file="includes/g3_testing_LOGs.md"-->
<!--#include file="includes/g3_mock_callbacks.md"-->
#### Mock std::function {#MockFunction}
`std::function` is a general function type introduced in C++11. It is a
preferred way of passing callbacks to new interfaces. Functions are copiable,
and are not usually passed around by pointer, which makes them tricky to mock.
But fear not - `MockFunction` can help you with that.
`MockFunction<R(T1, ..., Tn)>` has a mock method `Call()` with the signature:
```cpp
R Call(T1, ..., Tn);
```
It also has a `AsStdFunction()` method, which creates a `std::function` proxy
forwarding to Call:
```cpp
std::function<R(T1, ..., Tn)> AsStdFunction();
```
To use `MockFunction`, first create `MockFunction` object and set up
expectations on its `Call` method. Then pass proxy obtained from
`AsStdFunction()` to the code you are testing. For example:
```cpp
TEST(FooTest, RunsCallbackWithBarArgument) {
// 1. Create a mock object.
MockFunction<int(string)> mock_function;
// 2. Set expectations on Call() method.
EXPECT_CALL(mock_function, Call("bar")).WillOnce(Return(1));
// 3. Exercise code that uses std::function.
Foo(mock_function.AsStdFunction());
// Foo's signature can be either of:
// void Foo(const std::function<int(string)>& fun);
// void Foo(std::function<int(string)> fun);
// 4. All expectations will be verified when mock_function
// goes out of scope and is destroyed.
}
```
Remember that function objects created with `AsStdFunction()` are just
forwarders. If you create multiple of them, they will share the same set of
expectations.
Although `std::function` supports unlimited number of arguments, `MockFunction`
implementation is limited to ten. If you ever hit that limit... well, your
callback has bigger problems than being mockable. :-)
<!-- GOOGLETEST_CM0034 DO NOT DELETE -->

4
googlemock/docs/for_dummies.md
View File

@ -1,4 +1,4 @@
## Googletest Mocking (gMock) for Dummies {#GMockForDummies}
## gMock for Dummies {#GMockForDummies}
<!-- GOOGLETEST_CM0013 DO NOT DELETE -->
@ -206,6 +206,8 @@ choosing the adaptor interface can make your code easier to write and more
readable (a net win in the long run), as you can choose `FooAdaptor` to fit your
specific domain much better than `Foo` does.
<!-- GOOGLETEST_CM0029 DO NOT DELETE -->
### Using Mocks in Tests
Once you have a mock class, using it is easy. The typical work flow is:

4
googlemock/docs/gmock_faq.md
View File

@ -81,6 +81,8 @@ void Bar(int* p); // Neither p nor *p is const.
void Bar(const int* p); // p is not const, but *p is.
```
<<!-- GOOGLETEST_CM0030 DO NOT DELETE -->
### I can't figure out why gMock thinks my expectations are not satisfied. What should I do?
You might want to run your test with `--gmock_verbose=info`. This flag lets
@ -124,6 +126,8 @@ using ::testing::_;
.Times(0);
```
<!-- GOOGLETEST_CM0031 DO NOT DELETE -->
### I have a failed test where gMock tells me TWICE that a particular expectation is not satisfied. Isn't this redundant?
When gMock detects a failure, it prints relevant information (the mock function