From 7466a23da6d91b12e287962809991a8cbc150cdf Mon Sep 17 00:00:00 2001 From: Harshit S Gowda Date: Sat, 3 Oct 2026 19:38:58 +0530 Subject: [PATCH 1/3] docs: recommend parallel test execution --- testing/run-write-tests.rst | 31 ++++++------------------------- 1 file changed, 6 insertions(+), 25 deletions(-) diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 405d10f039..45d41518a4 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -17,21 +17,21 @@ Running and writing tests Running ======= -The shortest, simplest way of running the test suite is the following command -from the root directory of your checkout (after you have -:ref:`built Python `): +The shortest, simplest way of running the test suite is the following command, +which runs tests in parallel, from the root directory of your checkout +(after you have :ref:`built Python `): .. tab:: Unix .. code-block:: shell - ./python -m test + ./python -m test -j0 .. tab:: macOS .. code-block:: shell - ./python.exe -m test + ./python.exe -m test -j0 This works on :ref:`most ` macOS systems. @@ -39,7 +39,7 @@ from the root directory of your checkout (after you have .. code-block:: dosbatch - .\python.bat -m test + .\python.bat -m test -j0 This will run the majority of tests, but exclude a small portion of them; these excluded tests use special kinds of resources: for example, accessing the @@ -139,26 +139,7 @@ But, there are several important notes: In other words: if some module does not have ``unittest.main()``, then most likely it does not support direct invocation. -If you have a multi-core or multi-CPU machine, you can enable parallel testing -using several Python processes so as to speed up things: - -.. tab:: Unix - - .. code-block:: shell - - ./python -m test -j0 - -.. tab:: macOS - - .. code-block:: shell - - ./python.exe -m test -j0 -.. tab:: Windows - - .. code-block:: dosbatch - - .\python.bat -m test -j0 .. _strenuous_testing: From 7ada3c74389b10e175c979d87f4a34aa11a3ba88 Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 27 Oct 2026 12:58:17 +0000 Subject: [PATCH 2/3] Add section on running tests sequentially --- testing/run-write-tests.rst | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 45d41518a4..50acea44bb 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -139,7 +139,31 @@ But, there are several important notes: In other words: if some module does not have ``unittest.main()``, then most likely it does not support direct invocation. +By default, ``-j0`` runs tests in parallel using one worker process per CPU, +which is much faster but can interleave output from different tests. +To run tests sequentially, for example when debugging a failure, +drop the ``-j`` flag: +.. tab:: Unix + + .. code-block:: shell + + ./python -m test + +.. tab:: macOS + + .. code-block:: shell + + ./python.exe -m test + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m test + +To limit how many tests run at once, pass an explicit number of +worker processes instead, such as ``-j2``. .. _strenuous_testing: From 519d915509c78c5d4475779950e1e779fb7d4fca Mon Sep 17 00:00:00 2001 From: Stan Ulbrych Date: Tue, 27 Oct 2026 19:18:15 +0000 Subject: [PATCH 3/3] Apply Zach's suggestion Co-Authored-By: Zachary Ware --- testing/run-write-tests.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 50acea44bb..c7c36a7ba1 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -139,10 +139,10 @@ But, there are several important notes: In other words: if some module does not have ``unittest.main()``, then most likely it does not support direct invocation. -By default, ``-j0`` runs tests in parallel using one worker process per CPU, -which is much faster but can interleave output from different tests. -To run tests sequentially, for example when debugging a failure, -drop the ``-j`` flag: +By default, ``-j0`` runs tests in parallel using a number of worker processes +based on the CPU count, which is much faster but can interleave output +from different tests. To run tests sequentially, for example when debugging +a failure, drop the ``-j`` flag: .. tab:: Unix