README.rst

Driver Session Tests

Contents

• Introduction
• Test Format
  • Special Test Operations
    • assertDifferentLsidOnLastTwoCommands
    • assertSameLsidOnLastTwoCommands
    • assertSessionDirty
    • assertSessionNotDirty
• Snapshot session tests
  • Prose tests
• Changelog

---

Introduction

The YAML and JSON files in the legacy and unified sub-directories are platform-independent tests that drivers can use to prove their conformance to the Driver Sessions Spec. They are designed with the intention of sharing most test-runner code with the Transactions Spec tests.. Tests in the unified directory are written using the Unified Test Format.

Several prose tests, which are not easily expressed in YAML, are also presented in the Driver Sessions Spec. Those tests will need to be manually implemented by each driver.

Test Format

The same as the Transactions Spec Test format.

Special Test Operations

Certain operations that appear in the "operations" array do not correspond to API methods but instead represent special test operations. Such operations are defined on the "testRunner" object and are documented in the Transactions Spec Test. Additional, session test specific operations are documented here:

assertDifferentLsidOnLastTwoCommands

The "assertDifferentLsidOnLastTwoCommands" operation instructs the test runner to assert that the last two command started events from the test's MongoClient have different "lsid" fields. This assertion is used to ensure that dirty server sessions are discarded from the pool:

- name: assertDifferentLsidOnLastTwoCommands
  object: testRunner

assertSameLsidOnLastTwoCommands

The "assertSameLsidOnLastTwoCommands" operation instructs the test runner to assert that the last two command started events from the test's MongoClient have the same "lsid" field. This assertion is used to ensure that non-dirty server sessions are not discarded from the pool:

- name: assertSameLsidOnLastTwoCommands
  object: testRunner

assertSessionDirty

The "assertSessionDirty" operation instructs the test runner to assert that the given session is marked dirty:

- name: assertSessionDirty
  object: testRunner
  arguments:
    session: session0

assertSessionNotDirty

The "assertSessionNotDirty" operation instructs the test runner to assert that the given session is not marked dirty:

- name: assertSessionNotDirty
  object: testRunner
  arguments:
    session: session0

Snapshot session tests

Snapshot sessions tests require server of version 5.0 or higher and replica set or a sharded cluster deployment. Default snapshot history window on the server is 5 minutes. Running the test in debug mode, or in any other slow configuration may lead to SnapshotTooOld errors. Drivers can work around this issue by increasing the server's minSnapshotHistoryWindowInSeconds parameter, for example:

client.admin.command('setParameter', 1, minSnapshotHistoryWindowInSeconds=60)

Prose tests

• Setting both snapshot and causalConsistency is not allowed

  • client.startSession(snapshot = true, causalConsistency = true)
  • Assert that an error was raised by driver

Changelog

2019-05-15:	Initial version.
2021-06-15:	Added snapshot-session tests. Introduced legacy and unified folders.