1======================
2Server Selection Tests
3======================
4
5This directory contains platform-independent tests that drivers can use
6to prove their conformance to the Server Selection spec. The tests
7are provided in both YAML and JSON formats, and drivers may test against
8whichever format is more convenient for them.
9
10Version
11-------
12
13Specifications have no version scheme.
14They are not tied to a MongoDB server version,
15and it is our intention that each specification moves from "draft" to "final"
16with no further versions; it is superseded by a future spec, not revised.
17
18However, implementers must have stable sets of tests to target.
19As test files evolve they will be occasionally tagged like
20"server-selection-tests-2015-01-04", until the spec is final.
21
22Test Format and Use
23-------------------
24
25There are two types of tests for the server selection spec, tests for
26round trip time (RTT) calculation, and tests for server selection logic.
27
28Drivers should be able to test their server selection logic
29without any network I/O, by parsing topology descriptions and read preference
30documents from the test files and passing them into driver code. Parts of the
31server selection code may need to be mocked or subclassed to achieve this.
32
33RTT Calculation Tests
34>>>>>>>>>>>>>>>>>>>>>
35
36These YAML files contain the following keys:
37
38- ``avg_rtt_ms``: a server's previous average RTT, in milliseconds
39- ``new_rtt_ms``: a new RTT value for this server, in milliseconds
40- ``new_avg_rtt``: this server's newly-calculated average RTT, in milliseconds
41
42For each file, create a server description object initialized with ``avg_rtt_ms``.
43Parse ``new_rtt_ms``, and ensure that the new RTT value for the mocked server
44description is equal to ``new_avg_rtt``.
45
46If driver architecture doesn't easily allow construction of server description
47objects in isolation, unit testing the EWMA algorithm using these inputs
48and expected outputs is acceptable.
49
50Server Selection Logic Tests
51>>>>>>>>>>>>>>>>>>>>>>>>>>>>
52
53These YAML files contain the following setup for each test:
54
55- ``topology_description``: the state of a mocked cluster
56- ``operation``: the kind of operation to perform, either read or write
57- ``read_preference``: a read preference document
58
59For each file, create a new TopologyDescription object initialized with the values
60from ``topology_description``. Create a ReadPreference object initialized with the
61values from ``read_preference``.
62
63Together with "operation", pass the newly-created TopologyDescription and ReadPreference
64to server selection, and ensure that it selects the correct subset of servers from
65the TopologyDescription. Each YAML file contains a key for these stages of server selection:
66
67- ``suitable_servers``: the set of servers in topology_description that are suitable, as
68 per the Server Selection spec, given operation and read_preference
69- ``in_latency_window``: the set of suitable_servers that fall within the latency window
70
71Drivers implementing server selection MUST test that their implementation
72correctly returns the set of servers in ``in_latency_window``. Drivers SHOULD also test
73against ``suitable_servers`` if possible.
View as plain text