1=======================
2Connection String Tests
3=======================
4
5The YAML and JSON files in this directory tree are platform-independent tests
6that drivers can use to prove their conformance to the Connection String Spec.
7
8As the spec is primarily concerned with parsing the parts of a URI, these tests
9do not focus on host and option validation. Where necessary, the tests use
10options known to be (un)supported by drivers to assert behavior such as issuing
11a warning on repeated option keys. As such these YAML tests are in no way a
12replacement for more thorough testing. However, they can provide an initial
13verification of your implementation.
14
15Version
16-------
17
18Files in the "specifications" repository have no version scheme. They are not
19tied to a MongoDB server version.
20
21Format
22------
23
24Each YAML file contains an object with a single ``tests`` key. This key is an
25array of test case objects, each of which have the following keys:
26
27- ``description``: A string describing the test.
28- ``uri``: A string containing the URI to be parsed.
29- ``valid:`` A boolean indicating if the URI should be considered valid.
30- ``warning:`` A boolean indicating whether URI parsing should emit a warning
31 (independent of whether or not the URI is valid).
32- ``hosts``: An array of host objects, each of which have the following keys:
33
34 - ``type``: A string denoting the type of host. Possible values are "ipv4",
35 "ip_literal", "hostname", and "unix". Asserting the type is *optional*.
36 - ``host``: A string containing the parsed host.
37 - ``port``: An integer containing the parsed port number.
38- ``auth``: An object containing the following keys:
39
40 - ``username``: A string containing the parsed username. For auth mechanisms
41 that do not utilize a password, this may be the entire ``userinfo`` token
42 (as discussed in `RFC 2396 <https://www.ietf.org/rfc/rfc2396.txt>`_).
43 - ``password``: A string containing the parsed password.
44 - ``db``: A string containing the parsed authentication database. For legacy
45 implementations that support namespaces (databases and collections) this may
46 be the full namespace eg: ``<db>.<coll>``
47- ``options``: An object containing key/value pairs for each parsed query string
48 option.
49
50If a test case includes a null value for one of these keys (e.g. ``auth: ~``,
51``port: ~``), no assertion is necessary. This both simplifies parsing of the
52test files (keys should always exist) and allows flexibility for drivers that
53might substitute default values *during* parsing (e.g. omitted ``port`` could be
54parsed as 27017).
55
56The ``valid`` and ``warning`` fields are boolean in order to keep the tests
57flexible. We are not concerned with asserting the format of specific error or
58warnings messages strings.
59
60Use as unit tests
61=================
62
63Testing whether a URI is valid or not should simply be a matter of checking
64whether URI parsing (or MongoClient construction) raises an error or exception.
65Testing for emitted warnings may require more legwork (e.g. configuring a log
66handler and watching for output).
67
68Not all drivers may be able to directly assert the hosts, auth credentials, and
69options. Doing so may require exposing the driver's URI parsing component.
70
71The file valid-db-with-dotted-name.yml is a special case for testing drivers
72that allow dotted namespaces, instead of only database names, in the Auth
73Database portion of the URI.
View as plain text