improve warning message. Make it warn regardless of autouse or not. Add section to deprecations.rst

Author: jakkdl

changelog/10839.deprecation.rst

@@ -1 +1 @@
-Synchronous tests that request an asynchronous fixture with ``autouse=True`` will now give a DeprecationWarning.
+Synchronous tests that request an asynchronous fixture will now give a DeprecationWarning. This will introduce warnings in several pytest plugins that handle async tests/fixtures and for some users with custom setups. For guidance on how to manage this see :ref:`sync-test-async-fixture`.

changelog/10839.improvement.rst

@@ -15,6 +15,61 @@ Below is a complete list of all pytest features which are considered deprecated.
 :class:`~pytest.PytestWarning` or subclasses, which can be filtered using :ref:`standard warning filters <warnings>`.
 
 
+.. _sync-test-async-fixture:
+
+sync test depending on async fixture
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. deprecated:: 8.4
+
+Pytest has for a long time given an error when encountering an asynchronous test function, prompting the user to install
+a plugin that can handle it. It has not given any errors if you have an asynchronous fixture that's depended on by a
+synchronous test. This is a problem even if you do have a plugin installed for handling async tests, as they may require
+special decorators for async fixtures to be handled, and some may not robustly handle if a user accidentally requests an
+async fixture from their sync tests. Fixture values being cached can make this even more unintuitive, where everything will
+"work" if the fixture is first requested by an async test, and then requested by a synchronous test.
+
+Unfortunately there is no 100% reliable method of identifying when a user has made a mistake, versus when they expect an
+unawaited object from their fixture that they will handle - either on their own, or by a plugin. To suppress this warning
+when you in fact did intend to handle this you can wrap your async fixture in a synchronous fixture:
+
+.. code-block:: python
+
+    import asyncio
+    import pytest
+
+
+    @pytest.fixture
+    async def unawaited_fixture():
+        return 1
+
+
+    def test_foo(unawaited_fixture):
+        assert 1 == asyncio.run(unawaited_fixture)
+
+should be changed to
+
+
+.. code-block:: python
+
+    import asyncio
+    import pytest
+
+
+    @pytest.fixture
+    def unawaited_fixture():
+        async def inner_fixture():
+            return 1
+
+        return inner_fixture()
+
+
+    def test_foo(unawaited_fixture):
+        assert 1 == asyncio.run(unawaited_fixture)
+
+If a user has an async fixture with ``autouse=True`` in their ``conftest.py``, or in a file where they also have synchronous tests, they will also get this warning. We strongly recommend against this practice, and they should restructure their testing infrastructure so the fixture is synchronous or to separate the fixture from their synchronous tests. Plugins that handle async may want to introduce helpers to make that easier in scenarios where that might be wanted, e.g. if setting up a database in an asynchronous way, or the user may opt to make their test async even though it might not strictly need to be.
+
+
 .. _import-or-skip-import-error:
 
 ``pytest.importorskip`` default behavior regarding :class:`ImportError`

doc/en/deprecations.rst

@@ -308,7 +308,7 @@ disable = [
 ]
 
 [tool.codespell]
-ignore-words-list = "afile,asser,assertio,feld,hove,ned,noes,notin,paramete,parth,socio-economic,tesults,varius,wil"
+ignore-words-list = "afile,asend,asser,assertio,feld,hove,ned,noes,notin,paramete,parth,socio-economic,tesults,varius,wil"
 skip = "*/plugin_list.rst"
 write-changes = true
 

pyproject.toml

@@ -609,23 +609,26 @@ def _get_active_fixturedef(
             if fixturedef._autouse:
                 warnings.warn(
                     PytestRemovedIn9Warning(
-                        "Sync test requested an async fixture with autouse=True. "
+                        f"Sync test {self._pyfuncitem.name!r} requested async fixture "
+                        f"{argname!r} with autouse=True. "
                         "If you intended to use the fixture you may want to make the "
-                        "test asynchronous. If you did not intend to use it you should "
+                        "test asynchronous or the fixture synchronous. "
+                        "If you did not intend to use it you should "
                         "restructure your test setup. "
                         "This will turn into an error in pytest 9."
                     ),
                     stacklevel=3,
                 )
             else:
-                raise FixtureLookupError(
-                    argname,
-                    self,
-                    (
-                        "ERROR: Sync test requested async fixture. "
+                warnings.warn(
+                    PytestRemovedIn9Warning(
+                        f"Sync test {self._pyfuncitem.name!r} requested async fixture "
+                        f"{argname!r}. "
                         "You may want to make the test asynchronous and run it with "
-                        "a suitable async framework test plugin."
+                        "a suitable async framework test plugin, or make the fixture synchronous. "
+                        "This will turn into an error in pytest 9."
                     ),
+                    stacklevel=3,
                 )
 
         # Prepare a SubRequest object for calling the fixture.

src/_pytest/fixtures.py

@@ -1296,21 +1296,26 @@ async def async_fixture():
                 ...
 
             def test_foo(async_fixture):
-                ...
+                # suppress unawaited coroutine warning
+                try:
+                    async_fixture.send(None)
+                except StopIteration:
+                    pass
         """
     )
     result = pytester.runpytest()
     result.stdout.fnmatch_lines(
         [
             (
-                "*ERROR: Sync test requested async fixture. "
+                "*Sync test 'test_foo' requested async fixture "
+                "'async_fixture'. "
                 "You may want to make the test asynchronous and run it with "
-                "a suitable async framework test plugin.*"
+                "a suitable async framework test plugin, or make the fixture synchronous. "
+                "This will turn into an error in pytest 9."
             ),
-            "*ERROR test_sync.py::test_foo*",
         ]
     )
-    result.assert_outcomes(errors=1)
+    result.assert_outcomes(passed=1, warnings=1)
 
 
 def test_error_on_sync_test_async_fixture_gen(pytester: Pytester) -> None:
@@ -1323,21 +1328,26 @@ async def async_fixture():
                 yield
 
             def test_foo(async_fixture):
-                ...
+                # suppress unawaited coroutine warning
+                try:
+                    async_fixture.asend(None)
+                except StopIteration:
+                    pass
         """
     )
     result = pytester.runpytest()
     result.stdout.fnmatch_lines(
         [
             (
-                "*ERROR: Sync test requested async fixture. "
+                "*Sync test 'test_foo' requested async fixture "
+                "'async_fixture'. "
                 "You may want to make the test asynchronous and run it with "
-                "a suitable async framework test plugin.*"
+                "a suitable async framework test plugin, or make the fixture synchronous. "
+                "This will turn into an error in pytest 9."
             ),
-            "*ERROR test_sync.py::test_foo*",
         ]
     )
-    result.assert_outcomes(errors=1)
+    result.assert_outcomes(passed=1, warnings=1)
 
 
 def test_warning_on_sync_test_async_autouse_fixture(pytester: Pytester) -> None:
@@ -1362,11 +1372,11 @@ def test_foo(async_fixture):
     result.stdout.fnmatch_lines(
         [
             (
-                "*Sync test requested an async fixture with autouse=True. "
-                "If you intended to use the fixture you may want to make the "
-                "test asynchronous. If you did not intend to use it you should "
-                "restructure your test setup. "
-                "This will turn into an error in pytest 9.*"
+                "*Sync test 'test_foo' requested async fixture "
+                "'async_fixture' with autouse=True. "
+                "You may want to make the test asynchronous and run it with "
+                "a suitable async framework test plugin, or make the fixture synchronous. "
+                "This will turn into an error in pytest 9."
             ),
         ]
     )