Testing Infrastructure

Relevant source files

• Doc/library/difflib.rst
• Doc/library/pprint.rst
• Doc/library/test.rst
• Doc/library/unittest.mock.rst
• Doc/tutorial/stdlib2.rst
• Lib/asyncio/coroutines.py
• Lib/compileall.py
• Lib/difflib.py
• Lib/pprint.py
• Lib/py_compile.py
• Lib/test/_isolated_sample.py
• Lib/test/libregrtest/cmdline.py
• Lib/test/libregrtest/main.py
• Lib/test/libregrtest/utils.py
• Lib/test/support/isolation.py
• Lib/test/support/os_helper.py
• Lib/test/support/subprocess_runner.py
• Lib/test/test_asyncio/test_pep492.py
• Lib/test/test_compileall.py
• Lib/test/test_descrtut.py
• Lib/test/test_difflib.py
• Lib/test/test_difflib_expect.html
• Lib/test/test_importlib/source/test_file_loader.py
• Lib/test/test_pprint.py
• Lib/test/test_py_compile.py
• Lib/test/test_regrtest.py
• Lib/test/test_support.py
• Lib/test/test_unittest/testmock/support.py
• Lib/test/test_unittest/testmock/testhelpers.py
• Lib/test/test_unittest/testmock/testmagicmethods.py
• Lib/test/test_unittest/testmock/testmock.py
• Lib/test/test_unittest/testmock/testpatch.py
• Lib/test/test_unittest/testmock/testthreadingmock.py
• Lib/test/test_xpickle.py
• Lib/test/xpickle_worker.py
• Lib/unittest/mock.py
• Misc/NEWS.d/next/Documentation/2026-07-17-22-33-43.gh-issue-118150.m7iFdP.rst
• Misc/NEWS.d/next/Library/2026-04-26-11-25-38.gh-issue-118158.xIy05H.rst
• Misc/NEWS.d/next/Library/2026-05-09-15-42-54.gh-issue-149600.ZbL-iv.rst
• Misc/NEWS.d/next/Library/2026-05-21-11-25-58.gh-issue-150175.8H4Caz.rst
• Misc/NEWS.d/next/Library/2026-07-29-11-05-00.gh-issue-151728.Kq3vTn.rst
• Misc/NEWS.d/next/Tests/2026-06-29-10-14-09.gh-issue-152548.Khw9J7.rst

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

Architecture Overview

The testing stack is organized into three main layers:

1. Runner Layer: Handled by libregrtest, which manages test discovery, execution environment, and parallelization Lib/test/libregrtest/main.py33-55
2. Framework Layer: Built on the standard unittest and unittest.mock libraries Lib/test/test_support.py18 Lib/unittest/mock.py1-24
3. Support Layer: The test.support package provides CPython-specific utilities for handling resources, platform-specific skips, and environment isolation Lib/test/test_support.py21-28

System Component Mapping

The 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/test_support.py21-28 Lib/test/test_regrtest.py28-34

---

Regression Test Runner (libregrtest)

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.py167-184 Lib/test/libregrtest/utils.py142-187

Key features include:

• Parallel Execution: Running tests in multiple worker processes using the -j flag Lib/test/libregrtest/main.py93-101
• Refleak Detection: Tracking reference count leaks using the -R flag, which initializes HuntRefleak to monitor sys.gettotalrefcount() across multiple runs Lib/test/libregrtest/main.py111-116 Lib/test/libregrtest/runtests.py20
• Environment Isolation: Ensuring tests do not permanently alter global state, managed by setup_process and setup_test_dir Lib/test/libregrtest/main.py21 Lib/test/libregrtest/utils.py188-251
• Specialized Test Sets: Infrastructure for running specific subsets like Profile Guided Optimization (PGO) tests via setup_pgo_tests Lib/test/libregrtest/pgo.py17 or Thread Sanitizer (TSAN) tests via setup_tsan_tests Lib/test/libregrtest/tsan.py23

For details, see Regression Test Runner.

---

Test Support Utilities (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
Platform Checks	is_android, is_apple_mobile	Identifies the execution environment to apply platform-specific logic Lib/test/test_support.py100
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/test_support.py21-28 Lib/test/libregrtest/utils.py34-35 Lib/test/libregrtest/utils.py6

---

unittest and Mock Library

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 Lib/unittest/mock.py7-24 The patch utility handles the temporary replacement of module and class level attributes Lib/unittest/mock.py10

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/result.py18-20 Lib/test/test_support.py18 Lib/unittest/mock.py1-24

For details, see unittest Framework and Mock Library.

---

Internal C API Testing

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.py9
• difflib: Used extensively in testing for generating human-readable deltas between expected and actual output Lib/difflib.py1-27

Sources: Lib/test/libregrtest/utils.py23-25 Lib/test/libregrtest/main.py9 Lib/difflib.py1-27