...

Text file src/go.mongodb.org/mongo-driver/testdata/read-write-concern/README.rst

Documentation: go.mongodb.org/mongo-driver/testdata/read-write-concern

     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 Read and Write Concern
     7specification.
     8
     9Version
    10-------
    11
    12Files in the "specifications" repository have no version scheme. They are not
    13tied to a MongoDB server version.
    14
    15Format
    16------
    17
    18Connection String
    19~~~~~~~~~~~~~~~~~
    20
    21These tests are designed to exercise the connection string parsing related
    22to read concern and write concern.
    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 parsing the uri should result in an error.
    30- ``writeConcern:`` A document indicating the expected write concern.
    31- ``readConcern:`` A document indicating the expected read concern.
    32
    33If a test case includes a null value for one of these keys, or if the key is missing,
    34no assertion is necessary. This both simplifies parsing of the test files and allows flexibility
    35for drivers that might substitute default values *during* parsing.
    36
    37Document
    38~~~~~~~~
    39
    40These tests are designed to ensure compliance with the spec in relation to what should be
    41sent to the server.
    42
    43Each YAML file contains an object with a single ``tests`` key. This key is an
    44array of test case objects, each of which have the following keys:
    45
    46- ``description``: A string describing the test.
    47- ``valid:``: a boolean indicating if the write concern created from the document is valid.
    48- ``writeConcern:`` A document indicating the write concern to use.
    49- ``writeConcernDocument:`` A document indicating the write concern to be sent to the server.
    50- ``readConcern:`` A document indicating the read concern to use.
    51- ``readConcernDocument:`` A document indicating the read concern to be sent to the server.
    52- ``isServerDefault:`` Indicates whether the read or write concern is considered the server's default.
    53- ``isAcknowledged:`` Indicates if the write concern should be considered acknowledged.
    54
    55Operation
    56~~~~~~~~~
    57
    58These tests check that the default write concern is omitted in operations.
    59
    60The spec test format is an extension of `transactions spec tests <https://github.com/mongodb/specifications/blob/master/source/transactions/tests/README.rst>`_ with the following additions:
    61
    62- ``writeConcern`` in the ``databaseOptions`` or ``collectionOptions`` may be an empty document to indicate a `server default write concern <https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.rst#servers-default-writeconcern>`_. For example, in libmongoc:
    63
    64    .. code:: c
    65
    66       /* Create a default write concern, and set on a collection object. */
    67       mongoc_write_concern_t *wc = mongoc_write_concern_new ();
    68       mongoc_collection_set_write_concern (collection, wc);
    69
    70    If the driver has no way to explicitly set a default write concern on a database or collection, ignore the empty ``writeConcern`` document and continue with the test.
    71- The operations ``createIndex``, ``dropIndex`` are introduced.
    72
    73
    74Use as unit tests
    75=================
    76
    77Testing whether a URI is valid or not should simply be a matter of checking
    78whether URI parsing raises an error or exception.
    79Testing for emitted warnings may require more legwork (e.g. configuring a log
    80handler and watching for output).

View as plain text