Skip to content

Commit 10c7e2e

Browse files
blink1073blink1073
committed
DRIVERS-2789 Convert Connections Survive Primary Step Down Spec to Markdown
1 parent c07aead commit 10c7e2e

File tree

2 files changed

+281
-126
lines changed

2 files changed

+281
-126
lines changed

‎source/connections-survive-step-down/tests/README.md

Lines changed: 103 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -1,178 +1,155 @@
1-
===========================================
2-
Connections Survive Primary Step Down Tests
3-
===========================================
1+
# Connections Survive Primary Step Down Tests
42

5-
These tests can be used to verify a driver's compliance with server discovery
6-
and monitoring requirements with respect to handling "not primary" and
7-
"node is shutting down" error responses from the server.
8-
9-
.. contents::
3+
These tests can be used to verify a driver's compliance with server discovery and monitoring requirements with respect
4+
to handling "not primary" and "node is shutting down" error responses from the server.
105

116
These tests apply only to replica set topologies.
127

13-
Server Fail Point
14-
-----------------
15-
16-
See: `Server Fail Point`_ in the Transactions spec test suite.
17-
18-
.. _Server Fail Point: ../../transactions/tests#server-fail-point
19-
20-
Disabling Fail Point after Test Execution
21-
`````````````````````````````````````````
8+
## Server Fail Point
229

23-
After each test that configures a fail point, drivers should disable the
24-
``failCommand`` fail point to avoid spurious failures in
25-
subsequent tests. The fail point may be disabled like so::
10+
See: [Server Fail Point](../../transactions/tests#server-fail-point) in the Transactions spec test suite.
2611

27-
db.runCommand({
28-
configureFailPoint: "failCommand",
29-
mode: "off"
30-
});
12+
### Disabling Fail Point after Test Execution
3113

32-
Consideration when using serverStatus
33-
`````````````````````````````````````
14+
After each test that configures a fail point, drivers should disable the `failCommand` fail point to avoid spurious
15+
failures in subsequent tests. The fail point may be disabled like so:
3416

35-
Drivers executing `serverStatus`_ for connection assertions MUST take its own
36-
connection into account when making their calculations. Those drivers SHOULD
37-
execute `serverStatus`_ using a separate client not under test.
17+
```javascript
18+
db.runCommand({
19+
configureFailPoint: "failCommand",
20+
mode: "off"
21+
});
22+
```
3823

24+
### Consideration when using serverStatus
3925

40-
Tests
41-
-----
26+
Drivers executing [serverStatus](https://www.mongodb.com/docs/manual/reference/command/serverStatus) for connection
27+
assertions MUST take its own connection into account when making their calculations. Those drivers SHOULD execute
28+
[serverStatus](https://www.mongodb.com/docs/manual/reference/command/serverStatus) using a separate client not under
29+
test.
4230

31+
## Tests
4332

44-
Test setup
45-
``````````
33+
### Test setup
4634

4735
For each test, make sure the following steps have been completed before running the actual test:
4836

49-
- Create a ``MongoClient`` with ``retryWrites=false``
50-
- Create a collection object from the ``MongoClient``, using ``step-down`` for the database and collection name.
51-
- Drop the test collection, using ``writeConcern`` "majority".
52-
- Execute the "create" command to recreate the collection, using ``writeConcern``
53-
"majority".
37+
- Create a `MongoClient` with `retryWrites=false`
38+
- Create a collection object from the `MongoClient`, using `step-down` for the database and collection name.
39+
- Drop the test collection, using `writeConcern` "majority".
40+
- Execute the "create" command to recreate the collection, using `writeConcern` "majority".
5441

5542
The driver should implement the following tests:
5643

57-
getMore Iteration
58-
`````````````````
44+
### getMore Iteration
5945

6046
This test requires a replica set with server version 4.2 or higher.
6147

6248
Perform the following operations:
6349

6450
- Insert 5 documents into a collection with a majority write concern.
65-
- Start a find operation on the collection with a batch size of 2, and
66-
retrieve the first batch of results.
67-
- Send a ``{replSetFreeze: 0}`` command to any secondary and verify that the
68-
command succeeded. This command will unfreeze the secondary and ensure that
69-
it will be eligible to be elected immediately.
70-
- Send a ``{replSetStepDown: 30, force: true}`` command to the current primary and verify that
71-
the command succeeded.
72-
- Retrieve the next batch of results from the cursor obtained in the find
73-
operation, and verify that this operation succeeded.
74-
- If the driver implements the `CMAP`_ specification, verify that no new `PoolClearedEvent`_ has been
75-
published. Otherwise verify that `connections.totalCreated`_ in `serverStatus`_ has not changed.
76-
77-
78-
Not Primary - Keep Connection Pool
79-
``````````````````````````````````
51+
- Start a find operation on the collection with a batch size of 2, and retrieve the first batch of results.
52+
- Send a `{replSetFreeze: 0}` command to any secondary and verify that the command succeeded. This command will unfreeze
53+
the secondary and ensure that it will be eligible to be elected immediately.
54+
- Send a `{replSetStepDown: 30, force: true}` command to the current primary and verify that the command succeeded.
55+
- Retrieve the next batch of results from the cursor obtained in the find operation, and verify that this operation
56+
succeeded.
57+
- If the driver implements the [CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md)
58+
specification, verify that no new
59+
[PoolClearedEvent](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events) has been
60+
published. Otherwise verify that
61+
[connections.totalCreated](https://www.mongodb.com/docs/manual/reference/command/serverStatus/#serverstatus.connections.totalCreated)
62+
in [serverStatus](https://www.mongodb.com/docs/manual/reference/command/serverStatus) has not changed.
63+
64+
### Not Primary - Keep Connection Pool
8065

8166
This test requires a replica set with server version 4.2 or higher.
8267

83-
- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1},
84-
data: {failCommands: ["insert"], errorCode: 10107}}``
85-
- Execute an insert into the test collection of a ``{test: 1}``
86-
document.
68+
- Set the following fail point:
69+
`{configureFailPoint: "failCommand", mode: {times: 1}, data: {failCommands: ["insert"], errorCode: 10107}}`
70+
- Execute an insert into the test collection of a `{test: 1}` document.
8771
- Verify that the insert failed with an operation failure with 10107 code.
88-
- Execute an insert into the test collection of a ``{test: 1}``
89-
document and verify that it succeeds.
90-
- If the driver implements the `CMAP`_ specification, verify that no new `PoolClearedEvent`_ has been
91-
published. Otherwise verify that `connections.totalCreated`_ in `serverStatus`_ has not changed.
72+
- Execute an insert into the test collection of a `{test: 1}` document and verify that it succeeds.
73+
- If the driver implements the [CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md)
74+
specification, verify that no new
75+
[PoolClearedEvent](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events) has been
76+
published. Otherwise verify that
77+
[connections.totalCreated](https://www.mongodb.com/docs/manual/reference/command/serverStatus/#serverstatus.connections.totalCreated)
78+
in [serverStatus](https://www.mongodb.com/docs/manual/reference/command/serverStatus) has not changed.
9279

93-
94-
95-
Not Primary - Reset Connection Pool
96-
```````````````````````````````````
80+
### Not Primary - Reset Connection Pool
9781

9882
This test requires a replica set with server version 4.0.
9983

100-
101-
- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1},
102-
data: {failCommands: ["insert"], errorCode: 10107}}``
103-
- Execute an insert into the test collection of a ``{test: 1}``
104-
document.
84+
- Set the following fail point:
85+
`{configureFailPoint: "failCommand", mode: {times: 1}, data: {failCommands: ["insert"], errorCode: 10107}}`
86+
- Execute an insert into the test collection of a `{test: 1}` document.
10587
- Verify that the insert failed with an operation failure with 10107 code.
106-
- If the driver implements the `CMAP`_ specification, verify that a `PoolClearedEvent`_
107-
has been published
108-
- Execute an insert into the test collection of a ``{test: 1}``
109-
document and verify that it succeeds.
110-
- If the driver does NOT implement the `CMAP`_ specification, use the `serverStatus`_
111-
command to verify `connections.totalCreated`_ has increased by 1.
112-
113-
114-
Shutdown in progress - Reset Connection Pool
115-
````````````````````````````````````````````
88+
- If the driver implements the [CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md)
89+
specification, verify that a
90+
[PoolClearedEvent](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events) has been
91+
published
92+
- Execute an insert into the test collection of a `{test: 1}` document and verify that it succeeds.
93+
- If the driver does NOT implement the
94+
[CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md) specification, use the
95+
[serverStatus](https://www.mongodb.com/docs/manual/reference/command/serverStatus) command to verify
96+
[connections.totalCreated](https://www.mongodb.com/docs/manual/reference/command/serverStatus/#serverstatus.connections.totalCreated)
97+
has increased by 1.
98+
99+
### Shutdown in progress - Reset Connection Pool
116100

117101
This test should be run on all server versions >= 4.0.
118102

119103
Perform the following operations on a client configured to NOT retry writes:
120104

121-
- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1},
122-
data: {failCommands: ["insert"], errorCode: 91}}``
123-
- Execute an insert into the test collection of a ``{test: 1}``
124-
document.
105+
- Set the following fail point:
106+
`{configureFailPoint: "failCommand", mode: {times: 1}, data: {failCommands: ["insert"], errorCode: 91}}`
107+
- Execute an insert into the test collection of a `{test: 1}` document.
125108
- Verify that the insert failed with an operation failure with 91 code.
126-
- If the driver implements the `CMAP`_ specification, verify that a `PoolClearedEvent`_
127-
has been published
128-
- Execute an insert into the test collection of a ``{test: 1}``
129-
document and verify that it succeeds.
130-
- If the driver does NOT implement the `CMAP`_ specification, use the `serverStatus`_
131-
command to verify `connections.totalCreated`_ has increased by 1.
132-
133-
134-
Interrupted at shutdown - Reset Connection Pool
135-
```````````````````````````````````````````````
109+
- If the driver implements the [CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md)
110+
specification, verify that a
111+
[PoolClearedEvent](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events) has been
112+
published
113+
- Execute an insert into the test collection of a `{test: 1}` document and verify that it succeeds.
114+
- If the driver does NOT implement the
115+
[CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md) specification, use the
116+
[serverStatus](https://www.mongodb.com/docs/manual/reference/command/serverStatus) command to verify
117+
[connections.totalCreated](https://www.mongodb.com/docs/manual/reference/command/serverStatus/#serverstatus.connections.totalCreated)
118+
has increased by 1.
119+
120+
### Interrupted at shutdown - Reset Connection Pool
136121

137122
This test should be run on all server versions >= 4.0.
138123

139124
Perform the following operations on a client configured to NOT retry writes:
140125

141-
- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1},
142-
data: {failCommands: ["insert"], errorCode: 11600}}``
143-
- Execute an insert into the test collection of a ``{test: 1}``
144-
document.
126+
- Set the following fail point:
127+
`{configureFailPoint: "failCommand", mode: {times: 1}, data: {failCommands: ["insert"], errorCode: 11600}}`
128+
- Execute an insert into the test collection of a `{test: 1}` document.
145129
- Verify that the insert failed with an operation failure with 11600 code.
146-
- If the driver implements the `CMAP`_ specification, verify that a `PoolClearedEvent`_
147-
has been published
148-
- Execute an insert into the test collection of a ``{test: 1}``
149-
document and verify that it succeeds.
150-
- If the driver does NOT implement the `CMAP`_ specification, use the `serverStatus`_
151-
command to verify `connections.totalCreated`_ has increased by 1.
152-
130+
- If the driver implements the [CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md)
131+
specification, verify that a
132+
[PoolClearedEvent](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events) has been
133+
published
134+
- Execute an insert into the test collection of a `{test: 1}` document and verify that it succeeds.
135+
- If the driver does NOT implement the
136+
[CMAP](../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md) specification, use the
137+
[serverStatus](https://www.mongodb.com/docs/manual/reference/command/serverStatus) command to verify
138+
[connections.totalCreated](https://www.mongodb.com/docs/manual/reference/command/serverStatus/#serverstatus.connections.totalCreated)
139+
has increased by 1.
153140

141+
## Questions and Answers
154142

155-
Questions and Answers
156-
---------------------
143+
### Do we need to wait for re-election after the first test?
157144

158-
Do we need to wait for re-election after the first test?
159-
````````````````````````````````````````````````````````
145+
Since test setup requires creation of a collection, a primary must exist, so subsequent tests will block in server
146+
selection until a primary is available again.
160147

161-
Since test setup requires creation of a collection, a primary must exist, so subsequent tests will block in server selection until a primary is available again.
162-
163-
164-
Why do tests check for a successful insert operation in addition to checking that the pool was updated appropriately?
165-
`````````````````````````````````````````````````````````````````````````````````````````````````````````````````````
148+
### Why do tests check for a successful insert operation in addition to checking that the pool was updated appropriately?
166149

167150
Ensuring that we can run a successful insert after the primary steps down and without needing to recreate the
168-
``MongoClient`` serves to test the resiliency of drivers in the event of a failover/election. Even though checking for
169-
a successful insert operation does not directly test functionality introduced in this specification, it is a
151+
`MongoClient` serves to test the resiliency of drivers in the event of a failover/election. Even though checking for a
152+
successful insert operation does not directly test functionality introduced in this specification, it is a
170153
straightforward way to test driver resiliency against a live replica set undergoing an election. This testing
171-
methodology is in contrast to the one adopted by the SDAM spec tests that rely entirely on mocking with no actual
172-
server communication.
173-
174-
175-
.. _CMAP: ../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md
176-
.. _PoolClearedEvent: /source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events
177-
.. _serverStatus: https://www.mongodb.com/docs/manual/reference/command/serverStatus
178-
.. _connections.totalCreated: https://www.mongodb.com/docs/manual/reference/command/serverStatus/#serverstatus.connections.totalCreated
154+
methodology is in contrast to the one adopted by the SDAM spec tests that rely entirely on mocking with no actual server
155+
communication.

0 commit comments

Comments
 (0)