diff --git a/changelog.d/1044.added.rst b/changelog.d/1044.added.rst new file mode 100644 index 00000000..c8ef2fdd --- /dev/null +++ b/changelog.d/1044.added.rst @@ -0,0 +1 @@ +A ``RuntimeWarning`` that lists the tasks still pending when the scope of an event loop ends. Use pytest's warning filters to turn it into an error. diff --git a/docs/concepts.rst b/docs/concepts.rst index 3ac57069..6b6bcada 100644 --- a/docs/concepts.rst +++ b/docs/concepts.rst @@ -44,6 +44,16 @@ It's highly recommended for neighboring tests to use the same event loop scope. For example, all tests in a class or module should use the same scope. Assigning neighboring tests to different event loop scopes is discouraged as it can make test code hard to follow. +When the scope of an event loop ends, pytest-asyncio closes the loop and cancels any tasks that are still pending. +It also emits a ``RuntimeWarning`` that lists those tasks, because a task that outlives its scope usually means that a test or fixture forgot to await or cancel it. +If pending tasks should fail your tests, turn the warning into an error with pytest's `filterwarnings `__ option: + +.. code-block:: ini + + [pytest] + filterwarnings = + error:Tasks were still pending:RuntimeWarning + Test discovery modes ==================== diff --git a/pytest_asyncio/plugin.py b/pytest_asyncio/plugin.py index 32b1a834..59e7c797 100644 --- a/pytest_asyncio/plugin.py +++ b/pytest_asyncio/plugin.py @@ -1003,6 +1003,22 @@ def _get_default_test_loop_scope(config: Config) -> Any: %s """ +_PENDING_TASKS_WARNING = """\ +Tasks were still pending when the %s-scoped event loop was closed. \ +Make sure your tests and fixtures await or cancel the tasks they create: +%s +""" + + +def _pending_tasks(loop: AbstractEventLoop) -> list[str]: + return [ + repr(task) + for task in asyncio.all_tasks(loop) + # The loop closes abandoned async generators in tasks of its own. + # Those are not tasks the tests created. + if type(task.get_coro()).__name__ != "async_generator_athrow" + ] + def _create_scoped_runner_fixture(scope: _ScopeName) -> Callable: @pytest.fixture( @@ -1026,6 +1042,7 @@ def _scoped_runner( except Exception as e: runner.__exit__(type(e), e, e.__traceback__) else: + pending_tasks = _pending_tasks(runner.get_loop()) with warnings.catch_warnings(): warnings.filterwarnings( "ignore", ".*BaseEventLoop.shutdown_asyncgens.*", RuntimeWarning @@ -1037,6 +1054,14 @@ def _scoped_runner( _RUNNER_TEARDOWN_WARNING % traceback.format_exc(), RuntimeWarning, ) + # Warn only after the runner is closed, so that the tasks are + # still cancelled when the warning is turned into an error. + if pending_tasks: + warnings.warn( + _PENDING_TASKS_WARNING + % (scope, "\n".join(f" {task}" for task in pending_tasks)), + RuntimeWarning, + ) finally: if _asyncio_loop_factory is not None: _set_event_loop(None) diff --git a/tests/test_task_cleanup.py b/tests/test_task_cleanup.py index fda60b81..4625d47c 100644 --- a/tests/test_task_cleanup.py +++ b/tests/test_task_cleanup.py @@ -2,6 +2,7 @@ from textwrap import dedent +import pytest from pytest import Pytester @@ -22,5 +23,108 @@ async def coroutine(): asyncio.create_task(coroutine()) """)) - result = pytester.runpytest("--asyncio-mode=strict") - result.assert_outcomes(passed=1) + result = pytester.runpytest("--asyncio-mode=strict", "-W", "default") + result.assert_outcomes(passed=1, warnings=1) + + +def test_warns_about_task_left_pending_by_test(pytester: Pytester): + pytester.makeini("[pytest]\nasyncio_default_fixture_loop_scope = function") + pytester.makepyfile(dedent("""\ + import asyncio + import pytest + + async def wait_forever(): + await asyncio.Event().wait() + + @pytest.mark.asyncio + async def test_leaves_task_pending(): + asyncio.create_task(wait_forever()) + + @pytest.mark.asyncio + async def test_awaits_its_task(): + await asyncio.create_task(asyncio.sleep(0)) + """)) + result = pytester.runpytest("--asyncio-mode=strict", "-W", "default") + result.assert_outcomes(passed=2, warnings=1) + result.stdout.fnmatch_lines( + [ + "*warnings summary*", + "test_warns_about_task_left_pending_by_test.py::test_leaves_task_pending", + "*RuntimeWarning: Tasks were still pending when the function-scoped " + "event loop was closed*", + "**", + ] + ) + + +@pytest.mark.parametrize("loop_scope", ("class", "module", "package", "session")) +def test_warns_about_pending_tasks_when_loop_scope_ends( + pytester: Pytester, loop_scope: str +): + pytester.makeini("[pytest]\nasyncio_default_fixture_loop_scope = function") + pytester.makepyfile( + __init__="", + test_pending_task=dedent(f"""\ + import asyncio + import pytest + + pytestmark = pytest.mark.asyncio(loop_scope="{loop_scope}") + + async def wait_forever(): + await asyncio.Event().wait() + + class TestPendingTask: + task = None + + async def test_starts_task(self): + TestPendingTask.task = asyncio.create_task(wait_forever()) + + async def test_task_is_still_pending(self): + await asyncio.sleep(0) + assert not TestPendingTask.task.done() + """), + ) + result = pytester.runpytest("--asyncio-mode=strict", "-W", "default") + result.assert_outcomes(passed=2, warnings=1) + result.stdout.fnmatch_lines( + [ + f"*RuntimeWarning: Tasks were still pending when the {loop_scope}-scoped " + "event loop was closed*", + "**", + ] + ) + + +def test_pending_tasks_warning_can_be_turned_into_an_error(pytester: Pytester): + pytester.makeini(dedent("""\ + [pytest] + asyncio_default_fixture_loop_scope = function + filterwarnings = + default + error:Tasks were still pending:RuntimeWarning + """)) + pytester.makepyfile(dedent("""\ + import asyncio + import pytest + + async def wait_forever(): + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + print("task was cancelled") + raise + + @pytest.mark.asyncio + async def test_leaves_task_pending(): + asyncio.create_task(wait_forever()) + """)) + result = pytester.runpytest("--asyncio-mode=strict", "-s") + result.assert_outcomes(passed=1, errors=1) + result.stdout.fnmatch_lines( + [ + "*task was cancelled", + "*ERROR at teardown of test_leaves_task_pending*", + "*RuntimeWarning: Tasks were still pending when the function-scoped " + "event loop was closed*", + ] + )