diff options
Diffstat (limited to 'googlemock/docs/cook_book.md')
-rw-r--r-- | googlemock/docs/cook_book.md | 88 |
1 files changed, 78 insertions, 10 deletions
diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md index a858cd1f..0352ef65 100644 --- a/googlemock/docs/cook_book.md +++ b/googlemock/docs/cook_book.md @@ -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} @@ -1037,7 +1038,7 @@ arguments as *one* single tuple to the predicate. Have you noticed that a matcher is just a fancy predicate that also knows how to describe itself? Many existing algorithms take predicates as arguments (e.g. those defined in STL's `<algorithm>` header), and it would be a shame if gMock -matchers are not allowed to participate. +matchers were not allowed to participate. Luckily, you can use a matcher where a unary predicate functor is expected by wrapping it inside the `Matches()` function. For example, @@ -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 @@ -1192,11 +1195,12 @@ that satisfies matcher `m`. For example: +<!-- mdformat off(github rendering does not support multiline tables) --> | Expression | Description | | :--------------------------- | :--------------------------------------- | | `Field(&Foo::number, Ge(3))` | Matches `x` where `x.number >= 3`. | -| `Property(&Foo::name, | Matches `x` where `x.name()` starts with | -: StartsWith("John "))` : `"John "`. : +| `Property(&Foo::name, StartsWith("John "))` | Matches `x` where `x.name()` starts with `"John "`. | +<!-- mdformat on --> Note that in `Property(&Foo::baz, ...)`, method `baz()` must take no argument and be declared as `const`. @@ -1242,7 +1246,7 @@ what if you want to make sure the value *pointed to* by the pointer, instead of the pointer itself, has a certain property? Well, you can use the `Pointee(m)` matcher. -`Pointee(m)` matches a pointer iff `m` matches the value the pointer points to. +`Pointee(m)` matches a pointer if `m` matches the value the pointer points to. For example: ```cpp @@ -2147,7 +2151,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 { @@ -2596,7 +2604,7 @@ However, if the action has its own state, you may be surprised if you share the action object. Suppose you have an action factory `IncrementCounter(init)` which creates an action that increments and returns a counter whose initial value is `init`, using two actions created from the same expression and using a shared -action will exihibit different behaviors. Example: +action will exhibit different behaviors. Example: ```cpp EXPECT_CALL(foo, DoThis()) @@ -3239,6 +3247,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 @@ -3539,7 +3549,7 @@ class MatcherInterface { public: virtual ~MatcherInterface(); - // Returns true iff the matcher matches x; also explains the match + // Returns true if the matcher matches x; also explains the match // result to 'listener'. virtual bool MatchAndExplain(T x, MatchResultListener* listener) const = 0; @@ -3693,10 +3703,10 @@ class CardinalityInterface { public: virtual ~CardinalityInterface(); - // Returns true iff call_count calls will satisfy this cardinality. + // Returns true if call_count calls will satisfy this cardinality. virtual bool IsSatisfiedByCallCount(int call_count) const = 0; - // Returns true iff call_count calls will saturate this cardinality. + // Returns true if call_count calls will saturate this cardinality. virtual bool IsSaturatedByCallCount(int call_count) const = 0; // Describes self to an ostream. @@ -4175,3 +4185,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 --> |