From b2c63a1ba5ad2dd752fdb13f30f9c1d8894b0e30 Mon Sep 17 00:00:00 2001 From: Bruno Oliveira Date: Fri, 22 Dec 2017 16:42:35 -0200 Subject: [PATCH] Reworded some sections to be more newbie friendly --- README.rst | 118 +++++++++-------------------------------------------- 1 file changed, 20 insertions(+), 98 deletions(-) diff --git a/README.rst b/README.rst index 4ed43cb..575f422 100644 --- a/README.rst +++ b/README.rst @@ -21,7 +21,7 @@ :target: https://ci.appveyor.com/project/pytestbot/pytest-xdist xdist: pytest distributed testing plugin -========================================= +======================================== The `pytest-xdist`_ plugin extends py.test with some unique test execution modes: @@ -46,7 +46,7 @@ You may specify different Python versions and interpreters. Installation ------------------------ +------------ Install the plugin with:: @@ -67,7 +67,7 @@ To send tests to multiple CPUs, type:: py.test -n NUM Especially for longer running tests or tests requiring -a lot of IO this can lead to considerable speed ups. This option can +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. If a test crashes the interpreter, pytest-xdist will automatically restart @@ -75,6 +75,20 @@ that slave and report the failure as usual. You can use the ``--max-slave-restart`` option to limit the number of slaves that can be restarted, or disable restarting altogether using ``--max-slave-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: + +* ``--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=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``. + Running tests in a Python subprocess ------------------------------------ @@ -180,7 +194,7 @@ The basic command to run tests on multiple platforms is:: If you specify a windows host, an OSX host and a Linux environment this command will send each tests to all platforms - and report back failures from all platforms -at once. The specifications strings use the `xspec syntax`_. +at once. The specifications strings use the `xspec syntax`_. .. _`xspec syntax`: http://codespeak.net/execnet/basics.html#xspec @@ -213,8 +227,8 @@ defined: * ``PYTEST_XDIST_WORKER_COUNT``: the total number of workers in this session, e.g., ``"4"`` when ``-n 4`` is given in the command-line. -The information about the worker_id in a test is stored in the TestReport as -well, under worker_id attribute. +The information about the worker_id in a test is stored in the ``TestReport`` as +well, under the ``worker_id`` attribute. Specifying test exec environments in an ini file @@ -243,98 +257,6 @@ and then just type:: to run tests in each of the environments. -Sending groups of related tests to the same worker --------------------------------------------------- - -*New in version 1.19.* - -.. note:: - This is an **experimental** feature: the actual functionality will - likely stay the same, but the CLI might change slightly in future versions. - -You can send groups of related tests to the same worker by using the -``--dist=loadscope`` option. Tests will be grouped by **module** -for *test functions* and by **class** for *test methods*. - -For example, consider this two test files: - -.. code-block:: python - - # content of test_container.py - import pytest - - def test_container_startup(): - pass - - def test_container_logging(): - pass - - @pytest.mark.parametrize('methods', ['ssh', 'http']) - def test_container_communication(methods): - pass - - # content of test_io.py - class TestHDF: - - def test_listing(self): - pass - - def test_search(self): - pass - - - class TestXML: - - def test_listing(self): - pass - - def test_search(self): - pass - - -By executing ``pytest -v --dist=loadscope -n4`` you might get this output -(sorted by worker for readability):: - - ============================= test session starts ============================= - - gw0 [8] / gw1 [8] / gw2 [8] / gw3 [8] - scheduling tests via LoadScopeScheduling - - [gw0] PASSED test_container.py::test_container_communication[http] - [gw0] PASSED test_container.py::test_container_communication[ssh] - [gw0] PASSED test_container.py::test_container_logging - [gw0] PASSED test_container.py::test_container_startup - [gw1] PASSED test_io.py::TestHDF::test_listing - [gw1] PASSED test_io.py::TestHDF::test_search - [gw2] PASSED test_io.py::TestXML::test_listing - [gw2] PASSED test_io.py::TestXML::test_search - - ========================== 8 passed in 0.56 seconds =========================== - -As you can see, all test functions from ``test_container.py`` executed on -the same worker ``gw0``, while the test methods from classes ``TestHDF`` and -``TestXML`` executed in workers ``gw1`` and ``gw2`` respectively. - -Currently the groupings can't be customized, with grouping by class takes -priority over grouping by module. - -Sending tests to the same worker based on their file ----------------------------------------------------- - -*New in version 1.21.* - -.. note:: - This is an **experimental** feature: the actual functionality will - likely stay the same, but the CLI might change slightly in future versions. - -You can send tests to the same worker grouped by their filename by using the -``--dist=loadfile`` option, so tests of the same file are guaranteed to run -in the same worker. - -Using the example in the previous section, all tests from ``test_container.py`` will -run in the same worker, as well as the tests in ``test_io.py``. - - Specifying "rsync" dirs in an ini-file -------------------------------------