gh-152548: Add a test.support.isolated() decorator by serhiy-storchaka · Pull Request #152551 · python/cpython

serhiy-storchaka · 2026-06-29T07:21:37Z

Add test.support.isolated(), a decorator to run a test method or a whole TestCase subclass in a fresh interpreter subprocess, isolated from the rest of the test run.

Decorates a test method (only that method runs in a subprocess) or a TestCase subclass (the whole class runs in a single subprocess, so setUpClass()/setUpModule() run once there).
Failures, errors and skips — including those of individual subTest()s — are reported for the corresponding test and show the original subprocess traceback. A setUpClass()/setUpModule() failure or skip is reported for the whole class.
The subprocess inherits the parent's resource (-u), memory-limit (-M) and verbosity (-v) configuration, so requires_resource(), requires(), bigmemtest() and similar behave the same in both processes.
test.support.running_isolated is true while running in the subprocess, so fixtures can choose what to run there.

🤖 Generated with Claude Code

Issue: Add a decorator to run a test in an isolated subprocess #152548

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>

Fixes the ruff F401 "imported but unused" lint failure for the re-exports. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

read-the-docs-community · 2026-06-29T07:47:06Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #33352368 | 📁 Comparing 4aa316a against main (2670cb0)

🔍 Preview build

6 files changed · ± 6 modified

± Modified

@isolated

@isolated() always runs the test in a subprocess, so skip it in the parent process on platforms that lack subprocess support, the same way the tests it replaces were guarded by requires_subprocess(). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

encukou

Adding some thoughts as I read this.

I'm not convinced that this feature is worth the complexity.
(I'm also not convinced that it's complete -- but for an internal testing helper, that's OK.)

encukou · 2026-06-29T13:52:14Z

+# 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


Does this need to be support.isolated? Regrtest has been moving toward more granular helpers; this could be e.g. support.isolation.isolated.

If it needs to stay in this namespace, why are the imports not at the start of the file?

encukou · 2026-06-29T13:59:38Z

+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)


Maybe use newer syntax here?

encukou · 2026-06-29T14:05:52Z

+    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') \


Per PEP 8, prefer parentheses over the backslash.

encukou · 2026-06-29T14:13:02Z

+def _check_subprocess_support():
+    # isolated() always runs the test in a subprocess, so skip (in the parent)
+    # on platforms that do not support spawning one.
+    import test.support as support
+    if not support.has_subprocess_support:
+        raise unittest.SkipTest('requires subprocess support')


Skipping tests on platforms without subprocsess support looks dangerous to me: it's not obvious at all that @isolated will do that, so I worry people will apply the decorator to tests that don't strictly need it.
Perhaps name it @run_in_subprocess, or require @skipIf(not has_subprocess_support in call sites?

run_in_subprocess was the initial name. I changed it to reflect the purpose rather than mechanism. It also better fits unittest which already have IsolatedAsyncTestCase and in general do not use snake_case.

The final destination for this feature is unittest. I placed it in test.support first for two reasons. 1) to test and dogfeed it, 2) to simplify backports. But in future it will be moved to unittest.

I can move it to the test.support submodule for now.

Making it failing instead of skipping if subprocess is not available will just require every use to be decorated with require_resources('subprocess'). This will just add boilerplate, which this feature purposes to eliminate.

Tests which run code in subprocesses already skipped if subprocess is not supported. This decorator will replace asser_python_ok with hand-written scripts in which you cannot even use assertEqual.

encukou · 2026-06-29T14:16:46Z

+    orig_setUpClass = cls.setUpClass.__func__
+    orig_tearDownClass = cls.tearDownClass.__func__


What's the __func__ for? Could this use the bound classmethod?

encukou · 2026-06-29T14:21:52Z

+    The test is skipped on platforms without subprocess support.
+    """
+    def decorator(obj):
+        if isinstance(obj, type):


Should this be unittest.TestCase, as per the docstring?

encukou · 2026-06-29T14:30:50Z

+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]
+


This will ignore any other outcomes, like expectedFailures.
Also, collectedDurations isn't preserved.

encukou · 2026-06-29T14:36:14Z

+   Fixtures can test :data:`running_isolated` to decide what to run in each
+   process.


The added docs repeat this 3 times.

encukou · 2026-06-29T14:37:46Z

+   :meth:`~unittest.TestCase.setUp` and :meth:`~unittest.TestCase.tearDown`
+   run both in the parent process (as usual) and in the subprocess around the


Same for all the other fixtures, right?

bedevere-app Bot mentioned this pull request Jun 29, 2026

Add a decorator to run a test in an isolated subprocess #152548

Open

bedevere-app Bot added the awaiting core review label Jun 29, 2026

serhiy-storchaka requested review from encukou and vstinner June 29, 2026 07:23

serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jun 29, 2026

serhiy-storchaka force-pushed the test-run_in_subprocess branch from 560e882 to 2d5b380 Compare June 29, 2026 07:27

Add isolated() and running_isolated to test.support.__all__

bcc35ee

Fixes the ruff F401 "imported but unused" lint failure for the re-exports. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

This was referenced Jun 29, 2026

gh-152548: Convert test_audit to the test.support.isolated() decorator #152565

Open

gh-152548: Convert test_eintr to the test.support.isolated() decorator #152570

Open

encukou reviewed Jun 29, 2026

View reviewed changes

		orig_setUpClass = cls.setUpClass.__func__
		orig_tearDownClass = cls.tearDownClass.__func__

		Fixtures can test :data:`running_isolated` to decide what to run in each
		process.

		:meth:`~unittest.TestCase.setUp` and :meth:`~unittest.TestCase.tearDown`
		run both in the parent process (as usual) and in the subprocess around the

Uh oh!

Uh oh!

Conversation

serhiy-storchaka commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

serhiy-storchaka commented Jun 29, 2026 •

edited

Loading

read-the-docs-community Bot commented Jun 29, 2026 •

edited

Loading