Googletest export

Create new Mocking Reference

PiperOrigin-RevId: 376951575

docs/_data/navigation.yml

@@ -21,6 +21,8 @@ nav:
     url: "/gmock_cheat_sheet.html"
 - section: "References"
   items:
+  - title: "Mocking Reference"
+    url: "/reference/mocking.html"
   - title: "Assertions"
     url: "/reference/assertions.html"
   - title: "Matchers"

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
 

docs/gmock_cook_book.md

@@ -1711,7 +1711,7 @@ the test should reflect our real intent, instead of being overly constraining.
 
 gMock allows you to impose an arbitrary DAG (directed acyclic graph) on the
 calls. One way to express the DAG is to use the
-[After](gmock_cheat_sheet.md#AfterClause) clause of `EXPECT_CALL`.
+[`After` clause](reference/mocking.md#EXPECT_CALL.After) of `EXPECT_CALL`.
 
 Another way is via the `InSequence()` clause (not the same as the `InSequence`
 class), which we borrowed from jMock 2. It's less flexible than `After()`, but