Rename source/uri-options/uri-options.rst to source/uri-options/uri-o…

…ptions.md

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.