From af68b2e60d5a3d5106a4791b10ce2aa08c034187 Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Thu, 1 Oct 2026 22:09:19 +0300 Subject: [PATCH 1/4] Document that regrtest loads tests with unittest and rejects test_main(). --- Doc/library/test.rst | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 765811eba32fd4..c0b8bfd428a680 100644 --- a/Doc/library/test.rst +++ b/Doc/library/test.rst @@ -165,11 +165,16 @@ test suite, thanks to the :option:`-m` option: :program:`python -m test`. Under the hood, it uses :mod:`!test.regrtest`; the call :program:`python -m test.regrtest` used in previous Python versions still works. Running the script by itself automatically starts running all regression tests in the -:mod:`!test` package. It does this by finding all modules in the package whose -name starts with ``test_``, importing them, and executing the function -:func:`test_main` if present or loading the tests via -unittest.TestLoader.loadTestsFromModule if ``test_main`` does not exist. The -names of tests to execute may also be passed to the script. Specifying a single +:mod:`!test` package. It does this by finding modules and packages whose names +start with ``test_``, importing each one, and loading its tests with +:meth:`unittest.TestLoader.loadTestsFromModule`. The loader collects +:class:`unittest.TestCase` tests defined in the module. If the module defines +``load_tests``, the loader calls it with that suite and runs the suite the +function returns. Test packages use ``load_tests``, often via +:func:`test.support.load_package_tests`, to add tests discovered in +submodules. A module-level ``test_main()`` function is not called. If a test +module defines ``test_main``, :mod:`!test.regrtest` fails that test. The names of +tests to execute may also be passed to the script. Specifying a single regression test (:program:`python -m test test_spam`) will minimize output and only print whether the test passed or failed. @@ -882,9 +887,11 @@ The :mod:`!test.support` module defines the following functions: .. function:: reap_children() - Use this at the end of ``test_main`` whenever sub-processes are started. - This will help ensure that no extra children (zombies) stick around to - hog resources and create problems when looking for refleaks. + Call this from a test's :meth:`~unittest.TestCase.setUp`, + :meth:`~unittest.TestCase.tearDown`, or from ``tearDownModule`` when the + test starts subprocesses. This will help ensure that no extra children + (zombies) stick around to hog resources and create problems when looking + for refleaks. .. function:: get_attribute(obj, name) From 9890bcb1445260c2ab1862f4727774cf2de855da Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Thu, 1 Oct 2026 22:22:53 +0300 Subject: [PATCH 2/4] Align reap_children() docstring with the regrtest documentation. --- Lib/test/support/__init__.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Lib/test/support/__init__.py b/Lib/test/support/__init__.py index f348c9a5bbb31c..96f2e0916f715c 100644 --- a/Lib/test/support/__init__.py +++ b/Lib/test/support/__init__.py @@ -1595,10 +1595,10 @@ def set_environment_altered(reason): def reap_children(): - """Use this function at the end of test_main() whenever sub-processes - are started. This will help ensure that no extra children (zombies) - stick around to hog resources and create problems when looking - for refleaks. + """Call this from a test's setUp(), tearDown(), or tearDownModule() + when the test starts subprocesses. This will help ensure that no extra + children (zombies) stick around to hog resources and create problems when + looking for refleaks. """ # Need os.waitpid(-1, os.WNOHANG): Windows is not supported if not (hasattr(os, 'waitpid') and hasattr(os, 'WNOHANG')): From 787c24004446a05c78a241bd68dfa5d2bfe883e1 Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Sat, 3 Oct 2026 21:19:15 +0000 Subject: [PATCH 3/4] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20blu?= =?UTF-8?q?rb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst diff --git a/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst b/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst new file mode 100644 index 00000000000000..19b4b6a997e60e --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst @@ -0,0 +1,5 @@ +`Doc/library/test.rst` said that `python -m test` calls a module-level `test_main()` when it exists, and otherwise loads tests with `unittest.TestLoader.loadTestsFromModule`. It also told readers to call `test.support.reap_children()` at the end of `test_main`. The docstring of `reap_children()` said the same thing. + +`libregrtest` does not call `test_main()`. If the imported module defines it, `Lib/test/libregrtest/single.py` raises `Exception`. regrtest reports the module as failed with an uncaught exception (stderr: `test crashed`; summary: `failed (uncaught exception)`). Tests are loaded with `loadTestsFromModule`, which collects `TestCase` classes and, when the module defines `load_tests`, runs the suite that function returns. Packages use `load_tests`, usually via `test.support.load_package_tests`, to add tests from submodules. `reap_children()` is called from `setUp()`, `tearDown()`, and `tearDownModule()`. + +The runner is unchanged. This updates the library page and the `reap_children()` docstring. From 58b6171dcaf21ed51e241a93c46b750146cf85ed Mon Sep 17 00:00:00 2001 From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com> Date: Sun, 4 Oct 2026 18:37:46 +0300 Subject: [PATCH 4/4] Delete Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst --- .../2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst | 5 ----- 1 file changed, 5 deletions(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst diff --git a/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst b/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst deleted file mode 100644 index 19b4b6a997e60e..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst +++ /dev/null @@ -1,5 +0,0 @@ -`Doc/library/test.rst` said that `python -m test` calls a module-level `test_main()` when it exists, and otherwise loads tests with `unittest.TestLoader.loadTestsFromModule`. It also told readers to call `test.support.reap_children()` at the end of `test_main`. The docstring of `reap_children()` said the same thing. - -`libregrtest` does not call `test_main()`. If the imported module defines it, `Lib/test/libregrtest/single.py` raises `Exception`. regrtest reports the module as failed with an uncaught exception (stderr: `test crashed`; summary: `failed (uncaught exception)`). Tests are loaded with `loadTestsFromModule`, which collects `TestCase` classes and, when the module defines `load_tests`, runs the suite that function returns. Packages use `load_tests`, usually via `test.support.load_package_tests`, to add tests from submodules. `reap_children()` is called from `setUp()`, `tearDown()`, and `tearDownModule()`. - -The runner is unchanged. This updates the library page and the `reap_children()` docstring.