Mention scoping limitation for event loop fixtures

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 <https://github.com/pytest-dev/pytest-asyncio/issues/531>`_
 
 0.21.0 (2023-03-19)
 ===================

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 <https://docs.python.org/3/library/asyncio-eventloop.html#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.

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
     """
 )