1===================
2Max Staleness Tests
3===================
4
5This directory contains platform-independent tests that drivers can use
6to prove their conformance to the Max Staleness Spec. The tests
7are provided in both YAML and JSON formats, and drivers may test against
8whichever format is more convenient for them.
9
10Test Format and Use
11-------------------
12
13YAML files contain the following setup for each test:
14
15- ``heartbeatFrequencyMS``: optional int
16
17- ``topology_description``: the state of a mocked cluster
18
19 - ``type``: the TopologyType
20
21 - ``servers``: a list of ServerDescriptions, each with:
22
23 - ``address``: a "host:port"
24
25 - ``type``: a ServerType
26
27 - ``avg_rtt_ms``: average round trip time in milliseconds [1]_
28
29 - ``lastWrite``: subdocument
30
31 - ``lastWriteDate``: nonzero int64, milliseconds since some past time
32
33 - ``maxWireVersion``: an int
34
35 - ``lastUpdateTime``: milliseconds since the Unix epoch
36
37- ``read_preference``: a read preference document
38
39For each test, create a MongoClient.
40Configure it with the heartbeatFrequencyMS specified by the test,
41or accept the driver's default heartbeatFrequencyMS if the test omits this field.
42
43(Single-threaded and multi-threaded clients now make heartbeatFrequencyMS configurable.
44This is a change in Server Discovery and Monitoring to support maxStalenessSeconds.
45Before, multi-threaded clients were allowed to make it configurable or not.)
46
47For each test, create a new TopologyDescription object initialized with the
48values from ``topology_description``. Initialize ServerDescriptions from the
49provided data. Create a ReadPreference object initialized with the values
50from ``read_preference``. Select servers that match the ReadPreference.
51
52Each test specifies that it expects an error, or specifies two sets of servers:
53
54- ``error: true``
55- ``suitable_servers``: the set of servers in the TopologyDescription
56 that are suitable for the ReadPreference, without taking ``avg_rtt_ms``
57 into account.
58- ``in_latency_window``: the set of suitable servers whose round trip time
59 qualifies them according to the default latency threshold of 15ms.
60 In each test there is one server in the latency window, to ensure
61 tests pass or fail deterministically.
62
63If the file contains ``error: true``, drivers MUST test that they throw an
64error during server selection due to an invalid read preference. For other
65files, drivers MUST test that they correctly select the set of servers in
66``in_latency_window``.
67
68Drivers MAY also test that before filtration by latency, they select the
69specified set of "suitable" servers.
70
71.. [1] ``avg_rtt_ms`` is included merely for consistency with
72 Server Selection tests. It is not significant in Max Staleness tests.
View as plain text