Recommend running the test suite in parallel (#1917)

Co-authored-by: Stan Ulbrych <stan@python.org>
Co-authored-by: Zachary Ware <zach@python.org>

Author: 3 people

testing/run-write-tests.rst

@@ -17,29 +17,29 @@ 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 <compiling>`):
+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 <compiling>`):
 
 .. 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 <mac-python.exe>` macOS systems.
 
 .. tab:: Windows
 
     .. 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,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.
 
-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:
+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
 
     .. code-block:: shell
 
-        ./python -m test -j0
+        ./python -m test
 
 .. tab:: macOS
 
     .. code-block:: shell
 
-        ./python.exe -m test -j0
+        ./python.exe -m test
 
 .. tab:: Windows
 
     .. code-block:: dosbatch
 
-        .\python.bat -m test -j0
+        .\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: