Debian Codegraph @

docs/source/quickstart.rst

raw
1 Quickstart
2 ==========
3
4 Enabling Trio mode and running your first async tests
5 -----------------------------------------------------
6
7 .. note:: If you used `cookiecutter-trio
8 <https://github.com/python-trio/cookiecutter-trio>`__ to set up
9 your project, then pytest-trio and Trio mode are already
10 configured! You can write ``async def test_whatever(): ...`` and it
11 should just work. Feel free to skip to the next section.
12
13 Let's make a temporary directory to work in, and write two trivial
14 tests: one that we expect should pass, and one that we expect should
15 fail::
16
17 # test_example.py
18 import trio
19
20 async def test_sleep():
21 start_time = trio.current_time()
22 await trio.sleep(1)
23 end_time = trio.current_time()
24 assert end_time - start_time >= 1
25
26 async def test_should_fail():
27 assert False
28
29 If we run this under pytest normally, then the tests are skipped and we get
30 a warning explaining how pytest itself does not directly support async def
31 tests. Note that in versions of pytest prior to v4.4.0 the tests end up
32 being reported as passing with other warnings despite not actually having
33 been properly run.
34
35 .. code-block:: none
36
37 $ pytest test_example.py
38 ======================== test session starts =========================
39 platform linux -- Python 3.8.5, pytest-6.0.1, py-1.9.0, pluggy-0.13.1
40 rootdir: /tmp
41 collected 2 items
42
43 test_example.py ss [100%]
44
45 ========================== warnings summary ==========================
46 test_example.py::test_sleep
47 test_example.py::test_should_fail
48 .../_pytest/python.py:169: PytestUnhandledCoroutineWarning: async
49 def functions are not natively supported and have been skipped.
50 You need to install a suitable plugin for your async framework, for
51 example:
52 - pytest-asyncio
53 - pytest-trio
54 - pytest-tornasync
55 - pytest-twisted
56 warnings.warn(PytestUnhandledCoroutineWarning(msg.format(nodeid)))
57
58 -- Docs: https://docs.pytest.org/en/stable/warnings.html
59 =================== 2 skipped, 2 warnings in 0.26s ===================
60
61 Here's the fix:
62
63 1. Install pytest-trio: ``pip install pytest-trio``
64
65 2. In your project root, create a file called ``pytest.ini`` with
66 contents:
67
68 .. code-block:: none
69
70 [pytest]
71 trio_mode = true
72
73 And we're done! Let's try running pytest again:
74
75 .. code-block:: none
76
77 $ pip install pytest-trio
78
79 $ cat <<EOF >pytest.ini
80 [pytest]
81 trio_mode = true
82 EOF
83
84 $ pytest test_example.py
85 ======================== test session starts =========================
86 platform linux -- Python 3.8.5, pytest-6.0.1, py-1.9.0, pluggy-0.13.1
87 rootdir: /tmp, configfile: pytest.ini
88 plugins: trio-0.6.0
89 collected 2 items
90
91 test_example.py .F [100%]
92
93 ============================== FAILURES ==============================
94 __________________________ test_should_fail __________________________
95
96 async def test_should_fail():
97 > assert False
98 E assert False
99
100 test_example.py:11: AssertionError
101 ====================== short test summary info =======================
102 FAILED test_example.py::test_should_fail - assert False
103 ==================== 1 failed, 1 passed in 1.23s =====================
104
105 Notice that now it says ``plugins: trio``, which means that
106 pytest-trio is installed, and the results make sense: the good test
107 passed, the bad test failed, no warnings, and it took just over 1
108 second, like we'd expect.
109
110
111 Trio's magic autojump clock
112 ---------------------------
113
114 Tests involving time are often slow and flaky. But we can
115 fix that. Just add the ``autojump_clock`` fixture to your test, and
116 it will run in a mode where Trio's clock is virtualized and
117 deterministic. Essentially, the clock doesn't move, except that whenever all
118 tasks are blocked waiting, it jumps forward until the next time when
119 something will happen::
120
121 # Notice the 'autojump_clock' argument: that's all it takes!
122 async def test_sleep_efficiently_and_reliably(autojump_clock):
123 start_time = trio.current_time()
124 await trio.sleep(1)
125 end_time = trio.current_time()
126 assert end_time - start_time == 1
127
128 In the version of this test we saw before that used real time, at the
129 end we had to use a ``>=`` comparison, in order to account for
130 scheduler jitter and so forth. If there were a bug that caused
131 :func:`trio.sleep` to take 10 seconds, our test wouldn't have noticed.
132 But now we're using virtual time, so the call to ``await
133 trio.sleep(1)`` takes *exactly* 1 virtual second, and the ``==`` test
134 will pass every time. Before, we had to wait around for the test to
135 complete; now, it completes essentially instantaneously. (Try it!)
136 And, while here our example is super simple, its integration with
137 Trio's core scheduling logic allows this to work for arbitrarily
138 complex programs (as long as they aren't interacting with the outside
139 world).
140
141
142 Async fixtures
143 --------------
144
145 We can write async fixtures::
146
147 @pytest.fixture
148 async def db_connection():
149 return await some_async_db_library.connect(...)
150
151 async def test_example(db_connection):
152 await db_connection.execute("SELECT * FROM ...")
153
154 If you need to run teardown code, you can use ``yield``, just like a
155 regular pytest fixture::
156
157 # DB connection that wraps each test in a transaction and rolls it
158 # back afterwards
159 @pytest.fixture
160 async def rollback_db_connection():
161 # Setup code
162 connection = await some_async_db_library.connect(...)
163 await connection.execute("START TRANSACTION")
164
165 # The value of this fixture
166 yield connection
167
168 # Teardown code, executed after the test is done
169 await connection.execute("ROLLBACK")
170
171
172 .. _server-fixture-example:
173
174 Running a background server from a fixture
175 ------------------------------------------
176
177 Here's some code to implement an echo server. It's supposed to take in
178 arbitrary data, and then send it back out again::
179
180 async def echo_server_handler(stream):
181 while True:
182 data = await stream.receive_some(1000)
183 if not data:
184 break
185 await stream.send_all(data)
186
187 # Usage: await trio.serve_tcp(echo_server_handler, ...)
188
189 Now we need to test it, to make sure it's working correctly. In fact,
190 since this is such complicated and sophisticated code, we're going to
191 write lots of tests for it. And they'll all follow the same basic
192 pattern: we'll start the echo server running in a background task,
193 then connect to it, send it some test data, and see how it responds.
194 Here's a first attempt::
195
196 # Let's cross our fingers and hope no-one else is using this port...
197 PORT = 14923
198
199 # Don't copy this -- we can do better
200 async def test_attempt_1():
201 async with trio.open_nursery() as nursery:
202 # Start server running in the background
203 nursery.start_soon(
204 partial(trio.serve_tcp, echo_server_handler, port=PORT)
205 )
206
207 # Connect to the server.
208 echo_client = await trio.open_tcp_stream("127.0.0.1", PORT)
209 # Send some test data, and check that it gets echoed back
210 async with echo_client:
211 for test_byte in [b"a", b"b", b"c"]:
212 await echo_client.send_all(test_byte)
213 assert await echo_client.receive_some(1) == test_byte
214
215 This will mostly work, but it has a few problems. The most obvious one
216 is that when we run it, even if everything works perfectly, it will
217 hang at the end of the test - we never shut down the server, so the
218 nursery block will wait forever for it to exit.
219
220 To avoid this, we should cancel the nursery at the end of the test:
221
222 .. code-block:: python3
223 :emphasize-lines: 7,20,21
224
225 # Let's cross our fingers and hope no-one else is using this port...
226 PORT = 14923
227
228 # Don't copy this -- we can do better
229 async def test_attempt_2():
230 async with trio.open_nursery() as nursery:
231 try:
232 # Start server running in the background
233 nursery.start_soon(
234 partial(trio.serve_tcp, echo_server_handler, port=PORT)
235 )
236
237 # Connect to the server.
238 echo_client = await trio.open_tcp_stream("127.0.0.1", PORT)
239 # Send some test data, and check that it gets echoed back
240 async with echo_client:
241 for test_byte in [b"a", b"b", b"c"]:
242 await echo_client.send_all(test_byte)
243 assert await echo_client.receive_some(1) == test_byte
244 finally:
245 nursery.cancel_scope.cancel()
246
247 In fact, this pattern is *so* common, that pytest-trio provides a
248 handy :data:`nursery` fixture to let you skip the boilerplate. Just
249 add ``nursery`` to your test function arguments, and pytest-trio will
250 open a nursery, pass it in to your function, and then cancel it for
251 you afterwards:
252
253 .. code-block:: python3
254 :emphasize-lines: 5
255
256 # Let's cross our fingers and hope no-one else is using this port...
257 PORT = 14923
258
259 # Don't copy this -- we can do better
260 async def test_attempt_3(nursery):
261 # Start server running in the background
262 nursery.start_soon(
263 partial(trio.serve_tcp, echo_server_handler, port=PORT)
264 )
265
266 # Connect to the server.
267 echo_client = await trio.open_tcp_stream("127.0.0.1", PORT)
268 # Send some test data, and check that it gets echoed back
269 async with echo_client:
270 for test_byte in [b"a", b"b", b"c"]:
271 await echo_client.send_all(test_byte)
272 assert await echo_client.receive_some(1) == test_byte
273
274 Next problem: we have a race condition. We spawn a background task to
275 call ``serve_tcp``, and then immediately try to connect to that
276 server. Sometimes this will work fine. But it takes a little while for
277 the server to start up and be ready to accept connections - so other
278 times, randomly, our connection attempt will happen too quickly, and
279 error out. After all - ``nursery.start_soon`` only promises that the
280 task will be started *soon*, not that it has actually happened. So this
281 test will be flaky, and flaky tests are the worst.
282
283 Fortunately, Trio makes this easy to solve, by switching to using
284 ``await nursery.start(...)``. You can `read its docs for full details
285 <https://trio.readthedocs.io/en/latest/reference-core.html#trio.The%20nursery%20interface.start>`__,
286 but basically the idea is that both ``nursery.start_soon(...)`` and
287 ``await nursery.start(...)`` create background tasks, but only
288 ``start`` waits for the new task to finish getting itself set up. This
289 requires some cooperation from the background task: it has to notify
290 ``nursery.start`` when it's ready. Fortunately, :func:`trio.serve_tcp`
291 already knows how to cooperate with ``nursery.start``, so we can
292 write:
293
294 .. code-block:: python3
295 :emphasize-lines: 6-10
296
297 # Let's cross our fingers and hope no-one else is using this port...
298 PORT = 14923
299
300 # Don't copy this -- we can do better
301 async def test_attempt_4(nursery):
302 # Start server running in the background
303 # AND wait for it to finish starting up before continuing
304 await nursery.start(
305 partial(trio.serve_tcp, echo_server_handler, port=PORT)
306 )
307
308 # Connect to the server
309 echo_client = await trio.open_tcp_stream("127.0.0.1", PORT)
310 async with echo_client:
311 for test_byte in [b"a", b"b", b"c"]:
312 await echo_client.send_all(test_byte)
313 assert await echo_client.receive_some(1) == test_byte
314
315 That solves our race condition. Next issue: hardcoding the port number
316 like this is a bad idea, because port numbers are a machine-wide
317 resource, so if we're unlucky some other program might already be
318 using it. What we really want to do is to tell :func:`~trio.serve_tcp`
319 to pick a random port that no-one else is using. It turns out that
320 this is easy: if you request port 0, then the operating system will
321 pick an unused one for you automatically. Problem solved!
322
323 But wait... if the operating system is picking the port for us, how do
324 we know which one it picked, so we can connect to it later?
325
326 Well, there's no way to predict the port ahead of time. But after
327 :func:`~trio.serve_tcp` has opened a port, it can check and see what
328 it got. So we need some way to pass this data back out of
329 :func:`~trio.serve_tcp`. Fortunately, ``nursery.start`` handles this
330 too: it lets the task pass out a piece of data after it has started. And
331 it just so happens that what :func:`~trio.serve_tcp` passes out is a
332 list of :class:`~trio.SocketListener` objects. And there's a handy
333 function called :func:`trio.testing.open_stream_to_socket_listener`
334 that can take a :class:`~trio.SocketListener` and make a connection to
335 it.
336
337 Putting it all together:
338
339 .. code-block:: python3
340 :emphasize-lines: 1,8,13-16
341
342 from trio.testing import open_stream_to_socket_listener
343
344 # Don't copy this -- it finally works, but we can still do better!
345 async def test_attempt_5(nursery):
346 # Start server running in the background
347 # AND wait for it to finish starting up before continuing
348 # AND find out where it's actually listening
349 listeners = await nursery.start(
350 partial(trio.serve_tcp, echo_server_handler, port=0)
351 )
352
353 # Connect to the server.
354 # There might be multiple listeners (example: IPv4 and
355 # IPv6), but we don't care which one we connect to, so we
356 # just use the first.
357 echo_client = await open_stream_to_socket_listener(listeners[0])
358 async with echo_client:
359 for test_byte in [b"a", b"b", b"c"]:
360 await echo_client.send_all(test_byte)
361 assert await echo_client.receive_some(1) == test_byte
362
363 Now, this works - but there's still a lot of boilerplate. Remember, we
364 need to write lots of tests for this server, and we don't want to have
365 to copy-paste all that stuff into every test. Let's factor out the
366 setup into a fixture::
367
368 @pytest.fixture
369 async def echo_client(nursery):
370 listeners = await nursery.start(
371 partial(trio.serve_tcp, echo_server_handler, port=0)
372 )
373 echo_client = await open_stream_to_socket_listener(listeners[0])
374 async with echo_client:
375 yield echo_client
376
377 And now in tests, all we have to do is request the ``echo_client``
378 fixture, and we get a background server and a client stream connected
379 to it. So here's our complete, final version::
380
381 # Final version -- copy this!
382 from functools import partial
383 import pytest
384 import trio
385 from trio.testing import open_stream_to_socket_listener
386
387 # The code being tested:
388 async def echo_server_handler(stream):
389 while True:
390 data = await stream.receive_some(1000)
391 if not data:
392 break
393 await stream.send_all(data)
394
395 # The fixture:
396 @pytest.fixture
397 async def echo_client(nursery):
398 listeners = await nursery.start(
399 partial(trio.serve_tcp, echo_server_handler, port=0)
400 )
401 echo_client = await open_stream_to_socket_listener(listeners[0])
402 async with echo_client:
403 yield echo_client
404
405 # A test using the fixture:
406 async def test_final(echo_client):
407 for test_byte in [b"a", b"b", b"c"]:
408 await echo_client.send_all(test_byte)
409 assert await echo_client.receive_some(1) == test_byte
410
411 No hangs, no race conditions, simple, clean, and reusable.