[docs] Fixes the example showing how to run all tests in a session-sc…

…oped loop.

The change also adds a warning that the code snippet overrides all manually applied marks in strict mode and adds tests verifying the correctness of the example.

Signed-off-by: Michael Seifert <m.seifert@digitalernachschub.de>

docs/source/how-to-guides/run_session_tests_in_same_loop.rst

@@ -6,3 +6,5 @@ The easiest way to mark all tests is via a ``pytest_collection_modifyitems`` hoo
 
 .. include:: session_scoped_loop_example.py
     :code: python
+
+Note that this will also override *all* manually applied marks in *strict* mode.

docs/source/how-to-guides/session_scoped_loop_example.py

@@ -7,4 +7,4 @@ def pytest_collection_modifyitems(items):
     pytest_asyncio_tests = (item for item in items if is_async_test(item))
     session_scope_marker = pytest.mark.asyncio(scope="session")
     for async_test in pytest_asyncio_tests:
-        async_test.add_marker(session_scope_marker)
+        async_test.add_marker(session_scope_marker, append=False)

docs/source/how-to-guides/test_session_scoped_loop_example.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+from textwrap import dedent
+
+from pytest import Pytester
+
+
+def test_session_scoped_loop_configuration_works_in_auto_mode(
+    pytester: Pytester,
+):
+    session_wide_mark_conftest = (
+        Path(__file__).parent / "session_scoped_loop_example.py"
+    )
+    pytester.makeconftest(session_wide_mark_conftest.read_text())
+    pytester.makepyfile(
+        dedent(
+            """\
+            import asyncio
+
+            session_loop = None
+
+            async def test_store_loop(request):
+                global session_loop
+                session_loop = asyncio.get_running_loop()
+
+            async def test_compare_loop(request):
+                global session_loop
+                assert asyncio.get_running_loop() is session_loop
+            """
+        )
+    )
+    result = pytester.runpytest_subprocess("--asyncio-mode=auto")
+    result.assert_outcomes(passed=2)
+
+
+def test_session_scoped_loop_configuration_works_in_strict_mode(
+    pytester: Pytester,
+):
+    session_wide_mark_conftest = (
+        Path(__file__).parent / "session_scoped_loop_example.py"
+    )
+    pytester.makeconftest(session_wide_mark_conftest.read_text())
+    pytester.makepyfile(
+        dedent(
+            """\
+            import asyncio
+            import pytest
+
+            session_loop = None
+
+            @pytest.mark.asyncio
+            async def test_store_loop(request):
+                global session_loop
+                session_loop = asyncio.get_running_loop()
+
+            @pytest.mark.asyncio
+            async def test_compare_loop(request):
+                global session_loop
+                assert asyncio.get_running_loop() is session_loop
+            """
+        )
+    )
+    result = pytester.runpytest_subprocess("--asyncio-mode=strict")
+    result.assert_outcomes(passed=2)