From 48cad08c18c870ecb24018bf32e2925923790ad6 Mon Sep 17 00:00:00 2001
From: Michael Seifert <m.seifert@digitalernachschub.de>
Date: Wed, 8 Nov 2023 13:02:17 +0100
Subject: [PATCH] [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           |  1 +
 docs/source/how-to-guides/multiple_loops.rst  | 10 ++++++++
 .../how-to-guides/multiple_loops_example.py   | 24 +++++++++++++++++++
 3 files changed, 35 insertions(+)
 create mode 100644 docs/source/how-to-guides/multiple_loops.rst
 create mode 100644 docs/source/how-to-guides/multiple_loops_example.py

diff --git a/docs/source/how-to-guides/index.rst b/docs/source/how-to-guides/index.rst
index 922fac91..5bcb3be7 100644
--- a/docs/source/how-to-guides/index.rst
+++ b/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.
diff --git a/docs/source/how-to-guides/multiple_loops.rst b/docs/source/how-to-guides/multiple_loops.rst
new file mode 100644
index 00000000..3453c49f
--- /dev/null
+++ b/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.
diff --git a/docs/source/how-to-guides/multiple_loops_example.py b/docs/source/how-to-guides/multiple_loops_example.py
new file mode 100644
index 00000000..a4c7a01c
--- /dev/null
+++ b/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)