diff options
Diffstat (limited to 'googlemock/docs')
| -rw-r--r-- | googlemock/docs/cheat_sheet.md | 239 | ||||
| -rw-r--r-- | googlemock/docs/cook_book.md | 77 | ||||
| -rw-r--r-- | googlemock/docs/for_dummies.md | 12 | ||||
| -rw-r--r-- | googlemock/docs/gmock_faq.md | 6 |
4 files changed, 234 insertions, 100 deletions
diff --git a/googlemock/docs/cheat_sheet.md b/googlemock/docs/cheat_sheet.md index ea46a68c..6441a7a8 100644 --- a/googlemock/docs/cheat_sheet.md +++ b/googlemock/docs/cheat_sheet.md @@ -1,6 +1,8 @@ ## gMock Cheat Sheet -<!-- GOOGLETEST_CM0018 DO NOT DELETE --> +<!-- GOOGLETEST_CM0019 DO NOT DELETE --> + +<!-- GOOGLETEST_CM0033 DO NOT DELETE --> ### Defining a Mock Class @@ -215,7 +217,7 @@ and the default action will be taken each time. ### Matchers {#MatcherList} -<!-- GOOGLETEST_CM0019 DO NOT DELETE --> +<!-- GOOGLETEST_CM0020 DO NOT DELETE --> A **matcher** matches a *single* argument. You can use it inside `ON_CALL()` or `EXPECT_CALL()`, or use it to validate a value directly: @@ -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 :-------------------------- | :----------------------------------------------- @@ -340,67 +342,99 @@ or simply `expected_container` to match a container exactly. If you want to write the elements in-line, match them more flexibly, or get more informative messages, you can use: -| Matcher | Description | -| :----------------------------------- | :----------------------------------- | -| `ContainerEq(container)` | The same as `Eq(container)` except | -: : that the failure message also : -: : includes which elements are in one : -: : container but not the other. : -| `Contains(e)` | `argument` contains an element that | -: : matches `e`, which can be either a : -: : value or a matcher. : -| `Each(e)` | `argument` is a container where | -: : _every_ element matches `e`, which : -: : can be either a value or a matcher. : -| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, | -: : where the i-th element matches `ei`, : -: : which can be a value or a matcher. 0 : -: : to 10 arguments are allowed. : -| `ElementsAreArray({ e0, e1, ..., en | The same as `ElementsAre()` except | -: })`, `ElementsAreArray(array)`, or : that the expected element : -: `ElementsAreArray(array, count)` : values/matchers come from an : -: : initializer list, STL-style : -: : container, or C-style array. : -| `IsEmpty()` | `argument` is an empty container | -: : (`container.empty()`). : -| `Pointwise(m, container)` | `argument` contains the same number | -: : of elements as in `container`, and : -: : for all i, (the i-th element in : -: : `argument`, the i-th element in : -: : `container`) match `m`, which is a : -: : matcher on 2-tuples. E.g. : -: : `Pointwise(Le(), upper_bounds)` : -: : verifies that each element in : -: : `argument` doesn't exceed the : -: : corresponding element in : -: : `upper_bounds`. See more detail : -: : below. : -| `SizeIs(m)` | `argument` is a container whose size | -: : matches `m`. E.g. `SizeIs(2)` or : -: : `SizeIs(Lt(2))`. : -| `UnorderedElementsAre(e0, e1, ..., | `argument` has `n + 1` elements, and | -: en)` : under some permutation each element : -: : matches an `ei` (for a different : -: : `i`), which can be a value or a : -: : matcher. 0 to 10 arguments are : -: : allowed. : -| `UnorderedElementsAreArray({ e0, e1, | The same as `UnorderedElementsAre()` | -: ..., en })`, : except that the expected element : -: `UnorderedElementsAreArray(array)`, : values/matchers come from an : -: or `UnorderedElementsAreArray(array, : initializer list, STL-style : -: count)` : container, or C-style array. : -| `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<int>(), : -: : ElementsAre(3, 2, 1))`. : +| Matcher | Description | +| :---------------------------------------- | :------------------------------- | +| `BeginEndDistanceIs(m)` | `argument` is a container whose | +: : `begin()` and `end()` iterators : +: : are separated by a number of : +: : increments matching `m`. E.g. : +: : `BeginEndDistanceIs(2)` or : +: : `BeginEndDistanceIs(Lt(2))`. For : +: : containers that define a : +: : `size()` method, `SizeIs(m)` may : +: : be more efficient. : +| `ContainerEq(container)` | The same as `Eq(container)` | +: : except that the failure message : +: : also includes which elements are : +: : in one container but not the : +: : other. : +| `Contains(e)` | `argument` contains an element | +: : that matches `e`, which can be : +: : either a value or a matcher. : +| `Each(e)` | `argument` is a container where | +: : *every* element matches `e`, : +: : which can be either a value or a : +: : matcher. : +| `ElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, | +: : where the *i*-th element matches : +: : `ei`, which can be a value or a : +: : matcher. : +| `ElementsAreArray({e0, e1, ..., en})`, | The same as `ElementsAre()` | +: `ElementsAreArray(a_container)`, : except that the expected element : +: `ElementsAreArray(begin, end)`, : values/matchers come from an : +: `ElementsAreArray(array)`, or : initializer list, STL-style : +: `ElementsAreArray(array, count)` : container, iterator range, or : +: : C-style array. : +| `IsEmpty()` | `argument` is an empty container | +: : (`container.empty()`). : +| `IsFalse()` | `argument` evaluates to `false` | +: : in a Boolean context. : +| `IsSubsetOf({e0, e1, ..., en})`, | `argument` matches | +: `IsSubsetOf(a_container)`, : `UnorderedElementsAre(x0, x1, : +: `IsSubsetOf(begin, end)`, : ..., xk)` for some subset `{x0, : +: `IsSubsetOf(array)`, or : x1, ..., xk}` of the expected : +: `IsSubsetOf(array, count)` : matchers. : +| `IsSupersetOf({e0, e1, ..., en})`, | Some subset of `argument` | +: `IsSupersetOf(a_container)`, : matches : +: `IsSupersetOf(begin, end)`, : `UnorderedElementsAre(`expected : +: `IsSupersetOf(array)`, or : matchers`)`. : +: `IsSupersetOf(array, count)` : : +| `IsTrue()` | `argument` evaluates to `true` | +: : in a Boolean context. : +| `Pointwise(m, container)`, `Pointwise(m, | `argument` contains the same | +: {e0, e1, ..., en})` : number of elements as in : +: : `container`, and for all i, (the : +: : i-th element in `argument`, the : +: : i-th element in `container`) : +: : match `m`, which is a matcher on : +: : 2-tuples. E.g. `Pointwise(Le(), : +: : upper_bounds)` verifies that : +: : each element in `argument` : +: : doesn't exceed the corresponding : +: : element in `upper_bounds`. See : +: : more detail below. : +| `SizeIs(m)` | `argument` is a container whose | +: : size matches `m`. E.g. : +: : `SizeIs(2)` or `SizeIs(Lt(2))`. : +| `UnorderedElementsAre(e0, e1, ..., en)` | `argument` has `n + 1` elements, | +: : and under *some* permutation of : +: : the elements, each element : +: : matches an `ei` (for a different : +: : `i`), which can be a value or a : +: : matcher. : +| `UnorderedElementsAreArray({e0, e1, ..., | The same as | +: en})`, : `UnorderedElementsAre()` except : +: `UnorderedElementsAreArray(a_container)`, : that the expected element : +: `UnorderedElementsAreArray(begin, end)`, : values/matchers come from an : +: `UnorderedElementsAreArray(array)`, or : initializer list, STL-style : +: `UnorderedElementsAreArray(array, count)` : container, iterator range, or : +: : C-style array. : +| `UnorderedPointwise(m, container)`, | Like `Pointwise(m, container)`, | +: `UnorderedPointwise(m, {e0, e1, ..., : but ignores the order of : +: en})` : elements. : +| `WhenSorted(m)` | When `argument` is sorted using | +: : the `<` operator, it matches : +: : container matcher `m`. E.g. : +: : `WhenSorted(ElementsAre(1, 2, : +: : 3))` verifies that `argument` : +: : contains elements 1, 2, and 3, : +: : ignoring order. : +| `WhenSortedBy(comparator, m)` | The same as `WhenSorted(m)`, | +: : except that the given comparator : +: : instead of `<` is used to sort : +: : `argument`. E.g. : +: : `WhenSortedBy(std\:\:greater(), : +: : ElementsAre(3, 2, 1))`. : **Notes:** @@ -463,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 @@ -493,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 @@ -518,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 | | :---------------------------- | :------------------------------------------ | @@ -555,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 | @@ -587,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, | @@ -620,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. : @@ -676,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 | | :------------ | :----------------------------------------------------- | @@ -686,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 : @@ -702,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 - -| Matcher | Description | +#### Defining Actions + +<table border="1" cellspacing="0" cellpadding="1"> + <tr> + <td>`struct SumAction {` <br> +  `template <typename T>` <br> +  `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 : @@ -723,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. | diff --git a/googlemock/docs/cook_book.md b/googlemock/docs/cook_book.md index 7116fd4c..17c26459 100644 --- a/googlemock/docs/cook_book.md +++ b/googlemock/docs/cook_book.md @@ -1,6 +1,6 @@ -## Googletest Mocking (gMock) Cookbook +## gMock Cookbook -<!-- GOOGLETEST_CM0011 DO NOT DELETE --> +<!-- GOOGLETEST_CM0012 DO NOT DELETE --> You can find recipes for using gMock here. If you haven't yet, please read [this](for_dummies.md) first to make sure you understand the basics. @@ -154,7 +154,7 @@ class MockStack : public StackInterface<Elem> { #### Mocking Non-virtual Methods {#MockingNonVirtualMethods} gMock can mock non-virtual functions to be used in Hi-perf dependency -injection.<!-- GOOGLETEST_CM0016 DO NOT DELETE -->. +injection.<!-- GOOGLETEST_CM0017 DO NOT DELETE -->. In this case, instead of sharing a common base class with the real class, your mock class will be *unrelated* to the real class, but contain methods with the @@ -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 @@ -1455,7 +1458,7 @@ mock object and gMock. #### Knowing When to Expect {#UseOnCall} -<!-- GOOGLETEST_CM0017 DO NOT DELETE --> +<!-- GOOGLETEST_CM0018 DO NOT DELETE --> **`ON_CALL`** is likely the *single most under-utilized construct* in gMock. @@ -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 --> diff --git a/googlemock/docs/for_dummies.md b/googlemock/docs/for_dummies.md index b75c9a09..5551cd8b 100644 --- a/googlemock/docs/for_dummies.md +++ b/googlemock/docs/for_dummies.md @@ -1,6 +1,6 @@ -## Googletest Mocking (gMock) for Dummies {#GMockForDummies} +## gMock for Dummies {#GMockForDummies} -<!-- GOOGLETEST_CM0012 DO NOT DELETE --> +<!-- GOOGLETEST_CM0013 DO NOT DELETE --> ### What Is gMock? @@ -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: @@ -499,7 +501,7 @@ always return 100 as `n++` is only evaluated once. Similarly, `Return(new Foo)` will create a new `Foo` object when the `EXPECT_CALL()` is executed, and will return the same pointer every time. If you want the side effect to happen every time, you need to define a custom action, which we'll teach in the -[cook book](http://<!-- GOOGLETEST_CM0011 DO NOT DELETE -->). +[cook book](http://<!-- GOOGLETEST_CM0012 DO NOT DELETE -->). Time for another quiz! What do you think the following means? @@ -593,8 +595,8 @@ In this example, we test that `Foo()` calls the three expected functions in the order as written. If a call is made out-of-order, it will be an error. (What if you care about the relative order of some of the calls, but not all of -them? Can you specify an arbitrary partial order? The answer is ... yes! If you -are impatient, the details can be found [here](#PartialOrder).) +them? Can you specify an arbitrary partial order? The answer is ... yes! The +details can be found [here](cook_book.md#OrderedCalls).) #### All Expectations Are Sticky (Unless Said Otherwise) {#StickyExpectations} diff --git a/googlemock/docs/gmock_faq.md b/googlemock/docs/gmock_faq.md index 27f0eb06..8bc45b18 100644 --- a/googlemock/docs/gmock_faq.md +++ b/googlemock/docs/gmock_faq.md @@ -1,6 +1,6 @@ ## Legacy gMock FAQ {#GMockFaq} -<!-- GOOGLETEST_CM0020 DO NOT DELETE --> +<!-- GOOGLETEST_CM0021 DO NOT DELETE --> ### When I call a method on my mock object, the method for the real object is invoked instead. What's the problem? @@ -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 |