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

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

Add test.support.isolation.runInSubprocess(), a decorator to 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.

Decorates a test method (only that method runs in a subprocess) or a TestCase subclass (the whole class runs in a single subprocess, with its setUpClass()/setUp()/tearDown()/tearDownClass() running there rather than in the parent).
Failures, errors and skips — including those of individual subTest()s — are reported for the corresponding test; a failure or an error shows 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), verbosity (-v) and failfast (-f) configuration, so requires_resource(), requires(), bigmemtest() and similar behave the same in both processes.
A decorated test is skipped where subprocesses are unavailable, since it must spawn one.
test.support.isolation.runningInSubprocess is true while running in the subprocess, so fixtures can choose what to run there.

Demonstrated by three stacked PRs converting existing tests: #152565 (test_audit), #152570 (test_eintr) and #152639 (test_signal).

🤖 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 #33783890 | 📁 Comparing 085c7f1 against main (2670cb0)

🔍 Preview build

143 files changed · + 3 added · ± 140 modified

+ Added

± 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.

run_in_subprocess was the initial name. I changed it to reflect the purpose rather than mechanism.

But, “hiding” the mechanism obscures the fact that the tests are (now silently) skipped if subprocesses aren't available. I don't think that's acceptable.

It could be @isolation.run_in_subprocess(), or @isolated(subprocess=True), or fail rather than skip (so a decorator is necessary).

Tests which run code in subprocesses already skipped if subprocess is not supported. This decorator will replace assert_python_ok

But, assert_python_ok usage makes it clear that a subprocess is involved. @isolated hides that in docs.

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?

This is for subclasses. A bound classmethod is bound to the decoration-time class. At run time, we need to run a method bound to a run-time class.

Added an explanation comment.

A test would be good too, especially if you want to put this in unittest.

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?

@expectedfailure

Move the helper into a public test.support.isolation submodule (used as "from test.support import isolation"), drop the test.support re-export, and document running_isolated and isolated() under that module. Replay expected failures and forward subprocess durations to the parent, so an @expectedfailure isolated test is no longer misreported as an unexpected success and reported timings reflect the subprocess run. Add test.test_support.TestIsolated covering the outcomes, subtest reporting, traceback-as-cause, duration forwarding and the no-subprocess skip. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

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

…eview Rename the decorator to runInSubprocess() and the flag to runningInSubprocess so the subprocess mechanism (and the skip when it is unavailable) is explicit. Suppress Windows CRT assertion dialogs in the isolated child so a debug build does not hang on a modal dialog, and add a subclass fixture-binding test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

serhiy-storchaka · 2026-07-27T06:50:44Z

I need this feature for the curses tests on NetBSD and Windows (they only work with one terminal per process).

encukou

Thanks!
Let's start using this internally.

serhiy-storchaka · 2026-07-27T16:51:43Z

Thank you for your review.

… child output Hook the unittest _call*() indirections instead of replacing the test methods and fixtures found at decoration time, so that what a subclass of an isolated class adds or overrides also runs in the subprocess, and report an error when an overriding setUpClass() bypasses the subprocess altogether. Pass the configuration to the child on the command line instead of the environment: the child is marked as the subprocess in-process, so it can never spawn one in turn, and the marker is no longer inherited by processes that the test itself spawns. Decode the output of the child explicitly, so that an undecodable byte cannot hide the failure it is part of. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…fore the test Every module imported before the test runs is state that the test would not see in a normal test run. Serialize with marshal instead of json, since it is built in, and resolve the qualname in the imported module instead of letting loadTestsFromName() find it by trying imports that fail, which pulls in importlib.resources. The child now imports nothing that a normal test run does not, and starts in 63 ms instead of 111 ms. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

miss-islington-app · 2026-07-27T19:03:03Z

Thanks @serhiy-storchaka for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

miss-islington-app · 2026-07-27T19:03:13Z

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker bde526d7be55014ec49fd44b831c948664ce508b 3.14

bedevere-app · 2026-07-27T19:03:17Z

GH-154780 is a backport of this pull request to the 3.15 branch.

miss-islington-app · 2026-07-27T19:03:18Z

Sorry, @serhiy-storchaka, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker bde526d7be55014ec49fd44b831c948664ce508b 3.13

bedevere-app · 2026-07-27T19:42:27Z

GH-154783 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2026-07-27T19:42:27Z

GH-154784 is a backport of this pull request to the 3.13 branch.

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.isolation.runInSubprocess() decorator #152565

Open

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

Open

encukou reviewed Jun 29, 2026

View reviewed changes

serhiy-storchaka mentioned this pull request Jun 29, 2026

gh-152548: Convert the test_signal wakeup tests to @runInSubprocess() #152639

Open

serhiy-storchaka and others added 2 commits June 30, 2026 14:49

pythongh-152548: Fix the NEWS reference to the renamed isolated() dec…

63ccc24

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

johnslavik self-requested a review July 27, 2026 08:15

encukou approved these changes Jul 27, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Jul 27, 2026

serhiy-storchaka and others added 2 commits July 27, 2026 21:07

serhiy-storchaka enabled auto-merge (squash) July 27, 2026 18:40

serhiy-storchaka changed the title ~~gh-152548: Add a test.support.isolated() decorator~~ gh-152548: Add the test.support.isolation.runInSubprocess() decorator Jul 27, 2026

serhiy-storchaka merged commit bde526d into python:main Jul 27, 2026
50 checks passed

bedevere-app Bot removed the awaiting merge label Jul 27, 2026

miss-islington-app Bot assigned serhiy-storchaka Jul 27, 2026

bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jul 27, 2026

This was referenced Jul 27, 2026

[3.14] gh-152548: Add a test.support.isolation.runInSubprocess() decorator (GH-152551) #154783

Open

[3.13] gh-152548: Add a test.support.isolation.runInSubprocess() decorator (GH-152551) #154784

Open

bedevere-app Bot removed needs backport to 3.14 bugs and security fixes needs backport to 3.13 bugs and security fixes labels Jul 27, 2026

		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!

encukou Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

serhiy-storchaka commented Jul 27, 2026

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

serhiy-storchaka commented Jul 27, 2026

Uh oh!

Uh oh!

miss-islington-app Bot commented Jul 27, 2026

Uh oh!

miss-islington-app Bot commented Jul 27, 2026

Uh oh!

bedevere-app Bot commented Jul 27, 2026

Uh oh!

miss-islington-app Bot commented Jul 27, 2026

Uh oh!

bedevere-app Bot commented Jul 27, 2026

Uh oh!

bedevere-app Bot commented Jul 27, 2026

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

encukou Jun 30, 2026 •

edited

Loading