You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: data/change_stream/README.rst
+57-23Lines changed: 57 additions & 23 deletions
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,7 @@ Each YAML file has the following keys:
33
33
- ``description``: The name of the test.
34
34
- ``minServerVersion``: The minimum server version to run this test against. If not present, assume there is no minimum server version.
35
35
- ``maxServerVersion``: Reserved for later use
36
-
- ``failPoint``: Reserved for later use
36
+
- ``failPoint``(optional): The configureFailPoint command document to run to configure a fail point on the primary server.
37
37
- ``target``: The entity on which to run the change stream. Valid values are:
38
38
39
39
- ``collection``: Watch changes on collection ``database_name.collection_name``
@@ -48,7 +48,7 @@ Each YAML file has the following keys:
48
48
- ``database``: Database against which to run the operation
49
49
- ``collection``: Collection against which to run the operation
50
50
- ``name``: Name of the command to run
51
-
- ``arguments``: Object of arguments for the command (ex: document to insert)
51
+
- ``arguments`` (optional): Object of arguments for the command (ex: document to insert)
52
52
53
53
- ``expectations``: Optional list of command-started events in Extended JSON format
54
54
- ``result``: Document with ONE of the following fields:
@@ -104,26 +104,26 @@ For each YAML file, for each element in ``tests``:
104
104
- Drop the database ``database2_name``
105
105
- Create the database ``database_name`` and the collection ``database_name.collection_name``
106
106
- Create the database ``database2_name`` and the collection ``database2_name.collection2_name``
107
+
- If the the ``failPoint`` field is present, configure the fail point on the primary server. See
108
+
`Server Fail Point <../../transactions/tests#server-fail-point>`_ in the
109
+
Transactions spec test documentation for more information.
107
110
108
111
- Create a new MongoClient ``client``
109
112
- Begin monitoring all APM events for ``client``. (If the driver uses global listeners, filter out all events that do not originate with ``client``). Filter out any "internal" commands (e.g. ``isMaster``)
110
-
- Using ``client``, create a changeStream ``changeStream`` against the specified ``target``. Use ``changeStreamPipeline`` and ``changeStreamOptions`` if they are non-empty
111
-
- Using ``globalClient``, run every operation in ``operations`` in serial against the server
112
-
- Wait until either:
113
-
114
-
- An error occurs
115
-
- All operations have been successful AND the changeStream has received as many changes as there are in ``result.success``
116
-
113
+
- Using ``client``, create a changeStream ``changeStream`` against the specified ``target``. Use ``changeStreamPipeline`` and ``changeStreamOptions`` if they are non-empty. Capture any error.
114
+
- If there was no error, use ``globalClient`` and run every operation in ``operations`` in serial against the server until all operations have been executed or an error is thrown. Capture any error.
115
+
- If there was no error and ``result.error`` is set, iterate ``changeStream`` once and capture any error.
116
+
- If there was no error and ``result.success`` is non-empty, iterate ``changeStream`` until it returns as many changes as there are elements in the ``result.success`` array or an error is thrown. Capture any error.
117
117
- Close ``changeStream``
118
118
- If there was an error:
119
119
120
120
- Assert that an error was expected for the test.
121
-
- Assert that the error MATCHES ``results.error``
121
+
- Assert that the error MATCHES ``result.error``
122
122
123
123
- Else:
124
124
125
125
- Assert that no error was expected for the test
126
-
- Assert that the changes received from ``changeStream`` MATCH the results in ``results.success``
126
+
- Assert that the changes received from ``changeStream`` MATCH the results in ``result.success``
127
127
128
128
- If there are any ``expectations``
129
129
@@ -139,19 +139,53 @@ After running all tests
139
139
- Drop database ``database_name``
140
140
- Drop database ``database2_name``
141
141
142
+
Iterating the Change Stream
143
+
---------------------------
144
+
145
+
Although synchronous drivers must provide a [non-blocking mode of iteration](../change-streams.rst#not-blocking-on-iteration), asynchronous drivers may not have such a mechanism. Those drivers with only a blocking mode of iteration should be careful not to iterate the change stream unnecessarily, as doing so could cause the test runner to block indefinitely. For this reason, the test runner procedure above advises drivers to take a conservative approach to iteration.
146
+
147
+
If the test expects an error and one was not thrown by either creating the change stream or executing the test's operations, iterating the change stream once allows for an error to be thrown by a ``getMore`` command. If the test does not expect any error, the change stream should be iterated only until it returns as many result documents as are expected by the test.
142
148
143
149
Prose Tests
144
150
===========
145
151
146
-
The following tests have not yet been automated, but MUST still be tested
147
-
148
-
#. ``ChangeStream`` must continuously track the last seen ``resumeToken``
149
-
#. ``ChangeStream`` will throw an exception if the server response is missing the resume token
150
-
#. ``ChangeStream`` will automatically resume one time on a resumable error (including `not master`) with the initial pipeline and options, except for the addition/update of a ``resumeToken``.
151
-
#. ``ChangeStream`` will not attempt to resume on any error encountered while executing an ``aggregate`` command.
152
-
#. ``ChangeStream`` will not attempt to resume after encountering error code 11601 (Interrupted), 136 (CappedPositionLost), or 237 (CursorKilled) while executing a ``getMore`` command.
153
-
#. ``ChangeStream`` will perform server selection before attempting to resume, using initial ``readPreference``
154
-
#. Ensure that a cursor returned from an aggregate command with a cursor id and an initial empty batch is not closed on the driver side.
155
-
#. The ``killCursors`` command sent during the "Resume Process" must not be allowed to throw an exception.
156
-
#. ``$changeStream`` stage for ``ChangeStream`` against a server ``>=4.0`` that has not received any results yet MUST include a ``startAtOperationTime`` option when resuming a changestream.
157
-
#. ``ChangeStream`` will resume after a ``killCursors`` command is issued for its child cursor.
152
+
The following tests have not yet been automated, but MUST still be tested. All tests SHOULD be run on both replica sets and sharded clusters unless otherwise specified:
153
+
154
+
1. ``ChangeStream`` must continuously track the last seen ``resumeToken``
155
+
2. ``ChangeStream`` will throw an exception if the server response is missing the resume token (if wire version is < 8, this is a driver-side error; for 8+, this is a server-side error)
156
+
3. After receiving a ``resumeToken``, ``ChangeStream`` will automatically resume one time on a resumable error with the initial pipeline and options, except for the addition/update of a ``resumeToken``.
157
+
4. ``ChangeStream`` will not attempt to resume on any error encountered while executing an ``aggregate`` command. Note that retryable reads may retry ``aggregate`` commands. Drivers should be careful to distinguish retries from resume attempts. Alternatively, drivers may specify `retryReads=false` or avoid using a [retryable error](../../retryable-reads/retryable-reads.rst#retryable-error) for this test.
158
+
5. ``ChangeStream`` will not attempt to resume after encountering error code 11601 (Interrupted), 136 (CappedPositionLost), or 237 (CursorKilled) while executing a ``getMore`` command.
159
+
6. ``ChangeStream`` will perform server selection before attempting to resume, using initial ``readPreference``
160
+
7. Ensure that a cursor returned from an aggregate command with a cursor id and an initial empty batch is not closed on the driver side.
161
+
8. The ``killCursors`` command sent during the "Resume Process" must not be allowed to throw an exception.
162
+
9. ``$changeStream`` stage for ``ChangeStream`` against a server ``>=4.0`` and ``<4.0.7`` that has not received any results yet MUST include a ``startAtOperationTime`` option when resuming a change stream.
163
+
10. ``ChangeStream`` will resume after a ``killCursors`` command is issued for its child cursor.
164
+
11. - For a ``ChangeStream`` under these conditions:
165
+
- Running against a server ``>=4.0.7``.
166
+
- The batch is empty or has been iterated to the last document.
167
+
- Expected result:
168
+
- ``getResumeToken`` must return the ``postBatchResumeToken`` from the current command response.
169
+
12. - For a ``ChangeStream`` under these conditions:
170
+
- Running against a server ``<4.0.7``.
171
+
- The batch is empty or has been iterated to the last document.
172
+
- Expected result:
173
+
- ``getResumeToken`` must return the ``_id`` of the last document returned if one exists.
174
+
- ``getResumeToken`` must return ``resumeAfter`` from the initial aggregate if the option was specified.
175
+
- If ``resumeAfter`` was not specified, the ``getResumeToken`` result must be empty.
176
+
13. - For a ``ChangeStream`` under these conditions:
177
+
- The batch is not empty.
178
+
- The batch has been iterated up to but not including the last element.
179
+
- Expected result:
180
+
- ``getResumeToken`` must return the ``_id`` of the previous document returned.
181
+
14. - For a ``ChangeStream`` under these conditions:
182
+
- The batch is not empty.
183
+
- The batch hasn’t been iterated at all.
184
+
- Only the initial ``aggregate`` command has been executed.
185
+
- Expected result:
186
+
- ``getResumeToken`` must return ``startAfter`` from the initial aggregate if the option was specified.
187
+
- ``getResumeToken`` must return ``resumeAfter`` from the initial aggregate if the option was specified.
188
+
- If neither the ``startAfter`` nor ``resumeAfter`` options were specified, the ``getResumeToken`` result must be empty.
189
+
- Note that this test cannot be run against sharded topologies because in that case the initial ``aggregate`` command only establishes cursors on the shards and always returns an empty ``firstBatch``.
190
+
17. ``$changeStream`` stage for ``ChangeStream`` started with ``startAfter`` against a server ``>=4.1.1`` that has not received any results yet MUST include a ``startAfter`` option and MUST NOT include a ``resumeAfter`` option when resuming a change stream.
191
+
18. ``$changeStream`` stage for ``ChangeStream`` started with ``startAfter`` against a server ``>=4.1.1`` that has received at least one result MUST include a ``resumeAfter`` option and MUST NOT include a ``startAfter`` option when resuming a change stream.
0 commit comments