gh-158681: Document that regrtest rejects test_main() and loads unittest suites by bazhil · Pull Request #158682 · python/cpython

bazhil · 2026-10-03T21:15:41Z

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 <name> 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.

Issue: Doc/library/test.rst still says regrtest calls test_main() #158681

…n().

python-cla-bot · 2026-10-03T21:15:46Z

All commit authors signed the Contributor License Agreement.

read-the-docs-community · 2026-10-03T21:19:36Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #35085448 | 📁 Comparing c19d22f against main (1b015e6)

🔍 Preview build

27 files changed · ± 27 modified

± Modified

aisk · 2026-10-04T12:48:33Z

The commit email doesn't seem to be a valid address. Please use a valid one.

bazhil · 2026-10-04T18:01:14Z

The commit email doesn't seem to be a valid address. Please use a valid one.

Fixed

…8681.fpovlg.rst

…rding.

StanFromIreland

Some suggested wording tweaks.

StanFromIreland · 2026-10-11T19:03:02Z

+    """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.
    """


Suggested change

"""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.

"""

"""Call this from setUp(), tearDown(), or tearDownModule() in tests

that start subprocesses. This will help ensure that no extra children

(zombies) stick around to hog resources and create problems when

looking for refleaks.

"""

StanFromIreland · 2026-10-11T19:03:36Z

+   Call this from a test's :meth:`~unittest.TestCase.setUp`,
+   :meth:`~unittest.TestCase.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.


Suggested change

Call this from a test's :meth:`~unittest.TestCase.setUp`,

:meth:`~unittest.TestCase.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.

Call this from :meth:`~unittest.TestCase.setUp`,

:meth:`~unittest.TestCase.tearDown`, or ``tearDownModule()`` in tests

that start subprocesses. This will help ensure that no extra children

(zombies) stick around to hog resources and create problems when looking

for refleaks.

StanFromIreland · 2026-10-11T19:04:43Z

+: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`. See the
+:ref:`load_tests protocol <load_tests-protocol>` for how a module or package
+can customize what is loaded. 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


Suggested change

: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`. See the

:ref:`load_tests protocol <load_tests-protocol>` for how a module or package

can customize what is loaded. 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

: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`. See the

:ref:`load_tests protocol <load_tests-protocol>` for how a module or package

can customize what is loaded. Defining a module-level ``test_main()`` function

is not supported and causes the test to fail. The names of tests to

execute may also be passed to the script. Specifying a single

StanFromIreland · 2026-10-11T19:11:41Z

Please don't force push.

Also please apply suggestions, as it is clearer for reviewers whether something as been resolved (and if it has been modified while doing so).

StanFromIreland · 2026-10-12T16:07:41Z

@bazhil please apply suggestions via the web interface, that way it's clear if they have been applied or not. Since you didn't do that, I now have to re-review again.

bazhil · 2026-10-12T21:09:12Z

@StanFromIreland I apologize for the inconvenience. I will proceed in exactly this way in the future.

miss-islington-app · 2026-10-16T20:20:32Z

Thanks @bazhil for the PR, and @StanFromIreland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

miss-islington-app · 2026-10-16T20:20:32Z

Thanks @bazhil for the PR, and @StanFromIreland for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

bedevere-app · 2026-10-16T20:20:49Z

GH-159574 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2026-10-16T20:20:56Z

GH-159575 is a backport of this pull request to the 3.15 branch.

bazhil · 2026-10-16T20:48:12Z

@aisk @StanFromIreland Thank you!

…n()` (GH-158682) (#159574) (cherry picked from commit 75ce53d) Co-authored-by: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com>

…n()` (GH-158682) (#159575) (cherry picked from commit 75ce53d) Co-authored-by: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com>

bedevere-bot · 2026-10-16T22:05:05Z

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Hi! The buildbot ARM64 Raspbian 3.15 (tier-3) has failed when building commit df75ad4.

What do you need to do:

Don't panic.
Check the buildbot page in the devguide if you don't know what the buildbots are or how they work.
Go to the page of the buildbot that failed (https://buildbot.python.org/#/builders/2033/builds/609) and take a look at the build logs.
Check if the failure is related to this commit (df75ad4) or if it is a false positive.
If the failure is related to this commit, please, reflect that on the issue and make a new Pull Request with a fix.

You can take a look at the buildbot page here:

https://buildbot.python.org/#/builders/2033/builds/609

Failed tests:

test.test_multiprocessing_fork.test_processes

Failed subtests:

test_interrupt - test.test_multiprocessing_fork.test_processes.WithProcessesTestProcess.test_interrupt

Summary of the results of the build (if available):

==

Click to see traceback logs

Traceback (most recent call last):
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/contextlib.py", line 116, in inner
    return func(*args, **kwds)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 650, in test_interrupt
    exitcode = self._kill_process(multiprocessing.Process.interrupt)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/contextlib.py", line 116, in inner
    return func(*args, **kwds)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 631, in _kill_process
    self.assertEqual(join(), None)
                     ~~~~^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 304, in __call__
    return self.func(*args, **kwds)
           ~~~~~~~~~^^^^^^^^^^^^^^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/multiprocessing/process.py", line 156, in join
    res = self._popen.wait(timeout)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 44, in wait
    return self.poll(os.WNOHANG if timeout == 0.0 else 0)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 28, in poll
    pid, sts = os.waitpid(self.pid, flag)
               ~~~~~~~~~~^^^^^^^^^^^^^^^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 627, in handler
    raise RuntimeError('join took too long: %s' % p)
RuntimeError: join took too long: <Process name='Process-1' pid=1359989 parent=1359987 started daemon>


Traceback (most recent call last):
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/contextlib.py", line 116, in inner
    return func(*args, **kwds)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 650, in test_interrupt
    exitcode = self._kill_process(multiprocessing.Process.interrupt)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/contextlib.py", line 116, in inner
    return func(*args, **kwds)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 631, in _kill_process
    self.assertEqual(join(), None)
                     ~~~~^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 304, in __call__
    return self.func(*args, **kwds)
           ~~~~~~~~~^^^^^^^^^^^^^^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/multiprocessing/process.py", line 156, in join
    res = self._popen.wait(timeout)
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 44, in wait
    return self.poll(os.WNOHANG if timeout == 0.0 else 0)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/multiprocessing/popen_fork.py", line 28, in poll
    pid, sts = os.waitpid(self.pid, flag)
               ~~~~~~~~~~^^^^^^^^^^^^^^^^
  File "/home/stan/buildarea/3.15.stan-raspbian.nondebug/build/Lib/test/_test_multiprocessing.py", line 627, in handler
    raise RuntimeError('join took too long: %s' % p)
RuntimeError: join took too long: <Process name='Process-152' pid=1358143 parent=1357456 started daemon>

bazhil added 3 commits October 2, 2026 17:22

Document that regrtest loads tests with unittest and rejects test_mai…

af68b2e

…n().

Align reap_children() docstring with the regrtest documentation.

9890bcb

Merge branch 'python:main' into doc-regrtest-unittest-loader

b5c70b5

bedevere-app Bot added the awaiting review label Oct 3, 2026

bedevere-app Bot mentioned this pull request Oct 3, 2026

Doc/library/test.rst still says regrtest calls test_main() #158681

Closed

📜🤖 Added by blurb_it.

787c240

bazhil added 2 commits October 4, 2026 00:36

Merge branch 'main' into doc-regrtest-unittest-loader

cdcb8fb

Merge branch 'main' into doc-regrtest-unittest-loader

dbce53a

aisk reviewed Oct 4, 2026

View reviewed changes

Comment thread Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-158681.fpovlg.rst Outdated

aisk added the skip news label Oct 4, 2026

bazhil force-pushed the doc-regrtest-unittest-loader branch from fd30727 to 58b6171 Compare October 4, 2026 16:51

StanFromIreland reviewed Oct 7, 2026

View reviewed changes

Comment thread Doc/library/test.rst Outdated

Comment thread Doc/library/test.rst Outdated

bazhil added 2 commits October 8, 2026 00:35

Delete Misc/NEWS.d/next/Documentation/2026-10-03-21-19-14.gh-issue-15…

9290def

…8681.fpovlg.rst

Shorten the regrtest loading description and fix the reap_children wo…

aabe5ea

…rding.

bazhil force-pushed the doc-regrtest-unittest-loader branch from 58b6171 to aabe5ea Compare October 7, 2026 21:38

StanFromIreland reviewed Oct 11, 2026

View reviewed changes

Apply review wording for test_main and reap_children.

c19d22f

StanFromIreland approved these changes Oct 16, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting review labels Oct 16, 2026

StanFromIreland merged commit 75ce53d into python:main Oct 16, 2026
56 checks passed

bedevere-app Bot removed the awaiting merge label Oct 16, 2026

StanFromIreland added the needs backport to 3.14 bugs and security fixes label Oct 16, 2026

StanFromIreland added the needs backport to 3.15 bugs and security fixes label Oct 16, 2026

bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Oct 16, 2026

bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Oct 16, 2026

Conversation

bazhil commented Oct 3, 2026 • edited by bedevere-app Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot Bot commented Oct 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Oct 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

aisk commented Oct 4, 2026

Uh oh!

bazhil commented Oct 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

StanFromIreland Oct 11, 2026

Choose a reason for hiding this comment

Uh oh!

StanFromIreland Oct 11, 2026

Choose a reason for hiding this comment

Uh oh!

bazhil Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

StanFromIreland Oct 11, 2026

Choose a reason for hiding this comment

Uh oh!

bazhil Oct 12, 2026

Choose a reason for hiding this comment

Uh oh!

StanFromIreland commented Oct 11, 2026

Uh oh!

StanFromIreland commented Oct 12, 2026

Uh oh!

bazhil commented Oct 12, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented Oct 16, 2026

Uh oh!

miss-islington-app Bot commented Oct 16, 2026

Uh oh!

bedevere-app Bot commented Oct 16, 2026

Uh oh!

bedevere-app Bot commented Oct 16, 2026

Uh oh!

bazhil commented Oct 16, 2026

Uh oh!

bedevere-bot commented Oct 16, 2026

⚠️⚠️⚠️ Buildbot failure ⚠️⚠️⚠️

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bazhil commented Oct 3, 2026 •

edited by bedevere-app Bot

Loading

python-cla-bot Bot commented Oct 3, 2026 •

edited

Loading

read-the-docs-community Bot commented Oct 3, 2026 •

edited

Loading

bazhil commented Oct 4, 2026 •

edited

Loading