diff options
author | Abseil Team <absl-team@google.com> | 2021-06-02 00:16:21 (GMT) |
---|---|---|
committer | Andy Soffer <asoffer@google.com> | 2021-06-02 21:55:01 (GMT) |
commit | 5f6a14c846aaebc6000c5d844088f8c37c996441 (patch) | |
tree | 73744abe764b12749bbaf79ecd82fc485b479140 /docs/gmock_cheat_sheet.md | |
parent | 2bd34816661a29b7cf8c21bd86210408ed658edb (diff) | |
download | googletest-5f6a14c846aaebc6000c5d844088f8c37c996441.zip googletest-5f6a14c846aaebc6000c5d844088f8c37c996441.tar.gz googletest-5f6a14c846aaebc6000c5d844088f8c37c996441.tar.bz2 |
Googletest export
Create new Mocking Reference
PiperOrigin-RevId: 376951575
Diffstat (limited to 'docs/gmock_cheat_sheet.md')
-rw-r--r-- | docs/gmock_cheat_sheet.md | 167 |
1 files changed, 15 insertions, 152 deletions
diff --git a/docs/gmock_cheat_sheet.md b/docs/gmock_cheat_sheet.md index 2545c61..17ed7a5 100644 --- a/docs/gmock_cheat_sheet.md +++ b/docs/gmock_cheat_sheet.md @@ -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 |