@@ -963,6 +963,59 @@ The :mod:`!test.support` module defines the following functions:
963963 :mod: `tracemalloc ` is enabled.
964964
965965
966+ .. currentmodule :: test.support.isolation
967+
968+ .. decorator :: runInSubprocess()
969+
970+ Decorator that runs the decorated test in a fresh interpreter subprocess, in
971+ isolation, so that it does not share global or interpreter state with the
972+ rest of the test run. It can decorate a test method or a whole
973+ :class: `~unittest.TestCase ` subclass. Decorated methods must take no extra
974+ arguments. A failure, error or skip in the subprocess is reported for the
975+ corresponding test, and individual :meth: `subtests
976+ <unittest.TestCase.subTest> ` that fail or are skipped are reported
977+ individually. A reported failure or error shows the original subprocess
978+ traceback as the cause of the exception.
979+
980+ When a **method ** is decorated, only that method runs in a subprocess; all
981+ fixtures (:meth: `~unittest.TestCase.setUp ` / :meth: `~unittest.TestCase.tearDown `,
982+ :meth: `~unittest.TestCase.setUpClass ` / :meth: `~unittest.TestCase.tearDownClass `
983+ and ``setUpModule() `` / ``tearDownModule() ``) run both in the parent process
984+ (as usual) and in the subprocess around the method.
985+
986+ When a **class ** is decorated, the whole class runs in a single subprocess,
987+ and :meth: `~unittest.TestCase.setUpClass `,
988+ :meth: `~unittest.TestCase.tearDownClass `, :meth: `~unittest.TestCase.setUp `
989+ and :meth: `~unittest.TestCase.tearDown ` run once each in the subprocess and
990+ are skipped in the parent process. A failure or skip of
991+ :meth: `~unittest.TestCase.setUpClass ` in the subprocess is reported for the
992+ whole class. ``setUpModule() `` cannot be controlled by a class decorator,
993+ so it still runs in the parent process too; test it with
994+ :data: `runningInSubprocess ` if needed.
995+
996+ The subprocess inherits the enabled resources (``-u ``), memory limit
997+ (``-M ``) and verbosity (``-v ``) of the parent test run, so that
998+ :func: `~test.support.requires_resource `, :func: `~test.support.requires `,
999+ :func: `~test.support.bigmemtest ` and the like behave consistently in both
1000+ processes.
1001+
1002+ The test is skipped on platforms without subprocess support.
1003+
1004+
1005+ .. data :: runningInSubprocess
1006+
1007+ ``True `` while the code runs in the isolated subprocess spawned by
1008+ :func: `runInSubprocess `, and ``False `` otherwise (including in the parent
1009+ process and in a normal, non-isolated test run). Fixtures such as
1010+ :meth: `~unittest.TestCase.setUp `, :meth: `~unittest.TestCase.tearDown `,
1011+ :meth: `~unittest.TestCase.setUpClass `, :meth: `~unittest.TestCase.tearDownClass `,
1012+ ``setUpModule() `` and ``tearDownModule() `` can test it to choose which code
1013+ to run in the subprocess.
1014+
1015+
1016+ .. currentmodule :: test.support
1017+
1018+
9661019.. function :: check_free_after_iterating(test, iter, cls, args=())
9671020
9681021 Assert instances of *cls * are deallocated after iterating.
0 commit comments