From 82730e5c6c5f01ebb130936332129cfc4ab09291 Mon Sep 17 00:00:00 2001 From: Adam Johnson Date: Fri, 24 Jul 2020 19:46:49 +0100 Subject: [PATCH] Improve description of testing with multiple CPU's Co-authored-by: Bruno Oliveira --- README.rst | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/README.rst b/README.rst index 4c66d8b..ca13819 100644 --- a/README.rst +++ b/README.rst @@ -67,33 +67,35 @@ a checkout of the `pytest-xdist repository`_ :: Speed up test runs by sending tests to multiple CPUs ---------------------------------------------------- -To send tests to multiple CPUs, type:: +To send tests to multiple CPUs, use the ``-n`` (or ``-numprocesses``) option:: - pytest -n NUM + pytest -n NUMCPUS -Especially for longer running tests or tests requiring -a lot of I/O this can lead to considerable speed ups. This option can -also be set to ``auto`` for automatic detection of the number of CPUs. +Pass ``-n auto`` to use as many processes as your computer has CPU cores. This +can lead to considerable speed ups, especially if your test suite takes a +noticeable amount of time. -If a test crashes the interpreter, pytest-xdist will automatically restart -that worker and report the failure as usual. You can use the -``--max-worker-restart`` option to limit the number of workers that can -be restarted, or disable restarting altogether using ``--max-worker-restart=0``. +If a test crashes a worker, pytest-xdist will automatically restart that worker +and report the test’s failure. You can use the ``--max-worker-restart`` option +to limit the number of worker restarts that are allowed, or disable restarting +altogether using ``--max-worker-restart 0``. -By default, the ``-n`` option will send pending tests to any worker that is available, without -any guaranteed order, but you can control this with these options: +By default, using ``--numprocesses`` will send pending tests to any worker that +is available, without any guaranteed order. You can change the test +distribution algorithm this with the ``--dist`` option. It takes these values: -* ``--dist=loadscope``: tests will be grouped by **module** for *test functions* and - by **class** for *test methods*, then each group will be sent to an available worker, - guaranteeing that all tests in a group run in the same process. This can be useful if you have - expensive module-level or class-level fixtures. Currently the groupings can't be customized, - with grouping by class takes priority over grouping by module. - This feature was added in version ``1.19``. +* ``--dist no``: The default algorithm, distributing one test at a time. -* ``--dist=loadfile``: tests will be grouped by file name, and then will be sent to an available - worker, guaranteeing that all tests in a group run in the same worker. This feature was added - in version ``1.21``. +* ``--dist loadscope``: Tests are grouped by **module** for *test functions* + and by **class** for *test methods*. Groups are distributed to available + workers as whole units. This guarantees that all tests in a group run in the + same process. This can be useful if you have expensive module-level or + class-level fixtures. Grouping by class takes priority over grouping by + module. +* ``--dist loadfile``: Tests are grouped by their containing file. Groups are + distributed to available workers as whole units. This guarantees that all + tests in a file run in the same worker. Making session-scoped fixtures execute only once ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^