...

Text file src/go.mongodb.org/mongo-driver/testdata/uri-options/README.rst

Documentation: go.mongodb.org/mongo-driver/testdata/uri-options

     1=======================
     2URI Options 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 URI Options spec.
     7
     8These tests use the same format as the Connection String spec tests.
     9
    10Version
    11-------
    12
    13Files in the "specifications" repository have no version scheme. They are not
    14tied to a MongoDB server version.
    15
    16Format
    17------
    18
    19Each YAML file contains an object with a single ``tests`` key. This key is an
    20array of test case objects, each of which have the following keys:
    21
    22- ``description``: A string describing the test.
    23- ``uri``: A string containing the URI to be parsed.
    24- ``valid``: A boolean indicating if the URI should be considered valid.
    25- ``warning``: A boolean indicating whether URI parsing should emit a warning.
    26- ``hosts``: Included for compatibility with the Connection String spec tests. This will always be ``~``.
    27- ``auth``: Included for compatibility with the Connection String spec tests. This will always be ``~``.
    28- ``options``: An object containing key/value pairs for each parsed query string
    29  option.
    30
    31If a test case includes a null value for one of these keys (e.g. ``auth: ~``,
    32``hosts: ~``), no assertion is necessary. This both simplifies parsing of the
    33test files (keys should always exist) and allows flexibility for drivers that
    34might substitute default values *during* parsing (e.g. omitted ``hosts`` could be
    35parsed as ``["localhost"]``).
    36
    37The ``valid`` and ``warning`` fields are boolean in order to keep the tests
    38flexible. We are not concerned with asserting the format of specific error or
    39warnings messages strings.
    40
    41Under normal circumstances, it should not be necessary to specify both
    42``valid: false`` and ``warning: true``. Typically, a URI test case will either
    43yield an error (e.g. options conflict) or a warning (e.g. invalid type or value
    44for an option), but not both.
    45
    46Use as unit tests
    47=================
    48
    49Testing whether a URI is valid or not requires testing whether URI parsing (or
    50MongoClient construction) causes a warning due to a URI option being invalid and asserting that the
    51options parsed from the URI match those listed in the ``options`` field.
    52
    53Note that there are tests for each of the options marked as optional; drivers will need to implement
    54logic to skip over the optional tests that they don’t implement.

View as plain text