From b6bc98e1ac28d4bd891cbfe770bc3245cc53aed6 Mon Sep 17 00:00:00 2001
From: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com>
Date: Fri, 16 Oct 2026 23:19:02 +0300
Subject: [PATCH] gh-158681: Document that regrtest no longer supports
 `test_main()` (GH-158682) (cherry picked from commit
 75ce53d3e2f10347080ab466b936ae070f1c5a94)

Co-authored-by: Ilya Bazhenov <31971067+bazhil@users.noreply.github.com>
---
 Doc/library/test.rst         | 20 ++++++++++++--------
 Lib/test/support/__init__.py |  8 ++++----
 2 files changed, 16 insertions(+), 12 deletions(-)

diff --git a/Doc/library/test.rst b/Doc/library/test.rst
index 72ffc2a0b760ea..806f1f364ca48f 100644
--- a/Doc/library/test.rst
+++ b/Doc/library/test.rst
@@ -165,11 +165,13 @@ 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`. 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
 regression test (:program:`python -m test test_spam`) will minimize output and
 only print whether the test passed or failed.
 
@@ -881,9 +883,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 :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.
 
 
 .. function:: get_attribute(obj, name)
diff --git a/Lib/test/support/__init__.py b/Lib/test/support/__init__.py
index 03f1a068b2e922..eb2a44fd7d86bb 100644
--- a/Lib/test/support/__init__.py
+++ b/Lib/test/support/__init__.py
@@ -1536,10 +1536,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 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.
     """
     # Need os.waitpid(-1, os.WNOHANG): Windows is not supported
     if not (hasattr(os, 'waitpid') and hasattr(os, 'WNOHANG')):