Add a test.support.isolated() decorator

Run a test in a fresh interpreter subprocess, so that it does not share global
or interpreter state with the rest of the test run.  It can decorate a test
method (only that method runs in a subprocess) or a TestCase subclass (the
whole class runs in one subprocess, with its setUpClass()/setUp()/tearDown()/
tearDownClass() running once there).

Failures, errors and skips, including those of individual subtests, are
reported for the test and show the original subprocess traceback.  The
subprocess inherits the parent's resource, memory and verbosity configuration,
so that requires_resource(), bigmemtest() and similar behave the same in both
processes.

The test.support.running_isolated flag is true in the subprocess, so that
fixtures can choose what to run there.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: serhiy-storchaka

Doc/library/test.rst

@@ -961,6 +961,53 @@ The :mod:`!test.support` module defines the following functions:
    :mod:`tracemalloc` is enabled.
 
 
+.. decorator:: isolated()
+
+   Decorator that runs the decorated test in isolation, in a fresh interpreter
+   subprocess, so that it does not share global or interpreter state with the
+   rest of the test run.  It can decorate a test method or a whole
+   :class:`~unittest.TestCase` subclass.  Decorated methods must take no extra
+   arguments.  A failure, error or skip in the subprocess is reported for the
+   corresponding test, and individual :meth:`subtests
+   <unittest.TestCase.subTest>` that fail or are skipped are reported
+   individually.  A reported failure or error shows the original subprocess
+   traceback as the cause of the exception.
+
+   When a **method** is decorated, only that method runs in a subprocess;
+   :meth:`~unittest.TestCase.setUp` and :meth:`~unittest.TestCase.tearDown`
+   run both in the parent process (as usual) and in the subprocess around the
+   method.
+
+   When a **class** is decorated, the whole class runs in a single subprocess,
+   and :meth:`~unittest.TestCase.setUpClass`,
+   :meth:`~unittest.TestCase.tearDownClass`, :meth:`~unittest.TestCase.setUp`
+   and :meth:`~unittest.TestCase.tearDown` run once each in the subprocess and
+   are skipped in the parent process.  A failure or skip of
+   :meth:`~unittest.TestCase.setUpClass` in the subprocess is reported for the
+   whole class.  ``setUpModule()`` cannot be controlled by a class decorator,
+   so it still runs in the parent process too; test it with
+   :data:`running_isolated` if needed.
+
+   Fixtures can test :data:`running_isolated` to decide what to run in each
+   process.
+
+   The subprocess inherits the enabled resources (``-u``), memory limit
+   (``-M``) and verbosity (``-v``) of the parent test run, so that
+   :func:`requires_resource`, :func:`requires`, :func:`bigmemtest` and the like
+   behave consistently in both processes.
+
+
+.. data:: running_isolated
+
+   ``True`` while the code runs in the isolated subprocess spawned by
+   :func:`isolated`, and ``False`` otherwise (including in the parent process
+   and in a normal, non-isolated test run).  Fixtures such as
+   :meth:`~unittest.TestCase.setUp`, :meth:`~unittest.TestCase.tearDown`,
+   :meth:`~unittest.TestCase.setUpClass`, :meth:`~unittest.TestCase.tearDownClass`,
+   ``setUpModule()`` and ``tearDownModule()`` can test it to choose which code
+   to run in the subprocess.
+
+
 .. function:: check_free_after_iterating(test, iter, cls, args=())
 
    Assert instances of *cls* are deallocated after iterating.

Lib/test/support/__init__.py

@@ -1089,6 +1089,12 @@ def wrapper(self, /, *args, **kwargs):
         return wrapper
     return decorator
 
+# Run a test method or class in an isolated subprocess.  Implemented in a
+# dedicated module so that its frames carry the __unittest marker and are
+# stripped from reported tracebacks.
+from test.support._isolation import isolated, running_isolated
+
+
 #=======================================================================
 # Decorator/context manager for running a code in a different locale,
 # correctly resetting it afterwards.

Lib/test/support/_isolation.py

@@ -0,0 +1,251 @@
+"""Run tests in isolated subprocesses (the test.support.isolated decorator).
+
+A failure, error or skip that happens in the subprocess is replayed in the
+parent process so that the test runner records it.  The original (subprocess)
+traceback is attached as the cause of the replayed exception, the same way
+:mod:`concurrent.futures` surfaces tracebacks from worker processes.
+"""
+
+import functools
+import os
+import sys
+import unittest
+
+# Mark this module's frames as belonging to the test machinery, so that
+# unittest strips them from reported tracebacks (see TestResult._clean_tracebacks
+# in Lib/unittest/result.py).  Only the original subprocess traceback, attached
+# as the cause, is then shown -- not the parent-side replay frames.
+__unittest = True
+
+# Environment variable set in the child process so that the decorated test
+# method runs its real body instead of spawning yet another subprocess.
+_RUN_IN_SUBPROCESS_ENV = '_PYTHON_RUN_IN_SUBPROCESS'
+
+# Environment variable carrying (as JSON) the regrtest-configured test.support
+# state, so that the bare subprocess honors -u, -M, -v, etc. like the parent.
+_CONFIG_ENV = '_PYTHON_ISOLATED_CONFIG'
+
+# test.support globals set by regrtest (libregrtest/setup.py) that affect how
+# tests run and which are skipped at runtime in the subprocess.
+_PROPAGATED_CONFIG = (
+    'use_resources',                    # -u (is_resource_enabled/requires)
+    'max_memuse', 'real_max_memuse',    # -M (bigmemtest)
+    'verbose',                          # -v
+    'failfast',                         # -f
+)
+
+def _child_config():
+    import test.support as support
+    return {name: getattr(support, name) for name in _PROPAGATED_CONFIG}
+
+def _apply_child_config():
+    """Mirror the parent's test.support configuration in the subprocess.
+
+    Called by subprocess_runner before loading the test, so that import-time
+    decorators (e.g. requires_resource) and runtime checks see the same -u/-M/-v
+    configuration as the parent process.
+    """
+    import json
+    import test.support as support
+    data = os.environ.get(_CONFIG_ENV)
+    if data:
+        for name, value in json.loads(data).items():
+            setattr(support, name, value)
+
+# True while running inside the isolated subprocess spawned by @isolated().
+# setUp()/tearDown() and the class- and module-level fixtures can test it to
+# decide which code to run in the subprocess as opposed to the parent process.
+running_isolated = bool(os.environ.get(_RUN_IN_SUBPROCESS_ENV))
+
+
+class _RemoteTraceback(Exception):
+    """Carry a formatted traceback string from the subprocess for display.
+
+    Attached as the ``__cause__`` of the replayed failure/error, so that the
+    original traceback is shown by the traceback machinery.
+    """
+    def __init__(self, tb):
+        self.tb = tb
+
+    def __str__(self):
+        return self.tb
+
+
+class _SubprocessTestError(Exception):
+    """Replay a subprocess error (as opposed to a failure) in the parent."""
+
+
+def _remote(detail):
+    # Wrap the subprocess traceback the way concurrent.futures does, so it is
+    # clearly delimited when shown as the cause.
+    return _RemoteTraceback('\n"""\n%s"""' % detail)
+
+
+def _run_in_subprocess(module, qualname):
+    """Run module.qualname (a test method or class) in a fresh subprocess.
+
+    Return ``(outcomes, output, returncode)``, where *outcomes* is the list of
+    test outcomes decoded from the subprocess, or ``None`` if it did not run to
+    completion (crash, import error, ...).
+    """
+    import json
+    import subprocess
+    import tempfile
+    env = dict(os.environ)
+    env[_RUN_IN_SUBPROCESS_ENV] = '1'
+    env[_CONFIG_ENV] = json.dumps(_child_config())
+    fd, result_path = tempfile.mkstemp(suffix='.json')
+    os.close(fd)
+    try:
+        cmd = [sys.executable, '-m', 'test.support.subprocess_runner',
+               module, qualname, result_path]
+        proc = subprocess.run(cmd, capture_output=True, text=True, env=env)
+        try:
+            with open(result_path, encoding='utf-8') as f:
+                outcomes = json.load(f)
+        except (OSError, ValueError):
+            outcomes = None
+    finally:
+        try:
+            os.unlink(result_path)
+        except OSError:
+            pass
+    return outcomes, (proc.stdout or '') + (proc.stderr or ''), proc.returncode
+
+
+def _replay_outcome(test, outcome):
+    kind = outcome['kind']
+    detail = outcome['detail']
+    if kind == 'skipped':
+        test.skipTest(detail)  # the detail is the skip reason, not a traceback
+    elif kind == 'failure':
+        raise test.failureException('test failed in the subprocess') \
+            from _remote(detail)
+    else:  # 'error'
+        raise _SubprocessTestError('test failed in the subprocess') \
+            from _remote(detail)
+
+
+def _replay_outcomes(test, outcomes):
+    # Replay each subtest outcome in its own subTest() context so that they are
+    # reported individually, then replay the whole-test outcome (if any).
+    main = []
+    for outcome in outcomes:
+        if outcome['subtest']:
+            with test.subTest(outcome['desc']):
+                _replay_outcome(test, outcome)
+        else:
+            main.append(outcome)
+    for outcome in main:
+        _replay_outcome(test, outcome)
+
+
+def _raise_fixture_outcome(outcome):
+    # Reproduce a setUpClass()/setUpModule() failure or skip from the
+    # subprocess in a parent-process fixture, so it applies to every test.
+    if outcome['kind'] == 'skipped':
+        raise unittest.SkipTest(outcome['detail'])
+    raise _SubprocessTestError('class failed in the subprocess') \
+        from _remote(outcome['detail'])
+
+
+def _isolate_method(func):
+    @functools.wraps(func)
+    def wrapper(self, /, *args, **kwargs):
+        if running_isolated:
+            # Already running in the subprocess: run the real test.
+            return func(self, *args, **kwargs)
+        cls = type(self)
+        qualname = f'{cls.__qualname__}.{func.__name__}'
+        outcomes, output, returncode = _run_in_subprocess(cls.__module__,
+                                                          qualname)
+        if outcomes is None:
+            raise _SubprocessTestError(
+                f'test did not complete in a subprocess (exit code '
+                f'{returncode})') from _remote(output)
+        _replay_outcomes(self, outcomes)
+    return wrapper
+
+
+def _isolate_class(cls):
+    orig_setUpClass = cls.setUpClass.__func__
+    orig_tearDownClass = cls.tearDownClass.__func__
+    orig_setUp = cls.setUp
+    orig_tearDown = cls.tearDown
+
+    def setUpClass(cls):
+        if running_isolated:
+            orig_setUpClass(cls)
+            return
+        # Run the whole class in a single subprocess and stash the outcomes
+        # for the wrapped test methods to replay.
+        outcomes, output, returncode = _run_in_subprocess(cls.__module__,
+                                                          cls.__qualname__)
+        if outcomes is None:
+            raise _SubprocessTestError(
+                f'class did not complete in a subprocess (exit code '
+                f'{returncode})') from _remote(output)
+        by_id = {}
+        for outcome in outcomes:
+            if outcome['fixture']:
+                # A setUpClass()/setUpModule() failure or skip: apply it to the
+                # whole class by raising it here, in the parent's setUpClass().
+                _raise_fixture_outcome(outcome)
+            by_id.setdefault(outcome['id'], []).append(outcome)
+        cls._isolated_outcomes = by_id
+
+    def tearDownClass(cls):
+        if running_isolated:
+            orig_tearDownClass(cls)
+        else:
+            cls._isolated_outcomes = None
+
+    def setUp(self):
+        # In the parent the real test does not run, so neither should setUp().
+        if running_isolated:
+            orig_setUp(self)
+
+    def tearDown(self):
+        if running_isolated:
+            orig_tearDown(self)
+
+    def replay(self):
+        by_id = getattr(type(self), '_isolated_outcomes', None) or {}
+        _replay_outcomes(self, by_id.get(self.id(), []))
+
+    cls.setUpClass = classmethod(setUpClass)
+    cls.tearDownClass = classmethod(tearDownClass)
+    cls.setUp = setUp
+    cls.tearDown = tearDown
+    for name in unittest.TestLoader().getTestCaseNames(cls):
+        method = getattr(cls, name)
+        @functools.wraps(method)
+        def wrapper(self, /, *args, __func=method, **kwargs):
+            if running_isolated:
+                return __func(self, *args, **kwargs)
+            replay(self)
+        setattr(cls, name, wrapper)
+    return cls
+
+
+def isolated():
+    """Decorator to run a test method or class in isolation from the rest.
+
+    The decorated test runs in a separate, fresh Python process, so it does not
+    share global or interpreter state with the rest of the test run.  When a
+    :class:`~unittest.TestCase` subclass is decorated, the whole class runs in a
+    single subprocess and its ``setUpClass()``/``setUpModule()`` fixtures run
+    once there; when a method is decorated, only that method runs in a
+    subprocess.  Decorated methods must take no extra arguments.
+
+    A failure, error or skip of the whole test is reported for the test, and
+    individual subtests (:meth:`~unittest.TestCase.subTest`) that fail or are
+    skipped are reported individually.  The original subprocess traceback is
+    shown as the cause of a reported failure or error.  Use
+    :data:`running_isolated` in fixtures to choose what to run in the subprocess.
+    """
+    def decorator(obj):
+        if isinstance(obj, type):
+            return _isolate_class(obj)
+        return _isolate_method(obj)
+    return decorator

Lib/test/support/subprocess_runner.py

@@ -0,0 +1,58 @@
+"""Run a single test method in this (sub)process and report the result.
+
+Invoked as ``python -m test.support.subprocess_runner MODULE QUALNAME OUTFILE``
+by :func:`test.support.isolated`.  The outcome of the test (including
+that of each individual subtest) is written as JSON to OUTFILE.  This module is
+not meant to be imported.
+"""
+
+import json
+import sys
+import unittest
+from unittest.case import _SubTest
+
+if __name__ != '__main__':
+    raise ImportError('this module cannot be directly imported')
+
+if len(sys.argv) != 4:
+    print('usage: python -m test.support.subprocess_runner '
+          'MODULE QUALNAME OUTFILE', file=sys.stderr)
+    sys.exit(2)
+
+module = sys.argv[1]
+qualname = sys.argv[2]
+outfile = sys.argv[3]
+
+# Mirror the parent's regrtest configuration (-u, -M, -v, ...) before importing
+# the test, so resource gating and bigmem sizing match the parent process.
+from test.support._isolation import _apply_child_config
+_apply_child_config()
+
+suite = unittest.TestLoader().loadTestsFromName(f'{module}.{qualname}')
+result = unittest.TestResult()
+suite.run(result)
+
+
+def _outcome(kind, test, detail):
+    subtest = isinstance(test, _SubTest)
+    real = test.test_case if subtest else test
+    return {
+        'kind': kind,
+        'subtest': subtest,
+        'desc': test._subDescription() if subtest else '',
+        # id() groups outcomes by test method; a non-TestCase (e.g. an
+        # _ErrorHolder) marks a setUpClass()/setUpModule() fixture failure.
+        'id': real.id(),
+        'fixture': not isinstance(real, unittest.TestCase),
+        'detail': detail,
+    }
+
+
+outcomes = [_outcome('failure', t, tb) for t, tb in result.failures]
+outcomes += [_outcome('error', t, tb) for t, tb in result.errors]
+outcomes += [_outcome('skipped', t, reason) for t, reason in result.skipped]
+
+with open(outfile, 'w', encoding='utf-8') as f:
+    json.dump(outcomes, f)
+
+sys.exit(0)

Misc/NEWS.d/next/Tests/2026-06-29-10-14-09.gh-issue-152548.Khw9J7.rst

@@ -0,0 +1,3 @@
+Add the :func:`test.support.isolated` decorator to run a test method or
+``TestCase`` subclass in a fresh interpreter subprocess, isolated from the rest
+of the test run.