@@ -12,12 +12,21 @@ Command Monitoring
1212Testing
1313=======
1414
15+ Tests in ``unified `` are implemented in the `Unified Test Format <../../unified-test-format/unified-test-format.rst >`__ and require
16+ schema version 1.0. Tests in ``legacy `` should be run as described below.
17+
1518Tests are provided in YML and JSON format to assert proper upconversion of commands.
1619
20+ Database and Collection Names
21+ -----------------------------
22+
23+ The collection under test is specified in each test file with the fields
24+ ``database_name `` and ``collection_name ``.
25+
1726Data
1827----
1928
20- The {{ data}} at the beginning of each test file is the data that should exist in the
29+ The `` data `` at the beginning of each test file is the data that should exist in the
2130collection under test before each test run.
2231
2332Expectations
@@ -26,21 +35,21 @@ Expectations
2635Fake Placeholder Values
2736```````````````````````
2837
29- When an attribute in an expectation contains the value {{ "42"}}, {{42}} or {{""}} , this is a fake
38+ When an attribute in an expectation contains the value `` "42" ``, `` 42 `` or `` "" `` , this is a fake
3039placeholder value indicating that a special case MUST be tested that could not be
3140expressed in a YAML or JSON test. These cases are as follows:
3241
3342Cursor Matching
3443^^^^^^^^^^^^^^^
3544
36- When encountering a {{ cursor}} or {{ getMore}} value of {{ "42"}} in a test, the driver MUST assert
45+ When encountering a `` cursor `` or `` getMore `` value of `` "42" `` in a test, the driver MUST assert
3746that the values are equal to each other and greater than zero.
3847
3948Errors
4049^^^^^^
4150
42- For write errors, {{ code}} values of {{42}} MUST assert that the value is present and
43- greater than zero. {{ errmsg}} values of {{""}} MUST assert that the value is not empty
51+ For write errors, `` code `` values of `` 42 `` MUST assert that the value is present and
52+ greater than zero. `` errmsg `` values of `` "" `` MUST assert that the value is not empty
4453(a string of length greater than 1).
4554
4655OK Values
@@ -56,21 +65,67 @@ Additional Values
5665The expected events provide the minimum data that is required and can be tested. It is
5766possible for more values to be present in the events, such as extra data provided when
5867using sharded clusters or ``nModified `` field in updates. The driver MUST assert the
59- expected data is present and also MUST allow for additional data to be present as well.
60-
61- Ignoring Tests Based On Server Version
62- ``````````````````````````````````````
63-
64- Due to variations in server behaviour, some tests may not be valid on a specific range
65- of server versions and MUST NOT be run. These tests are indicated with the fields
66- {{ignore_if_server_version_greater_than}} and {{ignore_if_server_version_less_than}} which
67- are optionally provided at the description level of the test. When determining if the test
68- must be run or not, use only the minor server version.
69-
70- Example:
71-
72- If {{ignore_if_server_version_greater_than}} is {{3.0}}, then the tests MUST NOT run on
73- {{3.1}} and higher, but MUST run on {{3.0.3}}.
74-
75- Tests which do not have either one of these fields MUST run on all supported server
76- versions.
68+ expected data is present and also MUST allow for additional data to be present as well
69+ at the top level of the command document or reply document.
70+
71+ For example, say the client sends a causally-consistent "distinct" command with
72+ readConcern level "majority", like::
73+
74+ {
75+ "distinct": "collection",
76+ "key": "key",
77+ "readConcern":{
78+ "afterClusterTime": {"$timestamp":{"t":1522336030,"i":1}},
79+ "level":"majority"
80+ },
81+ "$clusterTime": {
82+ "clusterTime": { "$timestamp": { "i": 1, "t": 1522335530 } },
83+ "signature": {
84+ "hash": { "$binary": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=", "$type": "00" },
85+ "keyId": { "$numberLong": "0" }
86+ }
87+ },
88+ "lsid": {
89+ "id": { "$binary": "RaigP3oASqu+galPvRAfcg==", "$type": "04" }
90+ }
91+ }
92+
93+ Then it would pass a command-started event like the following YAML, because the
94+ fields not mentioned in the YAML are ignored::
95+
96+ command:
97+ distinct: collection
98+ key: key
99+
100+ However, if there are fields in command subdocuments that are not mentioned in
101+ the YAML, then the command does *not * pass the test::
102+
103+ command:
104+ distinct: collection
105+ key: key
106+ # Fails because the expected readConcern has no "afterClusterTime".
107+ readConcern:
108+ level: majority
109+
110+ Ignoring Tests Based On Server Version or Topology Type
111+ ```````````````````````````````````````````````````````
112+
113+ Due to variations in server behavior, some tests may not be valid and MUST NOT be run on
114+ certain server versions or topology types. These tests are indicated with any of the
115+ following fields, which will be optionally provided at the ``description `` level of each
116+ test:
117+
118+ - ``ignore_if_server_version_greater_than `` (optional): If specified, the test MUST be
119+ skipped if the minor version of the server is greater than this minor version. The
120+ server's patch version MUST NOT be considered. For example, a value of ``3.0 `` implies
121+ that the test can run on server version ``3.0.15 `` but not ``3.1.0 ``.
122+
123+ - ``ignore_if_server_version_less_than `` (optional): If specified, the test MUST be
124+ skipped if the minor version of the server is less than this minor version. The
125+ server's patch version MUST NOT be considered. For example, a value of ``3.2 `` implies
126+ that the test can run on server version ``3.2.0 `` but not ``3.0.15 ``.
127+
128+ - ``ignore_if_topology_type `` (optional): An array of server topologies for which the test
129+ MUST be skipped. Valid topologies are "single", "replicaset", and "sharded".
130+
131+ Tests that have none of these fields MUST be run on all supported server versions.
0 commit comments