gh-158681: Document that regrtest rejects test_main() and loads unittest suites

[bazhil]

#158681

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

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34931084 | 📁 Comparing 58b6171 against main (1b015e6)

  🔍 Preview build  

2 files changed

± library/test.html
± whatsnew/changelog.html

[aisk]

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

[bazhil]

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

Fixed