[docs] Added how-to guide for testing with multiple loops.

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

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

@@ -5,6 +5,7 @@ How-To Guides
 .. toctree::
   :hidden:
 
+  multiple_loops
   uvloop
 
 This section of the documentation provides code snippets and recipes to accomplish specific tasks with pytest-asyncio.

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

@@ -0,0 +1,10 @@
+======================================
+How to test with different event loops
+======================================
+
+Parametrizing the *event_loop_policy* fixture parametrizes all async tests. The following example causes all async tests to run multiple times, once for each event loop in the fixture parameters:
+
+.. include:: multiple_loops_example.py
+    :code: python
+
+You may choose to limit the scope of the fixture to *package,* *module,* or *class,* if you only want a subset of your tests to run with different event loops.

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

@@ -0,0 +1,24 @@
+import asyncio
+from asyncio import DefaultEventLoopPolicy
+
+import pytest
+
+
+class CustomEventLoopPolicy(DefaultEventLoopPolicy):
+    pass
+
+
+@pytest.fixture(
+    scope="session",
+    params=(
+        CustomEventLoopPolicy(),
+        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(), CustomEventLoopPolicy)