2.8 KiB
(contributing-pytest-asyncio)=
The Pytest-Asyncio Plugin
When testing the various JupyterHub components and their various implementations, it sometimes becomes necessary to have a running instance of JupyterHub to test against.
The app fixture mocks a JupyterHub application for use in testing by:
- enabling ssl if internal certificates are available
- creating an instance of MockHub using any provided configurations as arguments
- initializing the mocked instance
- starting the mocked instance
- finally, a registered finalizer function performs a cleanup and stops the mocked instance
The JupyterHub test suite uses the pytest-asyncio plugin that handles event-loop integration in Tornado applications. This allows for the use of top-level awaits when calling async functions or fixtures during testing. All test functions and fixtures labelled as async will run on the same event loop.
With the introduction of [top-level awaits](https://piccolo-orm.com/blog/top-level-await-in-python/), the use of the `io_loop` fixture of the [pytest-tornado plugin](https://www.tornadoweb.org/en/stable/ioloop.html) is no longer necessary. It was initially used to call coroutines. With the upgrades made to `pytest-asyncio`, this usage is now deprecated. It is now, only utilized within the JupyterHub test suite to ensure complete cleanup of resources used during testing such as open file descriptors. This is demonstrated in this [pull request](https://github.com/jupyterhub/jupyterhub/pull/4332).
More information is provided below.
One of the general goals of the JupyterHub Pytest Plugin project is to ensure the MockHub cleanup fully closes and stops all utilized resources during testing so the use of the io_loop fixture for teardown is not necessary. This was highlighted in this issue
For more information on asyncio and event-loops, here are some resources: