diff --git a/docs/source/reference/changelog.rst b/docs/source/reference/changelog.rst index 8e5e7d08..00b73fa0 100644 --- a/docs/source/reference/changelog.rst +++ b/docs/source/reference/changelog.rst @@ -5,6 +5,8 @@ Changelog 0.22.0 (UNRELEASED) =================== - Output a proper error message when an invalid ``asyncio_mode`` is selected. +- Extend warning message about unclosed event loops with additional possible cause. + `#531 `_ 0.21.0 (2023-03-19) =================== diff --git a/docs/source/reference/fixtures.rst b/docs/source/reference/fixtures.rst index fdd3e034..adcc092d 100644 --- a/docs/source/reference/fixtures.rst +++ b/docs/source/reference/fixtures.rst @@ -2,8 +2,8 @@ Fixtures ======== -``event_loop`` -============== +event_loop +========== Creates a new asyncio event loop based on the current event loop policy. The new loop is available as the return value of this fixture or via `asyncio.get_running_loop `__. The event loop is closed when the fixture scope ends. The fixture scope defaults @@ -25,25 +25,30 @@ fixture scope, for example: .. code-block:: python - @pytest.fixture(scope="session") + @pytest.fixture(scope="module") def event_loop(): policy = asyncio.get_event_loop_policy() loop = policy.new_event_loop() yield loop loop.close() +When defining multiple ``event_loop`` fixtures, you should ensure that their scopes don't overlap. +Each of the fixtures replace the running event loop, potentially without proper clean up. +This will emit a warning and likely lead to errors in your tests suite. +You can manually check for overlapping ``event_loop`` fixtures by running pytest with the ``--setup-show`` option. + If you need to change the type of the event loop, prefer setting a custom event loop policy over redefining the ``event_loop`` fixture. If the ``pytest.mark.asyncio`` decorator is applied to a test function, the ``event_loop`` fixture will be requested automatically by the test function. -``unused_tcp_port`` -=================== +unused_tcp_port +=============== Finds and yields a single unused TCP port on the localhost interface. Useful for binding temporary test servers. -``unused_tcp_port_factory`` -=========================== +unused_tcp_port_factory +======================= A callable which returns a different unused TCP port each invocation. Useful when several unused TCP ports are required in a test. @@ -53,6 +58,6 @@ when several unused TCP ports are required in a test. port1, port2 = unused_tcp_port_factory(), unused_tcp_port_factory() ... -``unused_udp_port`` and ``unused_udp_port_factory`` -=================================================== +unused_udp_port and unused_udp_port_factory +=========================================== Works just like their TCP counterparts but returns unused UDP ports. diff --git a/pytest_asyncio/plugin.py b/pytest_asyncio/plugin.py index b7c3fcbf..12669791 100644 --- a/pytest_asyncio/plugin.py +++ b/pytest_asyncio/plugin.py @@ -434,7 +434,8 @@ def _add_finalizers(fixturedef: FixtureDef, *finalizers: Callable[[], object]) - library will no longer do so. In order to ensure compatibility with future versions, please make sure that: 1. Any custom "event_loop" fixture properly closes the loop after yielding it - 2. Your code does not modify the event loop in async fixtures or tests + 2. The scopes of your custom "event_loop" fixtures do not overlap + 3. Your code does not modify the event loop in async fixtures or tests """ )