diff --git a/source/uri-options/tests/README.rst b/source/uri-options/tests/README.rst new file mode 100644 index 0000000000..f6a128bba9 --- /dev/null +++ b/source/uri-options/tests/README.rst @@ -0,0 +1,54 @@ +======================= +URI Options Tests +======================= + +The YAML and JSON files in this directory tree are platform-independent tests +that drivers can use to prove their conformance to the URI Options spec. + +These tests use the same format as the Connection String spec tests. + +Version +------- + +Files in the "specifications" repository have no version scheme. They are not +tied to a MongoDB server version. + +Format +------ + +Each YAML file contains an object with a single ``tests`` key. This key is an +array of test case objects, each of which have the following keys: + +- ``description``: A string describing the test. +- ``uri``: A string containing the URI to be parsed. +- ``valid``: A boolean indicating if the URI should be considered valid. +- ``warning``: A boolean indicating whether URI parsing should emit a warning. +- ``hosts``: Included for compatibility with the Connection String spec tests. This will always be ``~``. +- ``auth``: Included for compatibility with the Connection String spec tests. This will always be ``~``. +- ``options``: An object containing key/value pairs for each parsed query string + option. + +If a test case includes a null value for one of these keys (e.g. ``auth: ~``, +``hosts: ~``), no assertion is necessary. This both simplifies parsing of the +test files (keys should always exist) and allows flexibility for drivers that +might substitute default values *during* parsing (e.g. omitted ``hosts`` could be +parsed as ``["localhost"]``). + +The ``valid`` and ``warning`` fields are boolean in order to keep the tests +flexible. We are not concerned with asserting the format of specific error or +warnings messages strings. + +Under normal circumstances, it should not be necessary to specify both +``valid: false`` and ``warning: true``. Typically, a URI test case will either +yield an error (e.g. options conflict) or a warning (e.g. invalid type or value +for an option), but not both. + +Use as unit tests +================= + +Testing whether a URI is valid or not requires testing whether URI parsing (or +MongoClient construction) causes a warning due to a URI option being invalid and asserting that the +options parsed from the URI match those listed in the ``options`` field. + +Note that there are tests for each of the options marked as optional; drivers will need to implement +logic to skip over the optional tests that they don’t implement. diff --git a/source/uri-options/uri-options.rst b/source/uri-options/uri-options.md similarity index 100% rename from source/uri-options/uri-options.rst rename to source/uri-options/uri-options.md