diff --git a/Doc/library/test.rst b/Doc/library/test.rst index 765811eba32fd40..b4809fdd66c1834 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 ` 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. @@ -882,9 +884,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 e9fc4cca229a031..1d08b3e127d24fd 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 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')):