@@ -41,9 +41,19 @@ Each YAML file has the following keys:
4141 - ``operations ``: Array of documents, each describing an operation to be
4242 executed. Each document has the following fields:
4343
44- - ``name ``: The name of the operation.
44+ - ``name ``: The name of the operation on `` object `` .
4545
46- - ``arguments ``: The names and values of arguments.
46+ - ``object ``: The name of the object to perform the operation on. Can be
47+ "database", collection", "session0", or "session1".
48+
49+ - ``collectionOptions ``: Optional, parameters to pass to the Collection()
50+ used for this operation.
51+
52+ - ``command_name ``: Present only when ``name `` is "runCommand". The name
53+ of the command to run. Required for languages that are unable preserve
54+ the order keys in the "command" argument when parsing JSON/YAML.
55+
56+ - ``arguments ``: Optional, the names and values of arguments.
4757
4858 - ``result ``: The return value from the operation, if any. If the
4959 operation is expected to return an error, the ``result `` has one field,
@@ -64,12 +74,14 @@ Each YAML file has the following keys:
6474Use as integration tests
6575========================
6676
67- Run a MongoDB replica set with a primary, two secondaries, and an arbiter,
68- server version 4.0 or later. (Including two secondaries ensures that transaction
69- pinning works properly. Include an arbiter to ensure no new bugs have been
70- introduced related to arbiters.)
77+ Run a MongoDB replica set with a primary, a secondary, and an arbiter,
78+ server version 4.0 or later. (Including a secondary ensures that server
79+ selection in a transaction works properly. Including an arbiter helps ensure
80+ that no new bugs have been introduced related to arbiters.)
81+
82+ Load each YAML (or JSON) file using a Canonical Extended JSON parser.
7183
72- For each YAML file, for each element in ``tests ``:
84+ Then for each element in ``tests ``:
7385
7486#. Create a MongoClient and call
7587 ``client.admin.runCommand({killAllSessions: []}) `` to clean up any open
@@ -96,34 +108,31 @@ For each YAML file, for each element in ``tests``:
96108#. For each element in ``operations ``:
97109
98110 - Enter a "try" block or your programming language's closest equivalent.
99- - If ``name `` is "startTransaction", "commitTransaction", or
100- "abortTransaction", call the named method on ``session0 `` or
101- ``session1 ``, depending on the "session" argument.
102- - If ``name `` is "runCommand", call the runCommand method on the database
103- specified in the test. Pass the argument named "command" to the runCommand
104- method. Pass ``session0 `` or ``session1 `` to the runCommand method, depending
105- on which session's name is in the arguments list. If ``arguments ``
106- contains no "session", pass no explicit session to the method. If ``arguments ``
107- includes "readPreference", also pass the read preference to the runCommand
108- method.
109- - Otherwise, ``name `` refers to a CRUD method, such as ``insertOne ``.
110- Execute the named method on the "transactions-tests" database on the "test"
111- collection, passing the arguments listed. Pass ``session0 `` or ``session1 ``
112- to the method, depending on which session's name is in the arguments list.
111+ - Create a Database object from the MongoClient, using the ``database_name ``
112+ field at the top level of the test file.
113+ - Create a Collection object from the Database, using the
114+ ``collection_name `` field at the top level of the test file.
115+ If ``collectionOptions `` is present create the Collection object with the
116+ provided options. Otherwise create the object with the default options.
117+ - Execute the named method on the provided ``object ``, passing the
118+ arguments listed. Pass ``session0 `` or ``session1 `` to the method,
119+ depending on which session's name is in the arguments list.
113120 If ``arguments `` contains no "session", pass no explicit session to the
114- method. If ``arguments `` includes "readPreference", configure the specified
115- read preference in whatever manner the driver supports.
121+ method.
116122 - If the driver throws an exception / returns an error while executing this
117123 series of operations, store the error message and server error code.
118124 - If the result document has an "errorContains" field, verify that the
119125 method threw an exception or returned an error, and that the value of the
120- "errorContains" field matches the error string. If the result document has
121- an "errorCodeName" field, verify that the method threw a command failed
122- exception or returned an error, and that the value of the "errorCodeName"
123- field matches the "codeName" in the server error response.
126+ "errorContains" field matches the error string. "errorContains" is a
127+ substring (case-insensitive) of the actual error message.
128+ If the result document has an "errorCodeName" field, verify that the
129+ method threw a command failed exception or returned an error, and that
130+ the value of the "errorCodeName" field matches the "codeName" in the
131+ server error response.
132+ If the operation returns a raw command response, eg from ``runCommand ``,
133+ then compare only the fields present in the expected result document.
124134 Otherwise, compare the method's return value to ``result `` using the same
125- logic as the CRUD Spec Tests runner. key is a substring (case-insensitive)
126- of the actual error message.
135+ logic as the CRUD Spec Tests runner.
127136
128137#. Call ``session0.endSession() `` and ``session1.endSession ``.
129138#. If the test includes a list of command-started events in ``expectations ``,
0 commit comments