From 2a51b3fc4015f6f648c2dc20a87953d3c69ba6be Mon Sep 17 00:00:00 2001 From: Jake Chapa Date: Thu, 19 Nov 2026 12:12:06 +0700 Subject: [PATCH] Warn about tasks still pending when an event loop scope ends When the scope of an event loop ends, collect the tasks that are still pending and emit a RuntimeWarning that lists them once the runner is closed. Users can turn the warning into an error with pytest's warning filters. Tasks asyncio creates to close abandoned async generators are left out. Closes #1044 --- changelog.d/1044.added.rst | 1 + docs/concepts.rst | 10 ++++ pytest_asyncio/plugin.py | 25 +++++++++ tests/test_task_cleanup.py | 108 ++++++++++++++++++++++++++++++++++++- 4 files changed, 142 insertions(+), 2 deletions(-) create mode 100644 changelog.d/1044.added.rst 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*", + ] + )