Testing

CPython has roughly 750+ test modules under Lib/test/, driven by an in-tree harness called regrtest. The harness is Lib/test/regrtest.py and its implementation is in Lib/test/libregrtest/. On top of regrtest, individual modules use unittest.TestCase.

Running tests

Always run tests through the in-tree interpreter (./python or ./python.exe), never against a system Python:

./python -m test                       # whole suite, default workers
./python -m test test_os               # one test module
./python -m test test_os test_socket   # several
./python -m test -j$(nproc)            # parallel
./python -m test -v test_os            # verbose
./python -m test -W test_os            # re-run failures verbosely
./python -m test -uall                 # enable all resource categories
./python -m test -ucpu,network         # specific resource categories
./python -m test --pgo                 # the trimmed PGO training set
./python -m test --testdir Lib/test    # for out-of-tree tests
./python -m test -F test_os            # repeat until failure (flaky chasing)
./python -m test --fail-rerun -j8      # rerun the failures of a previous run

make test is roughly ./python -m test; make buildbottest is ./python -m test -j8 -uall -rwW.

Resource categories

Some tests are gated on resources because they are slow or have side effects:

Category	What it gates
audio	Tests that need /dev/dsp or audio hardware.
cpu	Long-running CPU-bound tests.
network	Tests that contact the internet.
urlfetch	Tests that fetch real URLs (subset of network).
largefile	Tests that allocate >1GB.
decimal	Long-running decimal tests.
gui	Tests that need a display.
subprocess	Tests that exec other processes.
extralargefile	Tests that allocate >2GB.
tzdata	Needs the system tzdata package.

-uall enables everything; this is what buildbots use.

Writing tests

The convention for module foo:

• Add or extend Lib/test/test_foo.py.
• Each test class subclasses unittest.TestCase.
• Use the helpers in Lib/test/support/ — they are extensive: os_helper, socket_helper, import_helper, script_helper, warnings_helper, threading_helper, etc. They handle resource gating, temporary files, requirement skipping, and OS quirks.
• For tests that exercise the interpreter or compiler internals, look at test/test_capi/, test/test_compile.py, and test/test_dis.py for patterns.

A small example:

import unittest
from test.support import os_helper

class MyTests(unittest.TestCase):
    def setUp(self):
        self.tmp = os_helper.mkdtemp()
        self.addCleanup(os_helper.rmtree, self.tmp)

    def test_something(self):
        self.assertEqual(1 + 1, 2)

C-API tests

C-API surface is tested through three internal modules:

Module	Source	Purpose
_testcapi	Modules/_testcapi/, Modules/_testcapimodule.c	Public C API (non-stable).
_testlimitedcapi	Modules/_testlimitedcapi/	The Stable ABI / Limited C API.
_testinternalcapi	Modules/_testinternalcapi.c, Modules/_testinternalcapi/	Interpreter-internal helpers used by Python tests under test_capi/.
_testbuffer	Modules/_testbuffer.c	Buffer protocol.
_testmultiphase / _testsinglephase	Modules/_testmultiphase.c, Modules/_testsinglephase.c	Module init protocol.
_testclinic	Modules/_testclinic.c	Argument Clinic edge cases.

The Python tests that exercise these live under Lib/test/test_capi/.

Performance and stress

• Lib/test/test_capi/test_opt.py — exercises the JIT/uop optimizer (one of the highest-churn test files in the tree).
• Tools/scripts/run_tests.py — the historical wrapper used in CI.
• Lib/test/pythoninfo.py — the body of make pythoninfo.
• Hypothesis is supported but optional (Tools/requirements-hypothesis.txt).
• -Werror runs — many CI jobs run with -Wall -Werror to catch deprecation warnings; if your change adds new warnings the CI lint job will fail.

Sanitizers and special builds

CPython has dedicated CI configurations for:

Build	Configured by
ASan	.github/workflows/reusable-san.yml
TSan	Tools/tsan/, same workflow
UBSan	Tools/ubsan/, same workflow
Emscripten / WASI	Tools/wasm/, .github/workflows/reusable-emscripten.yml, .github/workflows/reusable-wasi.yml
JIT	Tools/jit/, .github/workflows/jit.yml
Free-threaded (--disable-gil)	Standard Linux/macOS workflows with the flag.

Skipping vs xfailing

• unittest.skipIf(...) — for genuine "doesn't apply on this platform".
• unittest.expectedFailure — for known broken things you want CI to track.
• support.requires(...) — for resource-gated tests (requires('network')).
• support.skip_if_buggy_ucrt_strfptime(), support.skip_unless_symlink(), … — many helpers in Lib/test/support/.

Common debugging recipes

• A test hangs: ./python -m test --timeout 60 -v test_X then attach gdb to the process. See Debugging.
• A test passes alone but fails in the suite: leak between tests. Run with -R 3:3:reflog to dump a refcount diff between runs (debug build only).
• A test fails only with -uall: a resource-gated test is the actual culprit; bisect by removing categories.
• A test fails only on the JIT build: the optimizer probably picked a wrong specialization. See JIT for the de-opt mechanism, and _testinternalcapi.set_optimizer(None) to disable tier 2 in tests.