===================================== 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 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.