[docs] Added how-to guides for testing with different loop scopes.

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

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

@@ -0,0 +1,14 @@
+import asyncio
+
+import pytest
+
+
+@pytest.mark.asyncio(scope="class")
+class TestInOneEventLoopPerClass:
+    loop: asyncio.AbstractEventLoop
+
+    async def test_remember_loop(self):
+        TestInOneEventLoopPerClass.loop = asyncio.get_running_loop()
+
+    async def test_assert_same_loop(self):
+        assert asyncio.get_running_loop() is TestInOneEventLoopPerClass.loop

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

@@ -5,6 +5,10 @@ How-To Guides
 .. toctree::
   :hidden:
 
+  run_class_tests_in_same_loop
+  run_module_tests_in_same_loop
+  run_package_tests_in_same_loop
+  run_session_tests_in_same_loop
   multiple_loops
   uvloop
   test_item_is_async

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

@@ -0,0 +1,17 @@
+import asyncio
+
+import pytest
+
+pytestmark = pytest.mark.asyncio(scope="module")
+
+loop: asyncio.AbstractEventLoop
+
+
+async def test_remember_loop():
+    global loop
+    loop = asyncio.get_running_loop()
+
+
+async def test_assert_same_loop():
+    global loop
+    assert asyncio.get_running_loop() is loop

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

@@ -0,0 +1,3 @@
+import pytest
+
+pytestmark = pytest.mark.asyncio(scope="package")

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

@@ -0,0 +1,8 @@
+======================================================
+How to run all tests in a class in the same event loop
+======================================================
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="class")``.
+This is easily achieved by using the *asyncio* marker as a class decorator.
+
+.. include:: class_scoped_loop_example.py
+    :code: python

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

@@ -0,0 +1,8 @@
+=======================================================
+How to run all tests in a module in the same event loop
+=======================================================
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="module")``.
+This is easily achieved by adding a `pytestmark` statement to your module.
+
+.. include:: module_scoped_loop_example.py
+    :code: python

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

@@ -0,0 +1,11 @@
+========================================================
+How to run all tests in a package in the same event loop
+========================================================
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="package")``.
+Add the following code to the ``__init__.py`` of the test package:
+
+.. include:: package_scoped_loop_example.py
+    :code: python
+
+Note that this marker is not passed down to tests in subpackages.
+Subpackages constitute their own, separate package.

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

@@ -0,0 +1,8 @@
+==========================================================
+How to run all tests in the session in the same event loop
+==========================================================
+All tests can be run inside the same event loop by marking them with ``pytest.mark.asyncio(scope="session")``.
+The easiest way to mark all tests is via a ``pytest_collection_modifyitems`` hook in the ``conftest.py`` at the root folder of your test suite.
+
+.. include:: session_scoped_loop_example.py
+    :code: python

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

@@ -0,0 +1,10 @@
+import pytest
+
+from pytest_asyncio import is_async_test
+
+
+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)