diff --git a/README.rst b/README.rst index 11abda3..32addc1 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: @@ -49,7 +49,7 @@ If you would like to know how pytest-xdist works under the covers, checkout Installation ------------------------ +------------ Install the plugin with:: @@ -58,22 +58,19 @@ Install the plugin with:: or use the package in develop/in-place mode with a checkout of the `pytest-xdist repository`_ :: - python setup.py develop - -Usage examples ---------------------- + pip install --editable . .. _parallelization: Speed up test runs by sending tests to multiple CPUs -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +---------------------------------------------------- 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 @@ -81,20 +78,34 @@ 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``. +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 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +------------------------------------ -To instantiate a python2.5 sub process and send tests to it, you may type:: +To instantiate a python3.5 subprocess and send tests to it, you may type:: - py.test -d --tx popen//python=python2.5 + py.test -d --tx popen//python=python3.5 -This will start a subprocess which is run with the "python2.5" +This will start a subprocess which is run with the ``python3.5`` Python interpreter, found in your system binary lookup path. If you prefix the --tx option value like this:: - --tx 3*popen//python=python2.5 + --tx 3*popen//python=python3.5 then three subprocesses would be created and tests will be load-balanced across these three processes. @@ -102,28 +113,16 @@ will be load-balanced across these three processes. .. _boxed: Running tests in a boxed subprocess -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -If you have tests involving C or C++ libraries you might have to deal -with tests crashing the process. For this case you may use the boxing -options:: - - py.test --boxed - -which will run each test in a subprocess and will report if a test -crashed the process. You can also combine this option with -running multiple processes to speed up the test run and use your CPU cores:: - - py.test -n3 --boxed - -this would run 3 testing subprocesses in parallel which each -create new boxed subprocesses for each test. +----------------------------------- +This functionality has been moved to the +`pytest-forked `_ plugin, but the ``--boxed`` option +is still kept for backward compatibility. .. _`remote machines`: Sending tests to remote SSH accounts -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +------------------------------------ Suppose you have a package ``mypkg`` which contains some tests that you can successfully run locally. And you @@ -158,7 +157,7 @@ ini-file option(s). Sending tests to remote Socket Servers -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +-------------------------------------- Download the single-module `socketserver.py`_ Python program and run it like this:: @@ -177,7 +176,7 @@ new socket host with something like this:: Running tests on many platforms at once -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +--------------------------------------- The basic command to run tests on multiple platforms is:: @@ -186,7 +185,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 @@ -195,7 +194,7 @@ at once. The specifications strings use the `xspec syntax`_. .. _`execnet`: http://codespeak.net/execnet Identifying the worker process during a test -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +-------------------------------------------- *New in version 1.15.* @@ -219,16 +218,15 @@ 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 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +------------------------------------------------ -pytest (since version 2.0) supports ini-style cofiguration. -You can for example make running with three subprocesses -your default like this: +You can use pytest's ini file configuration to avoid typing common options. +You can for example make running with three subprocesses your default like this: .. code-block:: ini @@ -240,7 +238,7 @@ You can also add default environments like this: .. code-block:: ini [pytest] - addopts = --tx ssh=myhost//python=python2.5 --tx ssh=myhost//python=python3.6 + addopts = --tx ssh=myhost//python=python3.5 --tx ssh=myhost//python=python3.6 and then just type:: @@ -249,100 +247,8 @@ 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 -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +-------------------------------------- In a ``tox.ini`` or ``setup.cfg`` file in your root project directory you may specify directories to include or to exclude in synchronisation: