test_ok1/doc/test/dist.txt

.. _`distribute tests across machines`:

===================
Distributed testing
===================

``py.test`` can ad-hoc distribute test runs to multiple CPUs or remote
machines.  This allows to speed up development or to use special resources
of remote machines.  Before running tests remotely, ``py.test`` efficiently 
synchronizes your program source code to the remote place.  All test results 
are reported back and displayed to your local test session.  You may 
specify different Python versions and interpreters.

Synchronisation and running of tests only requires
a bare Python installation on the remote side.   No
special software is installed - this is realized 
by use of the **zero installation** `py.execnet`_ mechanisms.

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. 


Running tests in a Python subprocess 
----------------------------------------

To instantiate a python2.4 sub process and send tests to it, you may type::

    py.test -d --tx popen//python=python2.4

This will start a subprocess which is run with the "python2.4"
Python interpreter, found in your system binary lookup path. 

If you prefix the --tx option value like this::

    --tx 3*popen//python=python2.4

then three subprocesses would be created and tests
will be load-balanced across these three processes. 


Sending tests to remote SSH accounts
-----------------------------------------------

Suppose you have a package ``mypkg`` which contains some 
tests that you can successfully run locally. And you
have a ssh-reachable machine ``myhost``.  Then    
you can ad-hoc distribute your tests by typing::

    py.test -d --tx ssh=myhostpopen --rsyncdir mypkg mypkg

This will synchronize your ``mypkg`` package directory 
to an remote ssh account and then locally collect tests 
and send them to remote places for execution.  

You can specify multiple ``--rsyncdir`` directories 
to be sent to the remote side. 


Sending tests to remote Socket Servers
----------------------------------------

Download the single-module `socketserver.py`_ Python program 
and run it like this::

    python socketserver.py

It will tell you that it starts listening on the default
port.  You can now on your home machine specify this 
new socket host with something like this::

    py.test -d --tx socket=192.168.1.102:8888 --rsyncdir mypkg mypkg


.. _`atonce`:

Running tests on many platforms at once 
-------------------------------------------------------------

The basic command to run tests on multiple platforms is::

    py.test --dist=each --tx=spec1 --tx=spec2 

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 provided specifications strings 
use the `xspec syntax`_. 

.. _`xspec syntax`: ../execnet.html#xspec

.. _`socketserver.py`: http://codespeak.net/svn/py/dist/py/execnet/script/socketserver.py
.. _`py.execnet`: ../execnet.html

Specifying test exec environments in a conftest.py
-------------------------------------------------------------

Instead of specifying command line options, you can 
put options values in a ``conftest.py`` file like this::

    pytest_option_tx = ['ssh=myhost//python=python2.5', 'popen//python=python2.5']
    pytest_option_dist = True

Any commandline ``--tx`` specifictions  will add to the list of available execution
environments. 

Specifying "rsync" dirs in a conftest.py
-------------------------------------------------------------

In your ``mypkg/conftest.py`` you may specify directories to synchronise
or to exclude::

    rsyncdirs = ['.', '../plugins']
    rsyncignore = ['_cache']

These directory specifications are relative to the directory
where the ``conftest.py`` is found.