Googletest export
Create new Mocking Reference PiperOrigin-RevId: 376951575
This commit is contained in:
Abseil Team
@@ -133,22 +133,8 @@ gMock has a **built-in default action** for any function that returns `void`,
|
||||
`bool`, a numeric value, or a pointer. In C++11, it will additionally returns
|
||||
the default-constructed value, if one exists for the given type.
|
||||
|
||||
To customize the default action for functions with return type *`T`*:
|
||||
|
||||
```cpp
|
||||
using ::testing::DefaultValue;
|
||||
|
||||
// Sets the default value to be returned. T must be CopyConstructible.
|
||||
DefaultValue<T>::Set(value);
|
||||
// Sets a factory. Will be invoked on demand. T must be MoveConstructible.
|
||||
// T MakeT();
|
||||
DefaultValue<T>::SetFactory(&MakeT);
|
||||
// ... use the mocks ...
|
||||
// Resets the default value.
|
||||
DefaultValue<T>::Clear();
|
||||
```
|
||||
|
||||
Example usage:
|
||||
To customize the default action for functions with return type `T`, use
|
||||
[`DefaultValue<T>`](reference/mocking.md#DefaultValue). For example:
|
||||
|
||||
```cpp
|
||||
// Sets the default action for return type std::unique_ptr<Buzz> to
|
||||
@@ -172,55 +158,15 @@ Example usage:
|
||||
```
|
||||
|
||||
To customize the default action for a particular method of a specific mock
|
||||
object, use `ON_CALL()`. `ON_CALL()` has a similar syntax to `EXPECT_CALL()`,
|
||||
but it is used for setting default behaviors (when you do not require that the
|
||||
mock method is called). See [here](gmock_cook_book.md#UseOnCall) for a more
|
||||
detailed discussion.
|
||||
|
||||
```cpp
|
||||
ON_CALL(mock-object, method(matchers))
|
||||
.With(multi-argument-matcher) ?
|
||||
.WillByDefault(action);
|
||||
```
|
||||
object, use [`ON_CALL`](reference/mocking.md#ON_CALL). `ON_CALL` has a similar
|
||||
syntax to `EXPECT_CALL`, but it is used for setting default behaviors when you
|
||||
do not require that the mock method is called. See
|
||||
[Knowing When to Expect](gmock_cook_book.md#UseOnCall) for a more detailed
|
||||
discussion.
|
||||
|
||||
## Setting Expectations {#ExpectCall}
|
||||
|
||||
`EXPECT_CALL()` sets **expectations** on a mock method (How will it be called?
|
||||
What will it do?):
|
||||
|
||||
```cpp
|
||||
EXPECT_CALL(mock-object, method (matchers)?)
|
||||
.With(multi-argument-matcher) ?
|
||||
.Times(cardinality) ?
|
||||
.InSequence(sequences) *
|
||||
.After(expectations) *
|
||||
.WillOnce(action) *
|
||||
.WillRepeatedly(action) ?
|
||||
.RetiresOnSaturation(); ?
|
||||
```
|
||||
|
||||
For each item above, `?` means it can be used at most once, while `*` means it
|
||||
can be used any number of times.
|
||||
|
||||
In order to pass, `EXPECT_CALL` must be used before the calls are actually made.
|
||||
|
||||
The `(matchers)` is a comma-separated list of matchers that correspond to each
|
||||
of the arguments of `method`, and sets the expectation only for calls of
|
||||
`method` that matches all of the matchers.
|
||||
|
||||
If `(matchers)` is omitted, the expectation is the same as if the matchers were
|
||||
set to anything matchers (for example, `(_, _, _, _)` for a four-arg method).
|
||||
|
||||
If `Times()` is omitted, the cardinality is assumed to be:
|
||||
|
||||
* `Times(1)` when there is neither `WillOnce()` nor `WillRepeatedly()`;
|
||||
* `Times(n)` when there are `n` `WillOnce()`s but no `WillRepeatedly()`, where
|
||||
`n` >= 1; or
|
||||
* `Times(AtLeast(n))` when there are `n` `WillOnce()`s and a
|
||||
`WillRepeatedly()`, where `n` >= 0.
|
||||
|
||||
A method with no `EXPECT_CALL()` is free to be invoked *any number of times*,
|
||||
and the default action will be taken each time.
|
||||
See [`EXPECT_CALL`](reference/mocking.md#EXPECT_CALL) in the Mocking Reference.
|
||||
|
||||
## Matchers {#MatcherList}
|
||||
|
||||
@@ -232,99 +178,16 @@ See the [Actions Reference](reference/actions.md).
|
||||
|
||||
## Cardinalities {#CardinalityList}
|
||||
|
||||
These are used in `Times()` to specify how many times a mock function will be
|
||||
called:
|
||||
|
||||
| | |
|
||||
| :---------------- | :----------------------------------------------------- |
|
||||
| `AnyNumber()` | The function can be called any number of times. |
|
||||
| `AtLeast(n)` | The call is expected at least `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. |
|
||||
| `Exactly(n) or n` | The call is expected exactly `n` times. In particular, the call should never happen when `n` is 0. |
|
||||
See the [`Times` clause](reference/mocking.md#EXPECT_CALL.Times) of
|
||||
`EXPECT_CALL` in the Mocking Reference.
|
||||
|
||||
## Expectation Order
|
||||
|
||||
By default, the expectations can be matched in *any* order. If some or all
|
||||
expectations must be matched in a given order, there are two ways to specify it.
|
||||
They can be used either independently or together.
|
||||
|
||||
### The After Clause {#AfterClause}
|
||||
|
||||
```cpp
|
||||
using ::testing::Expectation;
|
||||
...
|
||||
Expectation init_x = EXPECT_CALL(foo, InitX());
|
||||
Expectation init_y = EXPECT_CALL(foo, InitY());
|
||||
EXPECT_CALL(foo, Bar())
|
||||
.After(init_x, init_y);
|
||||
```
|
||||
|
||||
says that `Bar()` can be called only after both `InitX()` and `InitY()` have
|
||||
been called.
|
||||
|
||||
If you don't know how many pre-requisites an expectation has when you write it,
|
||||
you can use an `ExpectationSet` to collect them:
|
||||
|
||||
```cpp
|
||||
using ::testing::ExpectationSet;
|
||||
...
|
||||
ExpectationSet all_inits;
|
||||
for (int i = 0; i < element_count; i++) {
|
||||
all_inits += EXPECT_CALL(foo, InitElement(i));
|
||||
}
|
||||
EXPECT_CALL(foo, Bar())
|
||||
.After(all_inits);
|
||||
```
|
||||
|
||||
says that `Bar()` can be called only after all elements have been initialized
|
||||
(but we don't care about which elements get initialized before the others).
|
||||
|
||||
Modifying an `ExpectationSet` after using it in an `.After()` doesn't affect the
|
||||
meaning of the `.After()`.
|
||||
|
||||
### Sequences {#UsingSequences}
|
||||
|
||||
When you have a long chain of sequential expectations, it's easier to specify
|
||||
the order using **sequences**, which don't require you to give each expectation
|
||||
in the chain a different name. *All expected calls* in the same sequence must
|
||||
occur in the order they are specified.
|
||||
|
||||
```cpp
|
||||
using ::testing::Return;
|
||||
using ::testing::Sequence;
|
||||
Sequence s1, s2;
|
||||
...
|
||||
EXPECT_CALL(foo, Reset())
|
||||
.InSequence(s1, s2)
|
||||
.WillOnce(Return(true));
|
||||
EXPECT_CALL(foo, GetSize())
|
||||
.InSequence(s1)
|
||||
.WillOnce(Return(1));
|
||||
EXPECT_CALL(foo, Describe(A<const char*>()))
|
||||
.InSequence(s2)
|
||||
.WillOnce(Return("dummy"));
|
||||
```
|
||||
|
||||
says that `Reset()` must be called before *both* `GetSize()` *and* `Describe()`,
|
||||
and the latter two can occur in any order.
|
||||
|
||||
To put many expectations in a sequence conveniently:
|
||||
|
||||
```cpp
|
||||
using ::testing::InSequence;
|
||||
{
|
||||
InSequence seq;
|
||||
|
||||
EXPECT_CALL(...)...;
|
||||
EXPECT_CALL(...)...;
|
||||
...
|
||||
EXPECT_CALL(...)...;
|
||||
}
|
||||
```
|
||||
|
||||
says that all expected calls in the scope of `seq` must occur in strict order.
|
||||
The name `seq` is irrelevant.
|
||||
By default, expectations can be matched in *any* order. If some or all
|
||||
expectations must be matched in a given order, you can use the
|
||||
[`After` clause](reference/mocking.md#EXPECT_CALL.After) or
|
||||
[`InSequence` clause](reference/mocking.md#EXPECT_CALL.InSequence) of
|
||||
`EXPECT_CALL`, or use an [`InSequence` object](reference/mocking.md#InSequence).
|
||||
|
||||
## Verifying and Resetting a Mock
|
||||
|
||||
|
||||
Reference in New Issue
Block a user