[feat!] Replaced the asyncio_event_loop marker with an optional "scope" kwarg to the asyncio mark.

Signed-off-by: Michael Seifert <[email protected]>

Author: seifertm

docs/source/reference/changelog.rst

@@ -2,8 +2,18 @@
 Changelog
 =========
 
+0.23.0 (UNRELEASED)
+===================
+This release is backwards-compatible with v0.21.
+Changes are non-breaking, unless you upgrade from v0.22.
+
+BREAKING: The *asyncio_event_loop* mark has been removed. Class-scoped and module-scoped event loops can be requested
+  via the *scope* keyword argument to the _asyncio_ mark.
+
 0.22.0 (2023-10-31)
 ===================
+This release has been yanked from PyPI due to fundamental issues with the _asyncio_event_loop_ mark.
+
 - Class-scoped and module-scoped event loops can be requested
   via the _asyncio_event_loop_ mark. `#620 <https://github.com/pytest-dev/pytest-asyncio/pull/620>`_
 - Deprecate redefinition of the `event_loop` fixture. `#587 <https://github.com/pytest-dev/pytest-asyncio/issues/531>`_

docs/source/reference/fixtures/event_loop_policy_example.py

@@ -0,0 +1,17 @@
+import asyncio
+
+import pytest
+
+
+class CustomEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+    pass
+
+
+@pytest.fixture(scope="module")
+def event_loop_policy(request):
+    return CustomEventLoopPolicy()
+
+
+@pytest.mark.asyncio(scope="module")
+async def test_uses_custom_event_loop_policy():
+    assert isinstance(asyncio.get_event_loop_policy(), CustomEventLoopPolicy)

docs/source/reference/fixtures/event_loop_policy_parametrized_example.py

@@ -0,0 +1,23 @@
+import asyncio
+from asyncio import DefaultEventLoopPolicy
+
+import pytest
+
+
+class CustomEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
+    pass
+
+
+@pytest.fixture(
+    params=(
+        DefaultEventLoopPolicy(),
+        CustomEventLoopPolicy(),
+    ),
+)
+def event_loop_policy(request):
+    return request.param
+
+
+@pytest.mark.asyncio
+async def test_uses_custom_event_loop_policy():
+    assert isinstance(asyncio.get_event_loop_policy(), DefaultEventLoopPolicy)

docs/source/reference/fixtures/index.rst

@@ -22,6 +22,23 @@ If you need to change the type of the event loop, prefer setting a custom event
 If the ``pytest.mark.asyncio`` decorator is applied to a test function, the ``event_loop``
 fixture will be requested automatically by the test function.
 
+event_loop_policy
+=================
+Returns the event loop policy used to create asyncio event loops.
+The default return value is *asyncio.get_event_loop_policy().*
+
+This fixture can be overridden when a different event loop policy should be used.
+
+.. include:: event_loop_policy_example.py
+    :code: python
+
+Multiple policies can be provided via fixture parameters.
+All tests to which the fixture is applied are run once for each fixture parameter.
+The following example runs the test with different event loop policies.
+
+.. include:: event_loop_policy_parametrized_example.py
+    :code: python
+
 unused_tcp_port
 ===============
 Finds and yields a single unused TCP port on the localhost interface. Useful for

docs/source/reference/markers/class_scoped_loop_auto_mode_example.py

@@ -3,14 +3,12 @@
 import pytest
 
 
-@pytest.mark.asyncio_event_loop
+@pytest.mark.asyncio(scope="class")
 class TestClassScopedLoop:
     loop: asyncio.AbstractEventLoop
 
-    @pytest.mark.asyncio
     async def test_remember_loop(self):
         TestClassScopedLoop.loop = asyncio.get_running_loop()
 
-    @pytest.mark.asyncio
     async def test_this_runs_in_same_loop(self):
         assert asyncio.get_running_loop() is TestClassScopedLoop.loop

docs/source/reference/markers/class_scoped_loop_custom_policy_strict_mode_example.py

@@ -5,14 +5,13 @@
 import pytest_asyncio
 
 
-@pytest.mark.asyncio_event_loop
+@pytest.mark.asyncio(scope="class")
 class TestClassScopedLoop:
     loop: asyncio.AbstractEventLoop
 
     @pytest_asyncio.fixture
     async def my_fixture(self):
         TestClassScopedLoop.loop = asyncio.get_running_loop()
 
-    @pytest.mark.asyncio
     async def test_runs_is_same_loop_as_fixture(self, my_fixture):
         assert asyncio.get_running_loop() is TestClassScopedLoop.loop

docs/source/reference/markers/class_scoped_loop_strict_mode_example.py

@@ -0,0 +1,10 @@
+import asyncio
+
+import pytest
+
+# Marks all test coroutines in this module
+pytestmark = pytest.mark.asyncio
+
+
+async def test_runs_in_asyncio_event_loop():
+    assert asyncio.get_running_loop()

docs/source/reference/markers/class_scoped_loop_with_fixture_strict_mode_example.py

@@ -0,0 +1,8 @@
+import asyncio
+
+import pytest
+
+
+@pytest.mark.asyncio
+async def test_runs_in_asyncio_event_loop():
+    assert asyncio.get_running_loop()

docs/source/reference/markers/function_scoped_loop_pytestmark_strict_mode_example.py

@@ -4,62 +4,33 @@ Markers
 
 ``pytest.mark.asyncio``
 =======================
-A coroutine or async generator with this marker will be treated as a test function by pytest. The marked function will be executed as an
-asyncio task in the event loop provided by the ``event_loop`` fixture.
+A coroutine or async generator with this marker is treated as a test function by pytest.
+The marked function is executed as an asyncio task in the event loop provided by pytest-asyncio.
 
-In order to make your test code a little more concise, the pytest |pytestmark|_
-feature can be used to mark entire modules or classes with this marker.
-Only test coroutines will be affected (by default, coroutines prefixed by
-``test_``), so, for example, fixtures are safe to define.
-
-.. include:: pytestmark_asyncio_strict_mode_example.py
+.. include:: function_scoped_loop_strict_mode_example.py
     :code: python
 
-In *auto* mode, the ``pytest.mark.asyncio`` marker can be omitted, the marker is added
-automatically to *async* test functions.
-
-
-``pytest.mark.asyncio_event_loop``
-==================================
-Test classes or modules with this mark provide a class-scoped or module-scoped asyncio event loop.
-
-This functionality is orthogonal to the `asyncio` mark.
-That means the presence of this mark does not imply that async test functions inside the class or module are collected by pytest-asyncio.
-The collection happens automatically in `auto` mode.
-However, if you're using strict mode, you still have to apply the `asyncio` mark to your async test functions.
+Multiple async tests in a single class or module can be marked using |pytestmark|_.
 
-The following code example uses the `asyncio_event_loop` mark to provide a shared event loop for all tests in `TestClassScopedLoop`:
-
-.. include:: class_scoped_loop_strict_mode_example.py
+.. include:: function_scoped_loop_pytestmark_strict_mode_example.py
     :code: python
 
-In *auto* mode, the ``pytest.mark.asyncio`` marker can be omitted:
-
-.. include:: class_scoped_loop_auto_mode_example.py
-    :code: python
+The ``pytest.mark.asyncio`` marker can be omitted entirely in *auto* mode, where the *asyncio* marker is added automatically to *async* test functions.
 
-Similarly, a module-scoped loop is provided when adding the `asyncio_event_loop` mark to the module:
+By default, each test runs in it's own asyncio event loop.
+Multiple tests can share the same event loop by providing a *scope* keyword argument to the *asyncio* mark.
+The following code example provides a shared event loop for all tests in `TestClassScopedLoop`:
 
-.. include:: module_scoped_loop_auto_mode_example.py
-    :code: python
-
-The `asyncio_event_loop` mark supports an optional `policy` keyword argument to set the asyncio event loop policy.
-
-.. include:: class_scoped_loop_custom_policy_strict_mode_example.py
+.. include:: class_scoped_loop_strict_mode_example.py
     :code: python
 
 
-The ``policy`` keyword argument may also take an iterable of event loop policies. This causes tests under by the `asyncio_event_loop` mark to be parametrized with different policies:
+Similarly, a module-scoped loop is provided when setting mark's scope to *module:*
 
-.. include:: class_scoped_loop_custom_policies_strict_mode_example.py
+.. include:: module_scoped_loop_strict_mode_example.py
     :code: python
 
-If no explicit policy is provided, the mark will use the loop policy returned by ``asyncio.get_event_loop_policy()``.
-
-Fixtures and tests sharing the same `asyncio_event_loop` mark are executed in the same event loop:
-
-.. include:: class_scoped_loop_with_fixture_strict_mode_example.py
-    :code: python
+The supported scopes are *class*, and *module.*
 
 .. |pytestmark| replace:: ``pytestmark``
 .. _pytestmark: http://doc.pytest.org/en/latest/example/markers.html#marking-whole-classes-or-modules

docs/source/reference/markers/function_scoped_loop_strict_mode_example.py

@@ -2,7 +2,7 @@
 
 import pytest
 
-pytestmark = pytest.mark.asyncio_event_loop
+pytestmark = pytest.mark.asyncio(scope="module")
 
 loop: asyncio.AbstractEventLoop
 

docs/source/reference/markers/index.rst

@@ -26,14 +26,15 @@
 )
 
 import pytest
-from _pytest.mark.structures import get_unpacked_marks
 from pytest import (
+    Class,
     Collector,
     Config,
     FixtureRequest,
     Function,
     Item,
     Metafunc,
+    Module,
     Parser,
     PytestCollectionWarning,
     PytestDeprecationWarning,
@@ -207,11 +208,13 @@ def _preprocess_async_fixtures(
     config = collector.config
     asyncio_mode = _get_asyncio_mode(config)
     fixturemanager = config.pluginmanager.get_plugin("funcmanage")
-    event_loop_fixture_id = "event_loop"
-    for node, mark in collector.iter_markers_with_node("asyncio_event_loop"):
-        event_loop_fixture_id = node.stash.get(_event_loop_fixture_id, None)
-        if event_loop_fixture_id:
-            break
+    marker = collector.get_closest_marker("asyncio")
+    scope = marker.kwargs.get("scope", "function") if marker else "function"
+    if scope == "function":
+        event_loop_fixture_id = "event_loop"
+    else:
+        event_loop_node = _retrieve_scope_root(collector, scope)
+        event_loop_fixture_id = event_loop_node.stash.get(_event_loop_fixture_id, None)
     for fixtures in fixturemanager._arg2fixturedefs.values():
         for fixturedef in fixtures:
             func = fixturedef.func
@@ -548,48 +551,40 @@ def pytest_pycollect_makeitem_convert_async_functions_to_subclass(
 def pytest_collectstart(collector: pytest.Collector):
     if not isinstance(collector, (pytest.Class, pytest.Module)):
         return
-    # pytest.Collector.own_markers is empty at this point,
-    # so we rely on _pytest.mark.structures.get_unpacked_marks
-    marks = get_unpacked_marks(collector.obj, consider_mro=True)
-    for mark in marks:
-        if not mark.name == "asyncio_event_loop":
-            continue
-
-        # There seem to be issues when a fixture is shadowed by another fixture
-        # and both differ in their params.
-        # https://github.com/pytest-dev/pytest/issues/2043
-        # https://github.com/pytest-dev/pytest/issues/11350
-        # As such, we assign a unique name for each event_loop fixture.
-        # The fixture name is stored in the collector's Stash, so it can
-        # be injected when setting up the test
-        event_loop_fixture_id = f"{collector.nodeid}::<event_loop>"
-        collector.stash[_event_loop_fixture_id] = event_loop_fixture_id
-
-        @pytest.fixture(
-            scope="class" if isinstance(collector, pytest.Class) else "module",
-            name=event_loop_fixture_id,
-        )
-        def scoped_event_loop(
-            *args,  # Function needs to accept "cls" when collected by pytest.Class
-            event_loop_policy,
-        ) -> Iterator[asyncio.AbstractEventLoop]:
-            new_loop_policy = event_loop_policy
-            old_loop_policy = asyncio.get_event_loop_policy()
-            old_loop = asyncio.get_event_loop()
-            asyncio.set_event_loop_policy(new_loop_policy)
-            loop = asyncio.new_event_loop()
-            asyncio.set_event_loop(loop)
-            yield loop
-            loop.close()
-            asyncio.set_event_loop_policy(old_loop_policy)
-            asyncio.set_event_loop(old_loop)
-
-        # @pytest.fixture does not register the fixture anywhere, so pytest doesn't
-        # know it exists. We work around this by attaching the fixture function to the
-        # collected Python class, where it will be picked up by pytest.Class.collect()
-        # or pytest.Module.collect(), respectively
-        collector.obj.__pytest_asyncio_scoped_event_loop = scoped_event_loop
-        break
+    # There seem to be issues when a fixture is shadowed by another fixture
+    # and both differ in their params.
+    # https://github.com/pytest-dev/pytest/issues/2043
+    # https://github.com/pytest-dev/pytest/issues/11350
+    # As such, we assign a unique name for each event_loop fixture.
+    # The fixture name is stored in the collector's Stash, so it can
+    # be injected when setting up the test
+    event_loop_fixture_id = f"{collector.nodeid}::<event_loop>"
+    collector.stash[_event_loop_fixture_id] = event_loop_fixture_id
+
+    @pytest.fixture(
+        scope="class" if isinstance(collector, pytest.Class) else "module",
+        name=event_loop_fixture_id,
+    )
+    def scoped_event_loop(
+        *args,  # Function needs to accept "cls" when collected by pytest.Class
+        event_loop_policy,
+    ) -> Iterator[asyncio.AbstractEventLoop]:
+        new_loop_policy = event_loop_policy
+        old_loop_policy = asyncio.get_event_loop_policy()
+        old_loop = asyncio.get_event_loop()
+        asyncio.set_event_loop_policy(new_loop_policy)
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        yield loop
+        loop.close()
+        asyncio.set_event_loop_policy(old_loop_policy)
+        asyncio.set_event_loop(old_loop)
+
+    # @pytest.fixture does not register the fixture anywhere, so pytest doesn't
+    # know it exists. We work around this by attaching the fixture function to the
+    # collected Python class, where it will be picked up by pytest.Class.collect()
+    # or pytest.Module.collect(), respectively
+    collector.obj.__pytest_asyncio_scoped_event_loop = scoped_event_loop
 
 
 def pytest_collection_modifyitems(
@@ -608,7 +603,9 @@ def pytest_collection_modifyitems(
     if _get_asyncio_mode(config) != Mode.AUTO:
         return
     for item in items:
-        if isinstance(item, PytestAsyncioFunction):
+        if isinstance(item, PytestAsyncioFunction) and not item.get_closest_marker(
+            "asyncio"
+        ):
             item.add_marker("asyncio")
 
 
@@ -626,32 +623,34 @@ def pytest_collection_modifyitems(
 
 @pytest.hookimpl(tryfirst=True)
 def pytest_generate_tests(metafunc: Metafunc) -> None:
-    for event_loop_provider_node, _ in metafunc.definition.iter_markers_with_node(
-        "asyncio_event_loop"
-    ):
-        event_loop_fixture_id = event_loop_provider_node.stash.get(
-            _event_loop_fixture_id, None
-        )
-        if event_loop_fixture_id:
-            # This specific fixture name may already be in metafunc.argnames, if this
-            # test indirectly depends on the fixture. For example, this is the case
-            # when the test depends on an async fixture, both of which share the same
-            # asyncio_event_loop mark.
-            if event_loop_fixture_id in metafunc.fixturenames:
-                continue
-            fixturemanager = metafunc.config.pluginmanager.get_plugin("funcmanage")
-            if "event_loop" in metafunc.fixturenames:
-                raise MultipleEventLoopsRequestedError(
-                    _MULTIPLE_LOOPS_REQUESTED_ERROR
-                    % (metafunc.definition.nodeid, event_loop_provider_node.nodeid),
-                )
-            # Add the scoped event loop fixture to Metafunc's list of fixture names and
-            # fixturedefs and leave the actual parametrization to pytest
-            metafunc.fixturenames.insert(0, event_loop_fixture_id)
-            metafunc._arg2fixturedefs[
-                event_loop_fixture_id
-            ] = fixturemanager._arg2fixturedefs[event_loop_fixture_id]
-            break
+    marker = metafunc.definition.get_closest_marker("asyncio")
+    if not marker:
+        return
+    scope = marker.kwargs.get("scope", "function")
+    if scope == "function":
+        return
+    event_loop_node = _retrieve_scope_root(metafunc.definition, scope)
+    event_loop_fixture_id = event_loop_node.stash.get(_event_loop_fixture_id, None)
+
+    if event_loop_fixture_id:
+        # This specific fixture name may already be in metafunc.argnames, if this
+        # test indirectly depends on the fixture. For example, this is the case
+        # when the test depends on an async fixture, both of which share the same
+        # asyncio_event_loop mark.
+        if event_loop_fixture_id in metafunc.fixturenames:
+            return
+        fixturemanager = metafunc.config.pluginmanager.get_plugin("funcmanage")
+        if "event_loop" in metafunc.fixturenames:
+            raise MultipleEventLoopsRequestedError(
+                _MULTIPLE_LOOPS_REQUESTED_ERROR
+                % (metafunc.definition.nodeid, event_loop_node.nodeid),
+            )
+        # Add the scoped event loop fixture to Metafunc's list of fixture names and
+        # fixturedefs and leave the actual parametrization to pytest
+        metafunc.fixturenames.insert(0, event_loop_fixture_id)
+        metafunc._arg2fixturedefs[
+            event_loop_fixture_id
+        ] = fixturemanager._arg2fixturedefs[event_loop_fixture_id]
 
 
 @pytest.hookimpl(hookwrapper=True)
@@ -826,11 +825,12 @@ def pytest_runtest_setup(item: pytest.Item) -> None:
     marker = item.get_closest_marker("asyncio")
     if marker is None:
         return
-    event_loop_fixture_id = "event_loop"
-    for node, mark in item.iter_markers_with_node("asyncio_event_loop"):
-        event_loop_fixture_id = node.stash.get(_event_loop_fixture_id, None)
-        if event_loop_fixture_id:
-            break
+    scope = marker.kwargs.get("scope", "function")
+    if scope != "function":
+        parent_node = _retrieve_scope_root(item, scope)
+        event_loop_fixture_id = parent_node.stash[_event_loop_fixture_id]
+    else:
+        event_loop_fixture_id = "event_loop"
     fixturenames = item.fixturenames  # type: ignore[attr-defined]
     # inject an event loop fixture for all async tests
     if "event_loop" in fixturenames:
@@ -846,6 +846,18 @@ def pytest_runtest_setup(item: pytest.Item) -> None:
         )
 
 
+def _retrieve_scope_root(item: Union[Collector, Item], scope: str) -> Collector:
+    node_type_by_scope = {
+        "class": Class,
+        "module": Module,
+    }
+    scope_root_type = node_type_by_scope[scope]
+    for node in reversed(item.listchain()):
+        if isinstance(node, scope_root_type):
+            return node
+    raise RuntimeError()
+
+
 @pytest.fixture
 def event_loop(request: FixtureRequest) -> Iterator[asyncio.AbstractEventLoop]:
     """Create an instance of the default event loop for each test case."""

docs/source/reference/markers/module_scoped_loop_auto_mode_example.py renamed to docs/source/reference/markers/module_scoped_loop_strict_mode_example.py

@@ -26,7 +26,7 @@ def sample_fixture():
     return None
 
 
-def test_asyncio_event_loop_mark_provides_class_scoped_loop_strict_mode(
+def test_asyncio_mark_provides_class_scoped_loop_when_applied_to_functions(
     pytester: pytest.Pytester,
 ):
     pytester.makepyfile(
@@ -35,15 +35,14 @@ def test_asyncio_event_loop_mark_provides_class_scoped_loop_strict_mode(
             import asyncio
             import pytest
 
-            @pytest.mark.asyncio_event_loop
             class TestClassScopedLoop:
                 loop: asyncio.AbstractEventLoop
 
-                @pytest.mark.asyncio
+                @pytest.mark.asyncio(scope="class")
                 async def test_remember_loop(self):
                     TestClassScopedLoop.loop = asyncio.get_running_loop()
 
-                @pytest.mark.asyncio
+                @pytest.mark.asyncio(scope="class")
                 async def test_this_runs_in_same_loop(self):
                     assert asyncio.get_running_loop() is TestClassScopedLoop.loop
             """
@@ -53,7 +52,7 @@ async def test_this_runs_in_same_loop(self):
     result.assert_outcomes(passed=2)
 
 
-def test_asyncio_event_loop_mark_provides_class_scoped_loop_auto_mode(
+def test_asyncio_mark_provides_class_scoped_loop_when_applied_to_class(
     pytester: pytest.Pytester,
 ):
     pytester.makepyfile(
@@ -62,7 +61,7 @@ def test_asyncio_event_loop_mark_provides_class_scoped_loop_auto_mode(
             import asyncio
             import pytest
 
-            @pytest.mark.asyncio_event_loop
+            @pytest.mark.asyncio(scope="class")
             class TestClassScopedLoop:
                 loop: asyncio.AbstractEventLoop
 
@@ -74,29 +73,27 @@ async def test_this_runs_in_same_loop(self):
             """
         )
     )
-    result = pytester.runpytest("--asyncio-mode=auto")
+    result = pytester.runpytest("--asyncio-mode=strict")
     result.assert_outcomes(passed=2)
 
 
-def test_asyncio_event_loop_mark_is_inherited_to_subclasses(pytester: pytest.Pytester):
+def test_asyncio_mark_is_inherited_to_subclasses(pytester: pytest.Pytester):
     pytester.makepyfile(
         dedent(
             """\
             import asyncio
             import pytest
 
-            @pytest.mark.asyncio_event_loop
+            @pytest.mark.asyncio(scope="class")
             class TestSuperClassWithMark:
                 pass
 
             class TestWithoutMark(TestSuperClassWithMark):
                 loop: asyncio.AbstractEventLoop
 
-                @pytest.mark.asyncio
                 async def test_remember_loop(self):
                     TestWithoutMark.loop = asyncio.get_running_loop()
 
-                @pytest.mark.asyncio
                 async def test_this_runs_in_same_loop(self):
                     assert asyncio.get_running_loop() is TestWithoutMark.loop
             """
@@ -106,29 +103,7 @@ async def test_this_runs_in_same_loop(self):
     result.assert_outcomes(passed=2)
 
 
-def test_raise_when_event_loop_fixture_is_requested_in_addition_to_scoped_loop(
-    pytester: pytest.Pytester,
-):
-    pytester.makepyfile(
-        dedent(
-            """\
-            import asyncio
-            import pytest
-
-            @pytest.mark.asyncio_event_loop
-            class TestClassScopedLoop:
-                @pytest.mark.asyncio
-                async def test_remember_loop(self, event_loop):
-                    pass
-            """
-        )
-    )
-    result = pytester.runpytest("--asyncio-mode=strict")
-    result.assert_outcomes(errors=1)
-    result.stdout.fnmatch_lines("*MultipleEventLoopsRequestedError: *")
-
-
-def test_asyncio_event_loop_mark_allows_specifying_the_loop_policy(
+def test_asyncio_mark_respects_the_loop_policy(
     pytester: pytest.Pytester,
 ):
     pytester.makepyfile(
@@ -144,10 +119,8 @@ class CustomEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
             def event_loop_policy():
                 return CustomEventLoopPolicy()
 
-            @pytest.mark.asyncio_event_loop
-            class TestUsesCustomEventLoop:
-
-                @pytest.mark.asyncio
+            @pytest.mark.asyncio(scope="class")
+            class TestUsesCustomEventLoopPolicy:
                 async def test_uses_custom_event_loop_policy(self):
                     assert isinstance(
                         asyncio.get_event_loop_policy(),
@@ -167,7 +140,7 @@ async def test_does_not_use_custom_event_loop_policy():
     result.assert_outcomes(passed=2)
 
 
-def test_asyncio_event_loop_mark_allows_specifying_multiple_loop_policies(
+def test_asyncio_mark_respects_parametrized_loop_policies(
     pytester: pytest.Pytester,
 ):
     pytester.makepyfile(
@@ -178,6 +151,7 @@ def test_asyncio_event_loop_mark_allows_specifying_multiple_loop_policies(
             import pytest
 
             @pytest.fixture(
+                scope="class",
                 params=[
                     asyncio.DefaultEventLoopPolicy(),
                     asyncio.DefaultEventLoopPolicy(),
@@ -186,8 +160,8 @@ def test_asyncio_event_loop_mark_allows_specifying_multiple_loop_policies(
             def event_loop_policy(request):
                 return request.param
 
+            @pytest.mark.asyncio(scope="class")
             class TestWithDifferentLoopPolicies:
-                @pytest.mark.asyncio
                 async def test_parametrized_loop(self, request):
                     pass
             """
@@ -197,7 +171,7 @@ async def test_parametrized_loop(self, request):
     result.assert_outcomes(passed=2)
 
 
-def test_asyncio_event_loop_mark_provides_class_scoped_loop_to_fixtures(
+def test_asyncio_mark_provides_class_scoped_loop_to_fixtures(
     pytester: pytest.Pytester,
 ):
     pytester.makepyfile(
@@ -208,7 +182,7 @@ def test_asyncio_event_loop_mark_provides_class_scoped_loop_to_fixtures(
             import pytest
             import pytest_asyncio
 
-            @pytest.mark.asyncio_event_loop
+            @pytest.mark.asyncio(scope="class")
             class TestClassScopedLoop:
                 loop: asyncio.AbstractEventLoop
 

docs/source/reference/markers/pytestmark_asyncio_strict_mode_example.py

@@ -59,22 +59,19 @@ def test_asyncio_mark_provides_module_scoped_loop_strict_mode(pytester: Pytester
             import asyncio
             import pytest
 
-            pytestmark = pytest.mark.asyncio_event_loop
+            pytestmark = pytest.mark.asyncio(scope="module")
 
             loop: asyncio.AbstractEventLoop
 
-            @pytest.mark.asyncio
             async def test_remember_loop():
                 global loop
                 loop = asyncio.get_running_loop()
 
-            @pytest.mark.asyncio
             async def test_this_runs_in_same_loop():
                 global loop
                 assert asyncio.get_running_loop() is loop
 
             class TestClassA:
-                @pytest.mark.asyncio
                 async def test_this_runs_in_same_loop(self):
                     global loop
                     assert asyncio.get_running_loop() is loop
@@ -85,36 +82,6 @@ async def test_this_runs_in_same_loop(self):
     result.assert_outcomes(passed=3)
 
 
-def test_asyncio_mark_provides_class_scoped_loop_auto_mode(pytester: Pytester):
-    pytester.makepyfile(
-        dedent(
-            """\
-            import asyncio
-            import pytest
-
-            pytestmark = pytest.mark.asyncio_event_loop
-
-            loop: asyncio.AbstractEventLoop
-
-            async def test_remember_loop():
-                global loop
-                loop = asyncio.get_running_loop()
-
-            async def test_this_runs_in_same_loop():
-                global loop
-                assert asyncio.get_running_loop() is loop
-
-            class TestClassA:
-                async def test_this_runs_in_same_loop(self):
-                    global loop
-                    assert asyncio.get_running_loop() is loop
-            """
-        )
-    )
-    result = pytester.runpytest("--asyncio-mode=auto")
-    result.assert_outcomes(passed=3)
-
-
 def test_raise_when_event_loop_fixture_is_requested_in_addition_to_scoped_loop(
     pytester: Pytester,
 ):
@@ -124,9 +91,8 @@ def test_raise_when_event_loop_fixture_is_requested_in_addition_to_scoped_loop(
             import asyncio
             import pytest
 
-            pytestmark = pytest.mark.asyncio_event_loop
+            pytestmark = pytest.mark.asyncio(scope="module")
 
-            @pytest.mark.asyncio
             async def test_remember_loop(event_loop):
                 pass
             """
@@ -137,7 +103,7 @@ async def test_remember_loop(event_loop):
     result.stdout.fnmatch_lines("*MultipleEventLoopsRequestedError: *")
 
 
-def test_asyncio_event_loop_mark_allows_specifying_the_loop_policy(
+def test_asyncio_mark_respects_the_loop_policy(
     pytester: Pytester,
 ):
     pytester.makepyfile(
@@ -157,13 +123,12 @@ class CustomEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
 
             from .custom_policy import CustomEventLoopPolicy
 
-            pytestmark = pytest.mark.asyncio_event_loop
+            pytestmark = pytest.mark.asyncio(scope="module")
 
             @pytest.fixture(scope="module")
             def event_loop_policy():
                 return CustomEventLoopPolicy()
 
-            @pytest.mark.asyncio
             async def test_uses_custom_event_loop_policy():
                 assert isinstance(
                     asyncio.get_event_loop_policy(),
@@ -178,7 +143,8 @@ async def test_uses_custom_event_loop_policy():
 
             from .custom_policy import CustomEventLoopPolicy
 
-            @pytest.mark.asyncio
+            pytestmark = pytest.mark.asyncio(scope="module")
+
             async def test_does_not_use_custom_event_loop_policy():
                 assert not isinstance(
                     asyncio.get_event_loop_policy(),
@@ -191,7 +157,7 @@ async def test_does_not_use_custom_event_loop_policy():
     result.assert_outcomes(passed=2)
 
 
-def test_asyncio_event_loop_mark_allows_specifying_multiple_loop_policies(
+def test_asyncio_mark_respects_parametrized_loop_policies(
     pytester: Pytester,
 ):
     pytester.makepyfile(
@@ -201,7 +167,7 @@ def test_asyncio_event_loop_mark_allows_specifying_multiple_loop_policies(
 
             import pytest
 
-            pytestmark = pytest.mark.asyncio_event_loop
+            pytestmark = pytest.mark.asyncio(scope="module")
 
             @pytest.fixture(
                 scope="module",
@@ -213,17 +179,16 @@ def test_asyncio_event_loop_mark_allows_specifying_multiple_loop_policies(
             def event_loop_policy(request):
                 return request.param
 
-            @pytest.mark.asyncio
             async def test_parametrized_loop():
                 pass
             """
         )
     )
-    result = pytester.runpytest_subprocess("--asyncio-mode=strict", "--setup-show")
+    result = pytester.runpytest_subprocess("--asyncio-mode=strict")
     result.assert_outcomes(passed=2)
 
 
-def test_asyncio_event_loop_mark_provides_module_scoped_loop_to_fixtures(
+def test_asyncio_mark_provides_module_scoped_loop_to_fixtures(
     pytester: Pytester,
 ):
     pytester.makepyfile(
@@ -234,16 +199,15 @@ def test_asyncio_event_loop_mark_provides_module_scoped_loop_to_fixtures(
             import pytest
             import pytest_asyncio
 
-            pytestmark = pytest.mark.asyncio_event_loop
+            pytestmark = pytest.mark.asyncio(scope="module")
 
             loop: asyncio.AbstractEventLoop
 
-            @pytest_asyncio.fixture
+            @pytest_asyncio.fixture(scope="module")
             async def my_fixture():
                 global loop
                 loop = asyncio.get_running_loop()
 
-            @pytest.mark.asyncio
             async def test_runs_is_same_loop_as_fixture(my_fixture):
                 global loop
                 assert asyncio.get_running_loop() is loop

pytest_asyncio/plugin.py

@@ -1,6 +1,6 @@
 [tox]
 minversion = 3.14.0
-envlist = py38, py39, py310, py311, py312, pytest-min
+envlist = py38, py39, py310, py311, py312, pytest-min, docs
 isolated_build = true
 passenv =
     CI
@@ -23,6 +23,16 @@ commands = make test
 allowlist_externals =
     make
 
+[testenv:docs]
+extras = docs
+deps =
+     --requirement dependencies/docs/requirements.txt
+     --constraint dependencies/docs/constraints.txt
+change_dir = docs
+commands = make html
+allowlist_externals =
+    make
+
 [gh-actions]
 python =
     3.8: py38, pytest-min