Googletest export
Updates headings. PiperOrigin-RevId: 271148974
This commit is contained in:
Abseil Team
Gennadiy Civil
parent
bf0fe874a2
commit
a783ade7c2
@ -1,4 +1,4 @@
|
||||
## gMock Cookbook
|
||||
# gMock Cookbook
|
||||
|
||||
<!-- GOOGLETEST_CM0012 DO NOT DELETE -->
|
||||
|
||||
@ -10,7 +10,7 @@ recommended to write `using ::testing::Foo;` once in your file before using the
|
||||
name `Foo` defined by gMock. We omit such `using` statements in this section for
|
||||
brevity, but you should do it in your own code.
|
||||
|
||||
### Creating Mock Classes
|
||||
## Creating Mock Classes
|
||||
|
||||
Mock classes are defined as normal classes, using the `MOCK_METHOD` macro to
|
||||
generate mocked methods. The macro gets 3 or 4 parameters:
|
||||
@ -36,7 +36,7 @@ generated method:
|
||||
* **`Calltype(...)`** - Sets the call type for the method (e.g. to
|
||||
`STDMETHODCALLTYPE`), useful in Windows.
|
||||
|
||||
#### Dealing with unprotected commas
|
||||
### Dealing with unprotected commas
|
||||
|
||||
Unprotected commas, i.e. commas which are not surrounded by parentheses, prevent
|
||||
`MOCK_METHOD` from parsing its arguments correctly:
|
||||
@ -74,7 +74,7 @@ class MockFoo {
|
||||
};
|
||||
```
|
||||
|
||||
#### Mocking Private or Protected Methods
|
||||
### Mocking Private or Protected Methods
|
||||
|
||||
You must always put a mock method definition (`MOCK_METHOD`) in a `public:`
|
||||
section of the mock class, regardless of the method being mocked being `public`,
|
||||
@ -108,7 +108,7 @@ class MockFoo : public Foo {
|
||||
};
|
||||
```
|
||||
|
||||
#### Mocking Overloaded Methods
|
||||
### Mocking Overloaded Methods
|
||||
|
||||
You can mock overloaded functions as usual. No special attention is required:
|
||||
|
||||
@ -152,7 +152,7 @@ class MockFoo : public Foo {
|
||||
};
|
||||
```
|
||||
|
||||
#### Mocking Class Templates
|
||||
### Mocking Class Templates
|
||||
|
||||
You can mock class templates just like any class.
|
||||
|
||||
@ -175,7 +175,7 @@ class MockStack : public StackInterface<Elem> {
|
||||
};
|
||||
```
|
||||
|
||||
#### Mocking Non-virtual Methods {#MockingNonVirtualMethods}
|
||||
### Mocking Non-virtual Methods {#MockingNonVirtualMethods}
|
||||
|
||||
gMock can mock non-virtual functions to be used in Hi-perf dependency
|
||||
injection.<!-- GOOGLETEST_CM0017 DO NOT DELETE -->
|
||||
@ -243,7 +243,7 @@ tests.
|
||||
... exercise reader ...
|
||||
```
|
||||
|
||||
#### Mocking Free Functions
|
||||
### Mocking Free Functions
|
||||
|
||||
It's possible to use gMock to mock a free function (i.e. a C-style function or a
|
||||
static method). You just need to rewrite your code to use an interface (abstract
|
||||
@ -279,7 +279,7 @@ If you are concerned about the performance overhead incurred by virtual
|
||||
functions, and profiling confirms your concern, you can combine this with the
|
||||
recipe for [mocking non-virtual methods](#MockingNonVirtualMethods).
|
||||
|
||||
#### Old-Style `MOCK_METHODn` Macros
|
||||
### Old-Style `MOCK_METHODn` Macros
|
||||
|
||||
Before the generic `MOCK_METHOD` macro was introduced, mocks where created using
|
||||
a family of macros collectively called `MOCK_METHODn`. These macros are still
|
||||
@ -337,7 +337,7 @@ Foo, bool(int))` </td> </tr> <tr> <td> New </td> <td> `MOCK_METHOD(bool, Foo,
|
||||
|
||||
</table>
|
||||
|
||||
#### The Nice, the Strict, and the Naggy {#NiceStrictNaggy}
|
||||
### The Nice, the Strict, and the Naggy {#NiceStrictNaggy}
|
||||
|
||||
If a mock method has no `EXPECT_CALL` spec but is called, we say that it's an
|
||||
"uninteresting call", and the default action (which can be specified using
|
||||
@ -444,7 +444,7 @@ nice mocks (not yet the default) most of the time, use naggy mocks (the current
|
||||
default) when developing or debugging tests, and use strict mocks only as the
|
||||
last resort.
|
||||
|
||||
#### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces}
|
||||
### Simplifying the Interface without Breaking Existing Code {#SimplerInterfaces}
|
||||
|
||||
Sometimes a method has a long list of arguments that is mostly uninteresting.
|
||||
For example:
|
||||
@ -516,7 +516,7 @@ ON_CALL(factory, DoMakeTurtle)
|
||||
.WillByDefault(MakeMockTurtle());
|
||||
```
|
||||
|
||||
#### Alternative to Mocking Concrete Classes
|
||||
### Alternative to Mocking Concrete Classes
|
||||
|
||||
Often you may find yourself using classes that don't implement interfaces. In
|
||||
order to test your code that uses such a class (let's call it `Concrete`), you
|
||||
@ -578,7 +578,7 @@ I'd like to assure you that the Java community has been practicing this for a
|
||||
long time and it's a proven effective technique applicable in a wide variety of
|
||||
situations. :-)
|
||||
|
||||
#### Delegating Calls to a Fake {#DelegatingToFake}
|
||||
### Delegating Calls to a Fake {#DelegatingToFake}
|
||||
|
||||
Some times you have a non-trivial fake implementation of an interface. For
|
||||
example:
|
||||
@ -696,7 +696,7 @@ Instead, you can define a `FileOps` interface and an `IOOps` interface and split
|
||||
`System`'s functionalities into the two. Then you can mock `IOOps` without
|
||||
mocking `FileOps`.
|
||||
|
||||
#### Delegating Calls to a Real Object
|
||||
### Delegating Calls to a Real Object
|
||||
|
||||
When using testing doubles (mocks, fakes, stubs, and etc), sometimes their
|
||||
behaviors will differ from those of the real objects. This difference could be
|
||||
@ -747,7 +747,7 @@ arguments, in the right order, called the right number of times, etc), and a
|
||||
real object will answer the calls (so the behavior will be the same as in
|
||||
production). This gives you the best of both worlds.
|
||||
|
||||
#### Delegating Calls to a Parent Class
|
||||
### Delegating Calls to a Parent Class
|
||||
|
||||
Ideally, you should code to interfaces, whose methods are all pure virtual. In
|
||||
reality, sometimes you do need to mock a virtual method that is not pure (i.e,
|
||||
@ -815,9 +815,9 @@ or tell the mock object that you don't want to mock `Concrete()`:
|
||||
`MockFoo::Concrete()` will be called (and cause an infinite recursion) since
|
||||
`Foo::Concrete()` is virtual. That's just how C++ works.)
|
||||
|
||||
### Using Matchers
|
||||
## Using Matchers
|
||||
|
||||
#### Matching Argument Values Exactly
|
||||
### Matching Argument Values Exactly
|
||||
|
||||
You can specify exactly which arguments a mock method is expecting:
|
||||
|
||||
@ -829,7 +829,7 @@ using ::testing::Return;
|
||||
EXPECT_CALL(foo, DoThat("Hello", bar));
|
||||
```
|
||||
|
||||
#### Using Simple Matchers
|
||||
### Using Simple Matchers
|
||||
|
||||
You can use matchers to match arguments that have a certain property:
|
||||
|
||||
@ -850,7 +850,7 @@ A frequently used matcher is `_`, which matches anything:
|
||||
```
|
||||
<!-- GOOGLETEST_CM0022 DO NOT DELETE -->
|
||||
|
||||
#### Combining Matchers {#CombiningMatchers}
|
||||
### Combining Matchers {#CombiningMatchers}
|
||||
|
||||
You can build complex matchers from existing ones using `AllOf()`,
|
||||
`AllOfArray()`, `AnyOf()`, `AnyOfArray()` and `Not()`:
|
||||
@ -871,7 +871,7 @@ using ::testing::Not;
|
||||
NULL));
|
||||
```
|
||||
|
||||
#### Casting Matchers {#SafeMatcherCast}
|
||||
### Casting Matchers {#SafeMatcherCast}
|
||||
|
||||
gMock matchers are statically typed, meaning that the compiler can catch your
|
||||
mistake if you use a matcher of the wrong type (for example, if you use `Eq(5)`
|
||||
@ -926,7 +926,7 @@ can `static_cast` type `T` to type `U`.
|
||||
always safe as it could throw away information, for example), so be careful not
|
||||
to misuse/abuse it.
|
||||
|
||||
#### Selecting Between Overloaded Functions {#SelectOverload}
|
||||
### Selecting Between Overloaded Functions {#SelectOverload}
|
||||
|
||||
If you expect an overloaded function to be called, the compiler may need some
|
||||
help on which overloaded version it is.
|
||||
@ -983,7 +983,7 @@ TEST(PrinterTest, Print) {
|
||||
}
|
||||
```
|
||||
|
||||
#### Performing Different Actions Based on the Arguments
|
||||
### Performing Different Actions Based on the Arguments
|
||||
|
||||
When a mock method is called, the *last* matching expectation that's still
|
||||
active will be selected (think "newer overrides older"). So, you can make a
|
||||
@ -1005,7 +1005,7 @@ using ::testing::Return;
|
||||
Now, if `foo.DoThis()` is called with a value less than 5, `'a'` will be
|
||||
returned; otherwise `'b'` will be returned.
|
||||
|
||||
#### Matching Multiple Arguments as a Whole
|
||||
### Matching Multiple Arguments as a Whole
|
||||
|
||||
Sometimes it's not enough to match the arguments individually. For example, we
|
||||
may want to say that the first argument must be less than the second argument.
|
||||
@ -1057,7 +1057,7 @@ Note that if you want to pass the arguments to a predicate of your own (e.g.
|
||||
take a `::std::tuple` as its argument; gMock will pass the `n` selected
|
||||
arguments as *one* single tuple to the predicate.
|
||||
|
||||
#### Using Matchers as Predicates
|
||||
### Using Matchers as Predicates
|
||||
|
||||
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.
|
||||
@ -1095,7 +1095,7 @@ using testing::Ne;
|
||||
Matches(AllOf(Ge(0), Le(100), Ne(50)))
|
||||
```
|
||||
|
||||
#### Using Matchers in googletest Assertions
|
||||
### Using Matchers in googletest Assertions
|
||||
|
||||
Since matchers are basically predicates that also know how to describe
|
||||
themselves, there is a way to take advantage of them in googletest assertions.
|
||||
@ -1143,7 +1143,7 @@ Expected: starts with "Hello"
|
||||
**Credit:** The idea of `(ASSERT|EXPECT)_THAT` was borrowed from Joe Walnes'
|
||||
Hamcrest project, which adds `assertThat()` to JUnit.
|
||||
|
||||
#### Using Predicates as Matchers
|
||||
### Using Predicates as Matchers
|
||||
|
||||
gMock provides a [built-in set](#MatcherList) of matchers. In case you find them
|
||||
lacking, you can use an arbitrary unary predicate function or functor as a
|
||||
@ -1165,7 +1165,7 @@ works as long as the return value can be used as the condition in in statement
|
||||
|
||||
<!-- GOOGLETEST_CM0023 DO NOT DELETE -->
|
||||
|
||||
#### Matching Arguments that Are Not Copyable
|
||||
### Matching Arguments that Are Not Copyable
|
||||
|
||||
When you do an `EXPECT_CALL(mock_obj, Foo(bar))`, gMock saves away a copy of
|
||||
`bar`. When `Foo()` is called later, gMock compares the argument to `Foo()` with
|
||||
@ -1195,7 +1195,7 @@ using ::testing::Lt;
|
||||
Remember: if you do this, don't change `bar` after the `EXPECT_CALL()`, or the
|
||||
result is undefined.
|
||||
|
||||
#### Validating a Member of an Object
|
||||
### Validating a Member of an Object
|
||||
|
||||
Often a mock function takes a reference to object as an argument. When matching
|
||||
the argument, you may not want to compare the entire object against a fixed
|
||||
@ -1262,7 +1262,7 @@ Matcher<Foo> IsFoo(const Foo& foo) {
|
||||
}
|
||||
```
|
||||
|
||||
#### Validating the Value Pointed to by a Pointer Argument
|
||||
### Validating the Value Pointed to by a Pointer Argument
|
||||
|
||||
C++ functions often take pointers as arguments. You can use matchers like
|
||||
`IsNull()`, `NotNull()`, and other comparison matchers to match a pointer, but
|
||||
@ -1304,7 +1304,7 @@ What if you have a pointer to pointer? You guessed it - you can use nested
|
||||
`Pointee(Pointee(Lt(3)))` matches a pointer that points to a pointer that points
|
||||
to a number less than 3 (what a mouthful...).
|
||||
|
||||
#### Testing a Certain Property of an Object
|
||||
### Testing a Certain Property of an Object
|
||||
|
||||
Sometimes you want to specify that an object argument has a certain property,
|
||||
but there is no existing matcher that does this. If you want good error
|
||||
@ -1350,7 +1350,7 @@ Matcher<const Foo&> BarPlusBazEq(int expected_sum) {
|
||||
EXPECT_CALL(..., DoThis(BarPlusBazEq(5)))...;
|
||||
```
|
||||
|
||||
#### Matching Containers
|
||||
### Matching Containers
|
||||
|
||||
Sometimes an STL container (e.g. list, vector, map, ...) is passed to a mock
|
||||
function and you may want to validate it. Since most STL containers support the
|
||||
@ -1446,7 +1446,7 @@ using testing::Pair;
|
||||
with containers whose element order are undefined (e.g. `hash_map`) you
|
||||
should use `WhenSorted` around `ElementsAre`.
|
||||
|
||||
#### Sharing Matchers
|
||||
### Sharing Matchers
|
||||
|
||||
Under the hood, a gMock matcher object consists of a pointer to a ref-counted
|
||||
implementation object. Copying matchers is allowed and very efficient, as only
|
||||
@ -1467,7 +1467,7 @@ using ::testing::Matcher;
|
||||
... use in_range as a matcher in multiple EXPECT_CALLs ...
|
||||
```
|
||||
|
||||
#### Matchers must have no side-effects {#PureMatchers}
|
||||
### Matchers must have no side-effects {#PureMatchers}
|
||||
|
||||
WARNING: gMock does not guarantee when or how many times a matcher will be
|
||||
invoked. Therefore, all matchers must be *purely functional*: they cannot have
|
||||
@ -1479,9 +1479,9 @@ it is one of the standard matchers, or a custom matcher). In particular, a
|
||||
matcher can never call a mock function, as that will affect the state of the
|
||||
mock object and gMock.
|
||||
|
||||
### Setting Expectations
|
||||
## Setting Expectations
|
||||
|
||||
#### Knowing When to Expect {#UseOnCall}
|
||||
### Knowing When to Expect {#UseOnCall}
|
||||
|
||||
<!-- GOOGLETEST_CM0018 DO NOT DELETE -->
|
||||
|
||||
@ -1534,7 +1534,7 @@ message for specific methods by adding `EXPECT_CALL(...).Times(AnyNumber())`. DO
|
||||
NOT suppress it by blindly adding an `EXPECT_CALL(...)`, or you'll have a test
|
||||
that's a pain to maintain.
|
||||
|
||||
#### Ignoring Uninteresting Calls
|
||||
### Ignoring Uninteresting Calls
|
||||
|
||||
If you are not interested in how a mock method is called, just don't say
|
||||
anything about it. In this case, if the method is ever called, gMock will
|
||||
@ -1547,7 +1547,7 @@ Please note that once you expressed interest in a particular mock method (via
|
||||
function is called but the arguments don't match any `EXPECT_CALL()` statement,
|
||||
it will be an error.
|
||||
|
||||
#### Disallowing Unexpected Calls
|
||||
### Disallowing Unexpected Calls
|
||||
|
||||
If a mock method shouldn't be called at all, explicitly say so:
|
||||
|
||||
@ -1573,7 +1573,7 @@ using ::testing::Gt;
|
||||
A call to `foo.Bar()` that doesn't match any of the `EXPECT_CALL()` statements
|
||||
will be an error.
|
||||
|
||||
#### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected}
|
||||
### Understanding Uninteresting vs Unexpected Calls {#uninteresting-vs-unexpected}
|
||||
|
||||
*Uninteresting* calls and *unexpected* calls are different concepts in gMock.
|
||||
*Very* different.
|
||||
@ -1648,7 +1648,7 @@ Note that the order of the two `EXPECT_CALL`s is important, as a newer
|
||||
For more on uninteresting calls, nice mocks, and strict mocks, read
|
||||
["The Nice, the Strict, and the Naggy"](#NiceStrictNaggy).
|
||||
|
||||
#### Ignoring Uninteresting Arguments {#ParameterlessExpectations}
|
||||
### Ignoring Uninteresting Arguments {#ParameterlessExpectations}
|
||||
|
||||
If your test doesn't care about the parameters (it only cares about the number
|
||||
or order of calls), you can often simply omit the parameter list:
|
||||
@ -1674,7 +1674,7 @@ SaveArg actions to [save the values for later verification](#SaveArgVerify). If
|
||||
you do that, you can easily differentiate calling the method the wrong number of
|
||||
times from calling it with the wrong arguments.
|
||||
|
||||
#### Expecting Ordered Calls {#OrderedCalls}
|
||||
### Expecting Ordered Calls {#OrderedCalls}
|
||||
|
||||
Although an `EXPECT_CALL()` statement defined earlier takes precedence when
|
||||
gMock tries to match a function call with an expectation, by default calls don't
|
||||
@ -1705,7 +1705,7 @@ In this example, we expect a call to `foo.DoThis(5)`, followed by two calls to
|
||||
a call to `foo.DoThis(6)`. If a call occurred out-of-order, gMock will report an
|
||||
error.
|
||||
|
||||
#### Expecting Partially Ordered Calls {#PartialOrder}
|
||||
### Expecting Partially Ordered Calls {#PartialOrder}
|
||||
|
||||
Sometimes requiring everything to occur in a predetermined order can lead to
|
||||
brittle tests. For example, we may care about `A` occurring before both `B` and
|
||||
@ -1763,7 +1763,7 @@ specifies the following DAG (where `s1` is `A -> B`, and `s2` is `A -> C -> D`):
|
||||
This means that A must occur before B and C, and C must occur before D. There's
|
||||
no restriction about the order other than these.
|
||||
|
||||
#### Controlling When an Expectation Retires
|
||||
### Controlling When an Expectation Retires
|
||||
|
||||
When a mock method is called, gMock only considers expectations that are still
|
||||
active. An expectation is active when created, and becomes inactive (aka
|
||||
@ -1816,9 +1816,9 @@ Here #2 can be used only once, so if you have two warnings with the message
|
||||
`"File too large."`, the first will match #2 and the second will match #1 -
|
||||
there will be no error.
|
||||
|
||||
### Using Actions
|
||||
## Using Actions
|
||||
|
||||
#### Returning References from Mock Methods
|
||||
### Returning References from Mock Methods
|
||||
|
||||
If a mock function's return type is a reference, you need to use `ReturnRef()`
|
||||
instead of `Return()` to return a result:
|
||||
@ -1838,7 +1838,7 @@ class MockFoo : public Foo {
|
||||
...
|
||||
```
|
||||
|
||||
#### Returning Live Values from Mock Methods
|
||||
### Returning Live Values from Mock Methods
|
||||
|
||||
The `Return(x)` action saves a copy of `x` when the action is created, and
|
||||
always returns the same value whenever it's executed. Sometimes you may want to
|
||||
@ -1900,7 +1900,7 @@ using testing::ReturnPointee;
|
||||
EXPECT_EQ(42, foo.GetValue()); // This will succeed now.
|
||||
```
|
||||
|
||||
#### Combining Actions
|
||||
### Combining Actions
|
||||
|
||||
Want to do more than one thing when a function is called? That's fine. `DoAll()`
|
||||
allow you to do sequence of actions every time. Only the return value of the
|
||||
@ -1922,7 +1922,7 @@ class MockFoo : public Foo {
|
||||
action_n));
|
||||
```
|
||||
|
||||
#### Verifying Complex Arguments {#SaveArgVerify}
|
||||
### Verifying Complex Arguments {#SaveArgVerify}
|
||||
|
||||
If you want to verify that a method is called with a particular argument but the
|
||||
match criteria is complex, it can be difficult to distinguish between
|
||||
@ -1946,7 +1946,7 @@ You can instead save the arguments and test them individually:
|
||||
EXPECT_THAT(actual_proto, EqualsProto( ... ));
|
||||
```
|
||||
|
||||
#### Mocking Side Effects {#MockingSideEffects}
|
||||
### Mocking Side Effects {#MockingSideEffects}
|
||||
|
||||
Sometimes a method exhibits its effect not via returning a value but via side
|
||||
effects. For example, it may change some global state or modify an output
|
||||
@ -2045,7 +2045,7 @@ class MockRolodex : public Rolodex {
|
||||
.WillOnce(SetArrayArgument<0>(names.begin(), names.end()));
|
||||
```
|
||||
|
||||
#### Changing a Mock Object's Behavior Based on the State
|
||||
### Changing a Mock Object's Behavior Based on the State
|
||||
|
||||
If you expect a call to change the behavior of a mock object, you can use
|
||||
`::testing::InSequence` to specify different behaviors before and after the
|
||||
@ -2091,7 +2091,7 @@ ACTION_P(ReturnPointee, p) { return *p; }
|
||||
Here `my_mock.GetPrevValue()` will always return the argument of the last
|
||||
`UpdateValue()` call.
|
||||
|
||||
#### Setting the Default Value for a Return Type {#DefaultValue}
|
||||
### Setting the Default Value for a Return Type {#DefaultValue}
|
||||
|
||||
If a mock method's return type is a built-in C++ type or pointer, by default it
|
||||
will return 0 when invoked. Also, in C++ 11 and above, a mock method whose
|
||||
@ -2134,7 +2134,7 @@ to understand. We recommend you to use this feature judiciously. For example,
|
||||
you may want to make sure the `Set()` and `Clear()` calls are right next to the
|
||||
code that uses your mock.
|
||||
|
||||
#### Setting the Default Actions for a Mock Method
|
||||
### Setting the Default Actions for a Mock Method
|
||||
|
||||
You've learned how to change the default value of a given type. However, this
|
||||
may be too coarse for your purpose: perhaps you have two mock methods with the
|
||||
@ -2172,7 +2172,7 @@ Note that both `ON_CALL` and `EXPECT_CALL` have the same "later statements take
|
||||
precedence" rule, but they don't interact. That is, `EXPECT_CALL`s have their
|
||||
own precedence order distinct from the `ON_CALL` precedence order.
|
||||
|
||||
#### Using Functions/Methods/Functors/Lambdas as Actions {#FunctionsAsActions}
|
||||
### 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.
|
||||
@ -2236,7 +2236,7 @@ as long as it's safe to do so - nice, huh?
|
||||
... Invoke(implicit_cast<Closure*>(done)) ...; // The cast is necessary.
|
||||
```
|
||||
|
||||
#### Using Functions with Extra Info as Actions
|
||||
### Using Functions with Extra Info as Actions
|
||||
|
||||
The function or functor you call using `Invoke()` must have the same number of
|
||||
arguments as the mock function you use it for. Sometimes you may have a function
|
||||
@ -2266,7 +2266,7 @@ TEST_F(FooTest, Test) {
|
||||
}
|
||||
```
|
||||
|
||||
#### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments
|
||||
### Invoking a Function/Method/Functor/Lambda/Callback Without Arguments
|
||||
|
||||
`Invoke()` is very useful for doing actions that are more complex. It passes the
|
||||
mock function's arguments to the function, etc being invoked such that the
|
||||
@ -2322,7 +2322,7 @@ bool Job2(int n, char c) { ... }
|
||||
// The cast is necessary.
|
||||
```
|
||||
|
||||
#### Invoking an Argument of the Mock Function
|
||||
### Invoking an Argument of the Mock Function
|
||||
|
||||
Sometimes a mock function will receive a function pointer, a functor (in other
|
||||
words, a "callable") as an argument, e.g.
|
||||
@ -2421,7 +2421,7 @@ temporary value:
|
||||
// are kept inside the InvokeArgument action.
|
||||
```
|
||||
|
||||
#### Ignoring an Action's Result
|
||||
### Ignoring an Action's Result
|
||||
|
||||
Sometimes you have an action that returns *something*, but you need an action
|
||||
that returns `void` (perhaps you want to use it in a mock function that returns
|
||||
@ -2459,7 +2459,7 @@ class MockFoo : public Foo {
|
||||
Note that you **cannot** use `IgnoreResult()` on an action that already returns
|
||||
`void`. Doing so will lead to ugly compiler errors.
|
||||
|
||||
#### Selecting an Action's Arguments {#SelectingArgs}
|
||||
### Selecting an Action's Arguments {#SelectingArgs}
|
||||
|
||||
Say you have a mock function `Foo()` that takes seven arguments, and you have a
|
||||
custom action that you want to invoke when `Foo()` is called. Trouble is, the
|
||||
@ -2543,7 +2543,7 @@ Here are more tips:
|
||||
if the 4-th argument of the mock function is an `int` and `my_action` takes
|
||||
a `double`, `WithArg<4>(my_action)` will work.
|
||||
|
||||
#### Ignoring Arguments in Action Functions
|
||||
### Ignoring Arguments in Action Functions
|
||||
|
||||
The [selecting-an-action's-arguments](#SelectingArgs) recipe showed us one way
|
||||
to make a mock function and an action with incompatible argument lists fit
|
||||
@ -2600,7 +2600,7 @@ double DistanceToOrigin(Unused, double x, double y) {
|
||||
.WillOnce(Invoke(DistanceToOrigin));
|
||||
```
|
||||
|
||||
#### Sharing Actions
|
||||
### Sharing Actions
|
||||
|
||||
Just like matchers, a gMock action object consists of a pointer to a ref-counted
|
||||
implementation object. Therefore copying actions is also allowed and very
|
||||
@ -2656,7 +2656,7 @@ using ::testing::Action;
|
||||
foo.DoThat(); // Returns 3 - the counter is shared.
|
||||
```
|
||||
|
||||
#### Testing Asynchronous Behavior
|
||||
### Testing Asynchronous Behavior
|
||||
|
||||
One oft-encountered problem with gMock is that it can be hard to test
|
||||
asynchronous behavior. Suppose you had a `EventQueue` class that you wanted to
|
||||
@ -2705,9 +2705,9 @@ our test will run forever. It will eventually time-out and fail, but it will
|
||||
take longer and be slightly harder to debug. To alleviate this problem, you can
|
||||
use `WaitForNotificationWithTimeout(ms)` instead of `WaitForNotification()`.
|
||||
|
||||
### Misc Recipes on Using gMock
|
||||
## Misc Recipes on Using gMock
|
||||
|
||||
#### Mocking Methods That Use Move-Only Types
|
||||
### Mocking Methods That Use Move-Only Types
|
||||
|
||||
C++11 introduced *move-only types*. A move-only-typed value can be moved from
|
||||
one object to another, but cannot be copied. `std::unique_ptr<T>` is probably
|
||||
@ -2847,7 +2847,7 @@ implemented yet. If this is blocking you, please file a bug.
|
||||
A few actions (e.g. `DoAll`) copy their arguments internally, so they can never
|
||||
work with non-copyable objects; you'll have to use functors instead.
|
||||
|
||||
##### Legacy workarounds for move-only types {#LegacyMoveOnly}
|
||||
#### Legacy workarounds for move-only types {#LegacyMoveOnly}
|
||||
|
||||
Support for move-only function arguments was only introduced to gMock in April
|
||||
2017. In older code, you may encounter the following workaround for the lack of
|
||||
@ -2879,7 +2879,7 @@ method:
|
||||
mock_buzzer_.ShareBuzz(MakeUnique<Buzz>(AccessLevel::kInternal), 0);
|
||||
```
|
||||
|
||||
#### Making the Compilation Faster
|
||||
### Making the Compilation Faster
|
||||
|
||||
Believe it or not, the *vast majority* of the time spent on compiling a mock
|
||||
class is in generating its constructor and destructor, as they perform
|
||||
@ -2943,7 +2943,7 @@ MockFoo::MockFoo() {}
|
||||
MockFoo::~MockFoo() {}
|
||||
```
|
||||
|
||||
#### Forcing a Verification
|
||||
### Forcing a Verification
|
||||
|
||||
When it's being destroyed, your friendly mock object will automatically verify
|
||||
that all expectations on it have been satisfied, and will generate googletest
|
||||
@ -2984,7 +2984,7 @@ indicate whether the verification was successful (`true` for yes), so you can
|
||||
wrap that function call inside a `ASSERT_TRUE()` if there is no point going
|
||||
further when the verification has failed.
|
||||
|
||||
#### Using Check Points {#UsingCheckPoints}
|
||||
### Using Check Points {#UsingCheckPoints}
|
||||
|
||||
Sometimes you may want to "reset" a mock object at various check points in your
|
||||
test: at each check point, you verify that all existing expectations on the mock
|
||||
@ -3048,7 +3048,7 @@ point "1", the second `Bar("a")` must happen after check point "2", and nothing
|
||||
should happen between the two check points. The explicit check points make it
|
||||
easy to tell which `Bar("a")` is called by which call to `Foo()`.
|
||||
|
||||
#### Mocking Destructors
|
||||
### Mocking Destructors
|
||||
|
||||
Sometimes you want to make sure a mock object is destructed at the right time,
|
||||
e.g. after `bar->A()` is called but before `bar->B()` is called. We already know
|
||||
@ -3096,7 +3096,7 @@ testing when its `Die()` method is called:
|
||||
|
||||
And that's that.
|
||||
|
||||
#### Using gMock and Threads {#UsingThreads}
|
||||
### Using gMock and Threads {#UsingThreads}
|
||||
|
||||
In a **unit** test, it's best if you could isolate and test a piece of code in a
|
||||
single-threaded context. That avoids race conditions and dead locks, and makes
|
||||
@ -3154,7 +3154,7 @@ Also, remember that `DefaultValue<T>` is a global resource that potentially
|
||||
affects *all* living mock objects in your program. Naturally, you won't want to
|
||||
mess with it from multiple threads or when there still are mocks in action.
|
||||
|
||||
#### Controlling How Much Information gMock Prints
|
||||
### Controlling How Much Information gMock Prints
|
||||
|
||||
When gMock sees something that has the potential of being an error (e.g. a mock
|
||||
function with no expectation is called, a.k.a. an uninteresting call, which is
|
||||
@ -3193,7 +3193,7 @@ warning messages, remember that you can control their amount with the
|
||||
|
||||
Now, judiciously use the right flag to enable gMock serve you better!
|
||||
|
||||
#### Gaining Super Vision into Mock Calls
|
||||
### Gaining Super Vision into Mock Calls
|
||||
|
||||
You have a test using gMock. It fails: gMock tells you some expectations aren't
|
||||
satisfied. However, you aren't sure why: Is there a typo somewhere in the
|
||||
@ -3273,7 +3273,7 @@ command line.
|
||||
|
||||
<!-- GOOGLETEST_CM0025 DO NOT DELETE -->
|
||||
|
||||
#### Running Tests in Emacs
|
||||
### Running Tests in Emacs
|
||||
|
||||
If you build and run your tests in Emacs using the `M-x google-compile` command
|
||||
(as many googletest users do), the source file locations of gMock and googletest
|
||||
@ -3293,9 +3293,9 @@ Then you can type `M-m` to start a build (if you want to run the test as well,
|
||||
just make sure `foo_test.run` or `runtests` is in the build command you supply
|
||||
after typing `M-m`), or `M-up`/`M-down` to move back and forth between errors.
|
||||
|
||||
### Extending gMock
|
||||
## Extending gMock
|
||||
|
||||
#### Writing New Matchers Quickly {#NewMatchers}
|
||||
### Writing New Matchers Quickly {#NewMatchers}
|
||||
|
||||
WARNING: gMock does not guarantee when or how many times a matcher will be
|
||||
invoked. Therefore, all matchers must be functionally pure. See
|
||||
@ -3409,7 +3409,7 @@ any type where the value of `(arg % 7) == 0` can be implicitly converted to a
|
||||
`int`, `arg_type` will be `int`; if it takes an `unsigned long`, `arg_type` will
|
||||
be `unsigned long`; and so on.
|
||||
|
||||
#### Writing New Parameterized Matchers Quickly
|
||||
### Writing New Parameterized Matchers Quickly
|
||||
|
||||
Sometimes you'll want to define a matcher that has parameters. For that you can
|
||||
use the macro:
|
||||
@ -3546,7 +3546,7 @@ matcher parameters, which in general leads to better compiler error messages
|
||||
that pay off in the long run. They also allow overloading matchers based on
|
||||
parameter types (as opposed to just based on the number of parameters).
|
||||
|
||||
#### Writing New Monomorphic Matchers
|
||||
### Writing New Monomorphic Matchers
|
||||
|
||||
A matcher of argument type `T` implements `::testing::MatcherInterface<T>` and
|
||||
does two things: it tests whether a value of type `T` matches the matcher, and
|
||||
@ -3652,7 +3652,7 @@ Expected: is divisible by 7
|
||||
Actual: 23 (the remainder is 2)
|
||||
```
|
||||
|
||||
#### Writing New Polymorphic Matchers
|
||||
### Writing New Polymorphic Matchers
|
||||
|
||||
You've learned how to write your own matchers in the previous recipe. Just one
|
||||
problem: a matcher created using `MakeMatcher()` only works for one particular
|
||||
@ -3712,7 +3712,7 @@ virtual.
|
||||
Like in a monomorphic matcher, you may explain the match result by streaming
|
||||
additional information to the `listener` argument in `MatchAndExplain()`.
|
||||
|
||||
#### Writing New Cardinalities
|
||||
### Writing New Cardinalities
|
||||
|
||||
A cardinality is used in `Times()` to tell gMock how many times you expect a
|
||||
call to occur. It doesn't have to be exact. For example, you can say
|
||||
@ -3771,7 +3771,7 @@ Cardinality EvenNumber() {
|
||||
.Times(EvenNumber());
|
||||
```
|
||||
|
||||
#### Writing New Actions Quickly {#QuickNewActions}
|
||||
### Writing New Actions Quickly {#QuickNewActions}
|
||||
|
||||
If the built-in actions don't work for you, you can easily define your own one.
|
||||
Just define a functor class with a (possibly templated) call operator, matching
|
||||
@ -3800,7 +3800,7 @@ struct MultiplyBy {
|
||||
// EXPECT_CALL(...).WillOnce(MultiplyBy{7});
|
||||
```
|
||||
|
||||
##### Legacy macro-based Actions
|
||||
#### Legacy macro-based Actions
|
||||
|
||||
Before C++11, the functor-based actions were not supported; the old way of
|
||||
writing actions was through a set of `ACTION*` macros. We suggest to avoid them
|
||||
@ -3879,7 +3879,7 @@ Pre-defined Symbol | Is Bound To
|
||||
`return_type` | the type `int`
|
||||
`function_type` | the type `int(bool, int*)`
|
||||
|
||||
##### Legacy macro-based parameterized Actions
|
||||
#### Legacy macro-based parameterized Actions
|
||||
|
||||
Sometimes you'll want to parameterize an action you define. For that we have
|
||||
another macro
|
||||
@ -3938,7 +3938,7 @@ ACTION_P(Plus, a) { ... }
|
||||
ACTION_P2(Plus, a, b) { ... }
|
||||
```
|
||||
|
||||
#### Restricting the Type of an Argument or Parameter in an ACTION
|
||||
### Restricting the Type of an Argument or Parameter in an ACTION
|
||||
|
||||
For maximum brevity and reusability, the `ACTION*` macros don't ask you to
|
||||
provide the types of the mock function arguments and the action parameters.
|
||||
@ -3966,7 +3966,7 @@ ACTION_P(Bar, param) {
|
||||
where `StaticAssertTypeEq` is a compile-time assertion in googletest that
|
||||
verifies two types are the same.
|
||||
|
||||
#### Writing New Action Templates Quickly
|
||||
### Writing New Action Templates Quickly
|
||||
|
||||
Sometimes you want to give an action explicit template parameters that cannot be
|
||||
inferred from its value parameters. `ACTION_TEMPLATE()` supports that and can be
|
||||
@ -4036,7 +4036,7 @@ Are we using a single-template-parameter action where `bool` refers to the type
|
||||
of `x`, or a two-template-parameter action where the compiler is asked to infer
|
||||
the type of `x`?
|
||||
|
||||
#### Using the ACTION Object's Type
|
||||
### Using the ACTION Object's Type
|
||||
|
||||
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
|
||||
@ -4063,7 +4063,7 @@ Note that we have to pick different suffixes (`Action`, `ActionP`, `ActionP2`,
|
||||
and etc) for actions with different numbers of value parameters, or the action
|
||||
definitions cannot be overloaded on the number of them.
|
||||
|
||||
#### Writing New Monomorphic Actions {#NewMonoActions}
|
||||
### Writing New Monomorphic Actions {#NewMonoActions}
|
||||
|
||||
While the `ACTION*` macros are very convenient, sometimes they are
|
||||
inappropriate. For example, despite the tricks shown in the previous recipes,
|
||||
@ -4120,7 +4120,7 @@ Action<IncrementMethod> IncrementArgument() {
|
||||
foo.Baz(&n); // Should return 5 and change n to 6.
|
||||
```
|
||||
|
||||
#### Writing New Polymorphic Actions {#NewPolyActions}
|
||||
### Writing New Polymorphic Actions {#NewPolyActions}
|
||||
|
||||
The previous recipe showed you how to define your own action. This is all good,
|
||||
except that you need to know the type of the function in which the action will
|
||||
@ -4196,7 +4196,7 @@ class MockFoo : public Foo {
|
||||
foo.DoThat(1, "Hi", "Bye"); // Will return "Hi".
|
||||
```
|
||||
|
||||
#### Teaching gMock How to Print Your Values
|
||||
### Teaching gMock How to Print Your Values
|
||||
|
||||
When an uninteresting or unexpected call occurs, gMock prints the argument
|
||||
values and the stack trace to help you debug. Assertion macros like
|
||||
@ -4211,12 +4211,12 @@ prints the raw bytes in the value and hopes that you the user can figure it out.
|
||||
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
|
||||
## Useful Mocks Created Using gMock
|
||||
|
||||
<!--#include file="includes/g3_testing_LOGs.md"-->
|
||||
<!--#include file="includes/g3_mock_callbacks.md"-->
|
||||
|
||||
#### Mock std::function {#MockFunction}
|
||||
### 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,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user