CPython's testing infrastructure is a multi-layered system designed to ensure the stability of the Python interpreter and its standard library across diverse platforms. The system ranges from low-level test support utilities to a comprehensive regression suite runner and the standard unittest framework.
The primary entry point for running the full suite is the test package, typically invoked via python -m test Lib/test/libregrtest/cmdline.py10-12
The testing stack is organized into three main layers:
libregrtest, which manages test discovery, execution environment, and parallelization Lib/test/libregrtest/main.py33-55unittest and unittest.mock libraries Lib/test/support/__init__.py20test.support package provides CPython-specific utilities for handling resources, platform-specific skips, and environment isolation Lib/test/support/__init__.py1-78The following diagram maps high-level testing concepts to their implementation entities in the codebase.
Testing Infrastructure Entity Map
Sources: Lib/test/libregrtest/main.py33-55 Lib/test/libregrtest/cmdline.py14-15 Lib/test/support/__init__.py20 Lib/test/libregrtest/run_workers.py107-136
The libregrtest framework is the engine behind CPython's regression testing. It is responsible for finding tests (usually files prefixed with test_ in Lib/test/) and executing them while monitoring for side effects like memory leaks or environment changes Lib/test/libregrtest/main.py172-184 Lib/test/libregrtest/utils.py143-187
Key features include:
-j flag, managed by WorkerThread Lib/test/libregrtest/main.py93-101 Lib/test/libregrtest/run_workers.py107-110-R flag, which initializes HuntRefleak to monitor sys.gettotalrefcount() Lib/test/libregrtest/main.py116-119 Lib/test/libregrtest/runtests.py20regrtest_unraisable_hook Lib/test/libregrtest/utils.py143-157setup_pgo_tests Lib/test/libregrtest/pgo.py17 or Thread Sanitizer (TSAN) tests via setup_tsan_tests Lib/test/libregrtest/tsan.py23For details, see Regression Test Runner.
test.support)The test.support package is a collection of specialized tools required for testing a language interpreter. It abstracts away platform differences and provides decorators to skip tests based on available features.
| Utility Type | Examples | Purpose |
|---|---|---|
| Resource Guards | requires_working_socket | Ensures tests only run if specific hardware or network access is enabled Lib/test/test_support.py164 Lib/test/support/__init__.py42 |
| Platform Checks | is_android, is_apple_mobile | Identifies the execution environment to apply platform-specific logic Lib/test/support/__init__.py51-52 |
| Environment | temp_dir, unlink, rmtree | Isolates I/O and temporary file creation Lib/test/test_support.py116-145 Lib/test/test_support.py184-198 |
| Module Handling | import_module, unload, forget | Manages sys.modules state to ensure clean imports Lib/test/test_support.py87-93 Lib/test/test_support.py110-115 |
Sources: Lib/test/support/__init__.py24-78 Lib/test/test_support.py87-198 Lib/test/libregrtest/utils.py34-36
CPython uses the standard unittest framework as its base. For isolating components, the unittest.mock library provides Mock, MagicMock, and AsyncMock to replace parts of the system. The patch utility handles the temporary replacement of module and class level attributes.
The interaction between the runner and the framework is depicted below:
Execution Flow: Runner to TestCase
Sources: Lib/test/libregrtest/main.py33-110 Lib/test/libregrtest/run_workers.py74-79 Lib/test/libregrtest/results.py19-20 Lib/test/support/__init__.py20
For details, see unittest Framework and Mock Library.
Beyond Python-level tests, CPython includes specialized C extension modules to test internal APIs that are not exposed to regular Python code.
_testcapi: Provides get_process_memory_usage to track memory footprint during regression tests Lib/test/libregrtest/utils.py23-25_colorize: Used by the test runner to provide colorized output for test results Lib/test/libregrtest/main.py9resource: The C-level Modules/resource.c provides access to system resource limits (RLIMIT) which are verified in Lib/test/test_resource.py Modules/resource.c1-20 Lib/test/test_resource.py12-14Sources: Lib/test/libregrtest/utils.py23-25 Lib/test/libregrtest/main.py9 Lib/test/test_resource.py8-12