1====================================
2Initial DNS Seedlist Discovery tests
3====================================
4
5This directory contains platform-independent tests that drivers can use
6to prove their conformance to the Initial DNS Seedlist Discovery spec.
7
8Test Setup
9----------
10
11The tests in the ``replica-set`` directory MUST be executed against a
12three-node replica set on localhost ports 27017, 27018, and 27019 with
13replica set name ``repl0``.
14
15The tests in the ``load-balanced`` directory MUST be executed against a
16load-balanced sharded cluster with the mongos servers running on localhost ports
1727017 and 27018 (corresponding to the script in `drivers-evergreen-tools`_). The
18load balancers, shard servers, and config servers may run on any open ports.
19
20.. _`drivers-evergreen-tools`: https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/run-load-balancer.sh
21
22The tests in the ``sharded`` directory MUST be executed against a sharded
23cluster with the mongos servers running on localhost ports 27017 and 27018.
24Shard servers and config servers may run on any open ports.
25
26In all cases, the clusters MUST be started with SSL enabled.
27
28To run the tests that accompany this spec, you need to configure the SRV and
29TXT records with a real name server. The following records are required for
30these tests::
31
32 Record TTL Class Address
33 localhost.test.build.10gen.cc. 86400 IN A 127.0.0.1
34 localhost.sub.test.build.10gen.cc. 86400 IN A 127.0.0.1
35
36 Record TTL Class Port Target
37 _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
38 _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc.
39 _mongodb._tcp.test2.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc.
40 _mongodb._tcp.test2.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc.
41 _mongodb._tcp.test3.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
42 _mongodb._tcp.test5.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
43 _mongodb._tcp.test6.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
44 _mongodb._tcp.test7.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
45 _mongodb._tcp.test8.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
46 _mongodb._tcp.test10.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
47 _mongodb._tcp.test11.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
48 _mongodb._tcp.test12.test.build.10gen.cc. 86400 IN SRV 27017 localhost.build.10gen.cc.
49 _mongodb._tcp.test13.test.build.10gen.cc. 86400 IN SRV 27017 test.build.10gen.cc.
50 _mongodb._tcp.test14.test.build.10gen.cc. 86400 IN SRV 27017 localhost.not-test.build.10gen.cc.
51 _mongodb._tcp.test15.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.not-build.10gen.cc.
52 _mongodb._tcp.test16.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.not-10gen.cc.
53 _mongodb._tcp.test17.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.not-cc.
54 _mongodb._tcp.test18.test.build.10gen.cc. 86400 IN SRV 27017 localhost.sub.test.build.10gen.cc.
55 _mongodb._tcp.test19.test.build.10gen.cc. 86400 IN SRV 27017 localhost.evil.build.10gen.cc.
56 _mongodb._tcp.test19.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
57 _mongodb._tcp.test20.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
58 _mongodb._tcp.test21.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc.
59 _customname._tcp.test22.test.build.10gen.cc 86400 IN SRV 27017 localhost.test.build.10gen.cc
60
61 Record TTL Class Text
62 test5.test.build.10gen.cc. 86400 IN TXT "replicaSet=repl0&authSource=thisDB"
63 test6.test.build.10gen.cc. 86400 IN TXT "replicaSet=repl0"
64 test6.test.build.10gen.cc. 86400 IN TXT "authSource=otherDB"
65 test7.test.build.10gen.cc. 86400 IN TXT "ssl=false"
66 test8.test.build.10gen.cc. 86400 IN TXT "authSource"
67 test10.test.build.10gen.cc. 86400 IN TXT "socketTimeoutMS=500"
68 test11.test.build.10gen.cc. 86400 IN TXT "replicaS" "et=rep" "l0"
69 test20.test.build.10gen.cc. 86400 IN TXT "loadBalanced=true"
70 test21.test.build.10gen.cc. 86400 IN TXT "loadBalanced=false"
71
72Note that ``test4`` is omitted deliberately to test what happens with no SRV
73record. ``test9`` is missing because it was deleted during the development of
74the tests. The missing ``test.`` sub-domain in the SRV record target for
75``test12`` is deliberate. ``test22`` is used to test a custom service name
76(``customname``).
77
78In our tests we have used ``localhost.test.build.10gen.cc`` as the domain, and
79then configured ``localhost.test.build.10gen.cc`` to resolve to 127.0.0.1.
80
81You need to adapt the records shown above to replace ``test.build.10gen.cc``
82with your own domain name, and update the "uri" field in the YAML or JSON files
83in this directory with the actual domain.
84
85Test Format and Use
86-------------------
87
88These YAML and JSON files contain the following fields:
89
90- ``uri``: a ``mongodb+srv`` connection string
91- ``seeds``: the expected set of initial seeds discovered from the SRV record
92- ``numSeeds``: the expected number of initial seeds discovered from the SRV
93 record. This is mainly used to test ``srvMaxHosts``, since randomly selected
94 hosts cannot be deterministically asserted.
95- ``hosts``: the discovered topology's list of hosts once SDAM completes a scan
96- ``numHosts``: the expected number of hosts discovered once SDAM completes a
97 scan. This is mainly used to test ``srvMaxHosts``, since randomly selected
98 hosts cannot be deterministically asserted.
99- ``options``: the parsed `URI options`_ as discovered from the
100 `Connection String`_'s "Connection Options" component and SRV resolution
101 (e.g. TXT records, implicit ``tls`` default).
102- ``parsed_options``: additional, parsed options from other `Connection String`_
103 components. This is mainly used for asserting ``UserInfo`` (as ``user`` and
104 ``password``) and ``Auth database`` (as ``auth_database``).
105- ``error``: indicates that the parsing of the URI, or the resolving or
106 contents of the SRV or TXT records included errors.
107- ``comment``: a comment to indicate why a test would fail.
108
109.. _`Connection String`: ../../connection-string/connection-string-spec.rst
110.. _`URI options`: ../../uri-options/uri-options.rst
111
112For each file, create a MongoClient initialized with the ``mongodb+srv``
113connection string.
114
115If ``seeds`` is specified, drivers SHOULD verify that the set of hosts in the
116client's initial seedlist matches the list in ``seeds``. If ``numSeeds`` is
117specified, drivers SHOULD verify that the size of that set matches ``numSeeds``.
118
119If ``hosts`` is specified, drivers MUST verify that the set of
120ServerDescriptions in the client's TopologyDescription eventually matches the
121list in ``hosts``. If ``numHosts`` is specified, drivers MUST verify that the
122size of that set matches ``numHosts``.
123
124If ``options`` is specified, drivers MUST verify each of the values under
125``options`` match the MongoClient's parsed value for that option. There may be
126other options parsed by the MongoClient as well, which a test does not verify.
127
128If ``parsed_options`` is specified, drivers MUST verify that each of the values
129under ``parsed_options`` match the MongoClient's parsed value for that option.
130Supported values include, but are not limited to, ``user`` and ``password``
131(parsed from ``UserInfo``) and ``auth_database`` (parsed from
132``Auth database``).
133
134If ``error`` is specified and ``true``, drivers MUST verify that an error has
135been thrown.
View as plain text