1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
|
.. role:: javascript(code)
:language: javascript
========================================
Connection Monitoring and Pooling (CMAP)
========================================
.. contents::
--------
Introduction
============
The YAML and JSON files in this directory are platform-independent tests that
drivers can use to prove their conformance to the Connection Monitoring and Pooling (CMAP) Spec.
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.
Common Test Format
==================
Each YAML file has the following keys:
- ``version``: A version number indicating the expected format of the spec tests (current version = 1)
- ``style``: A string indicating what style of tests this file contains. Currently ``unit`` is the only valid value
- ``description``: A text description of what the test is meant to assert
Unit Test Format:
=================
All Unit Tests have some of the following fields:
- ``poolOptions``: if present, connection pool options to use when creating a pool
- ``operations``: A list of operations to perform. All operations support the following fields:
- ``name``: A string describing which operation to issue.
- ``thread``: The name of the thread in which to run this operation. If not specified, runs in the default thread
- ``error``: Indicates that the main thread is expected to error during this test. An error may include of the following fields:
- ``type``: the type of error emitted
- ``message``: the message associated with that error
- ``address``: Address of pool emitting error
- ``events``: An array of all connection monitoring events expected to occur while running ``operations``. An event may contain any of the following fields
- ``type``: The type of event emitted
- ``address``: The address of the pool emitting the event
- ``connectionId``: The id of a connection associated with the event
- ``options``: Options used to create the pool
- ``reason``: A reason giving mroe information on why the event was emitted
- ``ignore``: An array of event names to ignore
Valid Unit Test Operations are the following:
- ``start(target)``: Starts a new thread named ``target``
- ``target``: The name of the new thread to start
- ``wait(ms)``: Sleep the current thread for ``ms`` milliseconds
- ``ms``: The number of milliseconds to sleep the current thread for
- ``waitForThread(target)``: wait for thread ``target`` to finish executing. Propagate any errors to the main thread.
- ``target``: The name of the thread to wait for.
- ``waitForEvent(event, count)``: block the current thread until ``event`` has occurred ``count`` times
- ``event``: The name of the event
- ``count``: The number of times the event must occur (counting from the start of the test)
- ``label = pool.checkOut()``: call ``checkOut`` on pool, returning the checked out connection
- ``label``: If specified, associate this label with the returned connection, so that it may be referenced in later operations
- ``pool.checkIn(connection)``: call ``checkIn`` on pool
- ``connection``: A string label identifying which connection to check in. Should be a label that was previously set with ``checkOut``
- ``pool.clear()``: call ``clear`` on Pool
- ``pool.close()``: call ``close`` on Pool
Spec Test Match Function
========================
The definition of MATCH or MATCHES in the Spec Test Runner is as follows:
- MATCH takes two values, ``expected`` and ``actual``
- Notation is "Assert [actual] MATCHES [expected]
- Assertion passes if ``expected`` is a subset of ``actual``, with the values ``42`` and ``"42"`` acting as placeholders for "any value"
Pseudocode implementation of ``actual`` MATCHES ``expected``:
::
If expected is "42" or 42:
Assert that actual exists (is not null or undefined)
Else:
Assert that actual is of the same JSON type as expected
If expected is a JSON array:
For every idx/value in expected:
Assert that actual[idx] MATCHES value
Else if expected is a JSON object:
For every key/value in expected
Assert that actual[key] MATCHES value
Else:
Assert that expected equals actual
Unit Test Runner:
=================
For the unit tests, the behavior of a Connection is irrelevant beyond the need to asserting ``connection.id``. Drivers MAY use a mock connection class for testing the pool behavior in unit tests
For each YAML file with ``style: unit``:
- Create a Pool ``pool``, subscribe and capture any Connection Monitoring events emitted in order.
- If ``poolOptions`` is specified, use those options to initialize both pools
- The returned pool must have an ``address`` set as a string value.
- Execute each ``operation`` in ``operations``
- If a ``thread`` is specified, execute in that corresponding thread. Otherwise, execute in the main thread.
- Wait for the main thread to finish executing all of its operations
- If ``error`` is presented
- Assert that an actual error ``actualError`` was thrown by the main thread
- Assert that ``actualError`` MATCHES ``error``
- Else:
- Assert that no errors were thrown by the main thread
- calculate ``actualEvents`` as every Connection Event emitted whose ``type`` is not in ``ignore``
- if ``events`` is not empty, then for every ``idx``/``expectedEvent`` in ``events``
- Assert that ``actualEvents[idx]`` exists
- Assert that ``actualEvents[idx]`` MATCHES ``expectedEvent``
It is important to note that the ``ignore`` list is used for calculating ``actualEvents``, but is NOT used for the ``waitForEvent`` command
Prose Tests
===========
The following tests have not yet been automated, but MUST still be tested
#. All ConnectionPoolOptions MUST be specified at the MongoClient level
#. All ConnectionPoolOptions MUST be the same for all pools created by a MongoClient
#. A user MUST be able to specify all ConnectionPoolOptions via a URI string
#. A user MUST be able to subscribe to Connection Monitoring Events in a manner idiomatic to their language and driver
#. When a check out attempt fails because connection set up throws an error,
assert that a ConnectionCheckOutFailedEvent with reason="connectionError" is emitted.
|
