CXX-1682 implement a with_transaction helper method

Author: samantharitter

.mci.yml

@@ -242,6 +242,7 @@ functions:
                   export GRIDFS_TESTS_PATH="$(pwd)/../data/gridfs"
                   export COMMAND_MONITORING_TESTS_PATH="$(pwd)/../data/command-monitoring"
                   export TRANSACTIONS_TESTS_PATH="$(pwd)/../data/transactions"
+                  export WITH_TRANSACTION_TESTS_PATH="$(pwd)/../data/with_transaction"
                   if [ "Windows_NT" == "$OS" ]; then
                       CRUD_TESTS_PATH=$(cygpath -m $CRUD_TESTS_PATH)
                       CTEST_OUTPUT_ON_FAILURE=1 MSBuild.exe /p:Configuration=${build_type} RUN_TESTS.vcxproj

data/with_transaction/README.rst

@@ -0,0 +1,220 @@
+=====================================
+Convenient API for Transactions Tests
+=====================================
+
+.. contents::
+
+----
+
+Introduction
+============
+
+The YAML and JSON files in this directory are platform-independent tests that
+drivers can use to prove their conformance to the Convenient API for
+Transactions spec.  They are designed with the intention of sharing some
+test-runner code with the CRUD, Command Monitoring, and Transaction spec tests.
+
+Several prose tests, which are not easily expressed in YAML, are also presented
+in this file. Those tests will need to be manually implemented by each driver.
+
+Server Fail Point
+=================
+
+See: `Server Fail Point <../../transactions/tests#server-fail-point>`_ in the
+Transactions spec test suite.
+
+Test Format
+===========
+
+Each YAML file has the following keys:
+
+- ``runOn`` (optional): An array of server version and/or topology requirements
+  for which the tests can be run. If the test environment satisfies one or more
+  of these requirements, the tests may be executed; otherwise, this file should
+  be skipped. If this field is omitted, the tests can be assumed to have no
+  particular requirements and should be executed. Each element will have some or
+  all of the following fields:
+
+  - ``minServerVersion`` (optional): The minimum server version (inclusive)
+    required to successfully run the tests. If this field is omitted, it should
+    be assumed that there is no lower bound on the required server version.
+
+  - ``maxServerVersion`` (optional): The maximum server version (inclusive)
+    against which the tests can be run successfully. If this field is omitted,
+    it should be assumed that there is no upper bound on the required server
+    version.
+
+  - ``topology`` (optional): An array of server topologies against which the
+    tests can be run successfully. Valid topologies are "single", "replicaset",
+    and "sharded". If this field is omitted, the default is all topologies (i.e.
+    ``["single", "replicaset", "sharded"]``).
+
+- ``database_name`` and ``collection_name``: The database and collection to use
+  for testing.
+
+- ``data``: The data that should exist in the collection under test before each
+  test run.
+
+- ``tests``: An array of tests that are to be run independently of each other.
+  Each test will have some or all of the following fields:
+
+  - ``description``: The name of the test.
+
+  - ``skipReason`` (optional): If present, the test should be skipped and the
+    string value will specify a reason.
+
+  - ``failPoint`` (optional): The ``configureFailPoint`` command document to run
+    to configure a fail point on the primary server. This option and
+    ``useMultipleMongoses: true`` are mutually exclusive.
+
+  - ``useMultipleMongoses`` (optional): If ``true``, the MongoClient for this
+    test should be initialized with multiple mongos seed addresses. If ``false``
+    or omitted, only a single mongos address should be specified. This field has
+    no effect for non-sharded topologies.
+
+  - ``clientOptions`` (optional): Names and values of options to pass to
+    ``MongoClient()``.
+
+  - ``sessionOptions`` (optional): Names and values of options to pass to
+    ``MongoClient.startSession()``.
+
+  - ``operations``: Array of documents, each describing an operation to be
+    executed. Each document has the following fields:
+
+    - ``name``: The name of the operation on ``object``.
+
+    - ``object``: The name of the object on which to perform the operation. The
+      value will be either "collection" or "session0".
+
+    - ``arguments`` (optional): Names and values of arguments to pass to the
+      operation.
+
+    - ``result`` (optional): The return value from the operation. This will
+      correspond to an operation's result object as defined in the CRUD
+      specification. If the operation is expected to return an error, the
+      ``result`` is a single document that has one or more of the following
+      fields:
+
+      - ``errorContains``: A substring of the expected error message.
+
+      - ``errorCodeName``: The expected "codeName" field in the server
+        error response.
+
+      - ``errorLabelsContain``: A list of error label strings that the
+        error is expected to have.
+
+      - ``errorLabelsOmit``: A list of error label strings that the
+        error is expected not to have.
+
+  - ``expectations`` (optional): List of command-started events.
+
+  - ``outcome``: Document describing the return value and/or expected state of
+    the collection after the operation is executed. Contains the following
+    fields:
+
+    - ``collection``:
+
+      - ``data``: The data that should exist in the collection after the
+        operations have run.
+
+``withTransaction`` Operation
+`````````````````````````````
+
+These tests introduce a ``withTransaction`` operation, which may have the
+following fields:
+
+- ``callback``: Document containing the following field:
+
+  - ``operations``: Array of documents, each describing an operation to be
+    executed. Elements in this array will follow the same structure as the
+    ``operations`` field defined above (and in the CRUD and Transactions specs).
+
+    Note that drivers are expected to evaluate ``error`` and ``result``
+    assertions when executing operations within ``callback.operations``.
+
+- ``options`` (optional): Names and values of options to pass to
+  ``withTransaction()``, which will in turn be used for ``startTransaction()``.
+
+Use as Integration Tests
+========================
+
+Testing against a replica set will require server version 4.0.0 or later. The
+replica set should include a primary, a secondary, and an arbiter. Including a
+secondary ensures that server selection in a transaction works properly.
+Including an arbiter helps ensure that no new bugs have been introduced related
+to arbiters.
+
+Testing against a sharded cluster will require server version 4.1.6 or later.
+A driver that implements support for sharded transactions MUST also run these
+tests against a MongoDB sharded cluster with multiple mongoses. Including
+multiple mongoses (and initializing the MongoClient with multiple mongos seeds!)
+ensures that mongos transaction pinning works properly.
+
+See: `Use as Integration Tests <../../transactions/tests#use-as-integration-tests>`_
+in the Transactions spec test suite for instructions on executing each test.
+
+Take note of the following:
+
+- Most tests will consist of a single "withTransaction" operation to be invoked
+  on the "session0" object. The ``callback`` argument of that operation will
+  resemble the ``operations`` array found in transaction spec tests.
+
+Command-Started Events
+``````````````````````
+
+See: `Command-Started Events <../../transactions/tests#command-started-events>`_
+in the Transactions spec test suite for instructions on asserting
+command-started events.
+
+Prose Tests
+===========
+
+Callback Raises a Custom Error
+``````````````````````````````
+
+Write a callback that raises a custom exception or error that does not include
+either UnknownTransactionCommitResult or TransientTransactionError error labels.
+Execute this callback using ``withTransaction`` and assert that the callback's
+error bypasses any retry logic within ``withTransaction`` and is propagated to
+the caller of ``withTransaction``.
+
+Callback Returns a Value
+````````````````````````
+
+Write a callback that returns a custom value (e.g. boolean, string, object).
+Execute this callback using ``withTransaction`` and assert that the callback's
+return value is propagated to the caller of ``withTransaction``.
+
+Retry Timeout is Enforced
+`````````````````````````
+
+Drivers should test that ``withTransaction`` enforces a non-configurable timeout
+before retrying both commits and entire transactions. Specifically, three cases
+should be checked:
+
+ * If the callback raises an error with the TransientTransactionError label and
+   the retry timeout has been exceeded, ``withTransaction`` should propagate the
+   error to its caller.
+ * If committing raises an error with the UnknownTransactionCommitResult label,
+   the error is not a write concern timeout, and the retry timeout has been
+   exceeded, ``withTransaction`` should propagate the error to its caller.
+ * If committing raises an error with the TransientTransactionError label and
+   the retry timeout has been exceeded, ``withTransaction`` should propagate the
+   error to its caller. This case may occur if the commit was internally retried
+   against a new primary after a failover and the second primary returned a
+   NoSuchTransaction error response.
+
+ If possible, drivers should implement these tests without requiring the test
+ runner to block for the full duration of the retry timeout. This might be done
+ by internally modifying the timeout value used by ``withTransaction`` with some
+ private API or using a mock timer.
+
+Changelog
+=========
+
+:2019-03-01: Add top-level ``runOn`` field to denote server version and/or
+             topology requirements requirements for the test file. Removes the
+             ``minServerVersion`` top-level field, which is now expressed within
+             ``runOn`` elements.
+
+             Add test-level ``useMultipleMongoses`` field.