SERVER-50157 Add usage notes for MockNetwork::InSequence

1 files changed, 63 insertions, 3 deletions

diff --git a/src/mongo/executor/mock_network_fixture.h b/src/mongo/executor/mock_network_fixture.h
index 91c08207898..e98cace0ca7 100644
--- a/src/mongo/executor/mock_network_fixture.h
+++ b/src/mongo/executor/mock_network_fixture.h
@@ -42,9 +42,69 @@ using executor::RemoteCommandResponse;
 namespace test {
 namespace mock {
 
-// MockNetwork wraps the NetworkInterfaceMock to provide a declarative approach
-// to specify expected behaviors on the network and to hide the interaction with
-// the NetworkInterfaceMock.
+/**
+ * MockNetwork wraps the NetworkInterfaceMock to provide a declarative approach to specify
+ * expected behaviors on the network and to hide the interaction with NetworkInterfaceMock.
+ * We refer to the behaviors we are testing as "expectations".
+ *
+ * Expectations:
+ * All expectations are unordered by default, unless otherwise specified (see Sequences below).
+ * There are two types of expectations: default expectations and user expectations.
+ * The purpose of default expectations is to cover uninteresting calls that are typically
+ * repeated throughout a set of tests, so that individual tests can focus on the specific
+ * behaviors they are meant to evaluate. Default expectations may be matched any number of times
+ * (including zero).
+ * User expectations represent the concrete requirements of a test. They must all be matched
+ * the exact number of times required. For example:
+ *
+ *      // Earlier in the test fixture
+ *      mock.defaultExpect(...); // A
+ *      mock.defaultExpect(...); // B
+ *
+ *      ...
+ *
+ *      // In individual tests
+ *      mock.expect(...).times(...); // C
+ *      mock.expect(...).times(...); // D
+ *
+ *      ...
+ *
+ *      // Later in those tests
+ *      mock.runUntilExpectationsSatisfied();
+ *
+ * We have no requirements here on matching A or B, but C and D must be satisfied in full.
+ * You may omit the times() call if you would like to use the default of 1 "times".
+ *
+ * To run expectations, use runUntilExpectationsSatisfied(), which will block until all
+ * expectations have been fully satisfied. You may also use runUntil() if you only want to
+ * advance to a particular time. If you would like to still check that your expectations have
+ * been satisfied (or explicitly demonstrate that they haven't), call verifyExpectations().
+ *
+ * Sequences:
+ * The Sequence class provides a way to specify order of expectations. A test may have all
+ * expectations in a sequence, or a subset, or none at all. It may also include any number of
+ * sequences. Note that sequences only specify partial ordering, which means it is acceptable to
+ * interleave other expectations in between sequence members (including expectations belonging to
+ * other sequences) so long as all sequences are run in their required order. We enforce ordering
+ * by refusing to match an expectation if it has unsatisfied prerequisites.
+ *
+ * To specify a sequence, use the InSequence RAII type, which will add all Expectations in its
+ * scope to an anonymous sequence. For example:
+ *
+ *
+ *      {
+ *          MockNetwork::InSequence seq(mock);
+ *
+ *          mock.expect(...); // A
+ *          mock.expect(...); // B
+ *      }
+ *
+ *      mock.expect(...); // C
+ *
+ *
+ * In this example, we only require that A comes before B. We have no requirements for when C
+ * is executed. Therefore, all of {ABC, ACB, CAB} are valid, but {BAC, BCA, CBA} are not valid.
+ */
 class MockNetwork {
 public:
     using MatcherFunc = std::function<bool(const BSONObj&)>;