9
The `pytest-xdist`_ plugin extends py.test with some unique
9
The `pytest-xdist`_ plugin extends py.test with some unique
10
10
test execution modes:
12
12
* Looponfail: run your tests repeatedly in a subprocess. After each run py.test
13
13
waits until a file in your project changes and then re-runs the previously
14
14
failing tests. This is repeated until all tests pass after which again
15
a full run is performed.
15
a full run is performed.
17
17
* Load-balancing: if you have multiple CPUs or hosts you can use
18
those for a combined test run. This allows to speed up
19
development or to use special resources of remote machines.
18
those for a combined test run. This allows to speed up
19
development or to use special resources of remote machines.
21
21
* Multi-Platform coverage: you can specify different Python interpreters
22
or different platforms and run tests in parallel on all of them.
22
or different platforms and run tests in parallel on all of them.
24
Before running tests remotely, ``py.test`` efficiently synchronizes your
25
program source code to the remote place. All test results
26
are reported back and displayed to your local test session.
24
Before running tests remotely, ``py.test`` efficiently synchronizes your
25
program source code to the remote place. All test results
26
are reported back and displayed to your local test session.
27
27
You may specify different Python versions and interpreters.
29
29
.. _`pytest-xdist`: http://pypi.python.org/pypi/pytest-xdist
41
Especially for longer running tests or tests requiring
42
a lot of IO this can lead to considerable speed ups.
45
Running tests in a Python subprocess
41
Especially for longer running tests or tests requiring
42
a lot of IO this can lead to considerable speed ups.
45
Running tests in a Python subprocess
46
46
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
48
48
To instantiate a python2.4 sub process and send tests to it, you may type::
50
50
py.test -d --tx popen//python=python2.4
52
52
This will start a subprocess which is run with the "python2.4"
53
Python interpreter, found in your system binary lookup path.
53
Python interpreter, found in your system binary lookup path.
55
55
If you prefix the --tx option value like this::
57
57
--tx 3*popen//python=python2.4
59
59
then three subprocesses would be created and tests
60
will be load-balanced across these three processes.
60
will be load-balanced across these three processes.
63
63
Sending tests to remote SSH accounts
64
64
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
66
Suppose you have a package ``mypkg`` which contains some
66
Suppose you have a package ``mypkg`` which contains some
67
67
tests that you can successfully run locally. And you
68
have a ssh-reachable machine ``myhost``. Then
68
have a ssh-reachable machine ``myhost``. Then
69
69
you can ad-hoc distribute your tests by typing::
71
71
py.test -d --tx ssh=myhostpopen --rsyncdir mypkg mypkg
73
This will synchronize your ``mypkg`` package directory
74
to an remote ssh account and then locally collect tests
75
and send them to remote places for execution.
73
This will synchronize your ``mypkg`` package directory
74
to an remote ssh account and then locally collect tests
75
and send them to remote places for execution.
77
You can specify multiple ``--rsyncdir`` directories
78
to be sent to the remote side.
77
You can specify multiple ``--rsyncdir`` directories
78
to be sent to the remote side.
80
80
**NOTE:** For py.test to collect and send tests correctly
81
81
you not only need to make sure all code and tests
82
82
directories are rsynced, but that any test (sub) directory
83
83
also has an ``__init__.py`` file because internally
84
84
py.test references tests as a fully qualified python
85
module path. **You will otherwise get strange errors**
85
module path. **You will otherwise get strange errors**
86
86
during setup of the remote side.
88
88
Sending tests to remote Socket Servers
89
89
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
91
Download the single-module `socketserver.py`_ Python program
91
Download the single-module `socketserver.py`_ Python program
92
92
and run it like this::
94
94
python socketserver.py
96
96
It will tell you that it starts listening on the default
97
port. You can now on your home machine specify this
97
port. You can now on your home machine specify this
98
98
new socket host with something like this::
100
100
py.test -d --tx socket=192.168.1.102:8888 --rsyncdir mypkg mypkg
105
Running tests on many platforms at once
105
Running tests on many platforms at once
106
106
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
108
108
The basic command to run tests on multiple platforms is::
110
py.test --dist=each --tx=spec1 --tx=spec2
110
py.test --dist=each --tx=spec1 --tx=spec2
112
112
If you specify a windows host, an OSX host and a Linux
113
environment this command will send each tests to all
113
environment this command will send each tests to all
114
114
platforms - and report back failures from all platforms
115
at once. The specifications strings use the `xspec syntax`_.
115
at once. The specifications strings use the `xspec syntax`_.
117
117
.. _`xspec syntax`: http://codespeak.net/execnet/trunk/basics.html#xspec
123
123
Specifying test exec environments in a conftest.py
124
124
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
126
Instead of specifying command line options, you can
126
Instead of specifying command line options, you can
127
127
put options values in a ``conftest.py`` file like this::
129
pytest_option_tx = ['ssh=myhost//python=python2.5', 'popen//python=python2.5']
130
pytest_option_dist = True
129
option_tx = ['ssh=myhost//python=python2.5', 'popen//python=python2.5']
132
Any commandline ``--tx`` specifictions will add to the list of available execution
132
Any commandline ``--tx`` specifictions will add to the list of
133
available execution environments.
135
135
Specifying "rsync" dirs in a conftest.py
136
136
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
156
156
box each test run in a separate process (unix)
157
157
``--dist=distmode``
158
158
set mode for distributing tests to exec environments.
160
160
each: send each test to each available environment.
162
162
load: send each test to available environment.
164
164
(default) no: run tests inprocess, don't distribute.
166
166
add a test execution environment. some examples: --tx popen//python=python2.5 --tx socket=192.168.1.102:8888 --tx ssh=user@codespeak.net//chdir=testcache
169
169
``--rsyncdir=dir1``
170
170
add directory for rsyncing to remote tx nodes.
172
Start improving this plugin in 30 seconds
173
=========================================
176
1. Download `plugin.py`_ plugin source code
177
2. put it somewhere as ``plugin.py`` into your import path
178
3. a subsequent ``py.test`` run will use your local version
180
Checkout customize_, other plugins_ or `get in contact`_.
182
172
.. include:: links.txt
added
removed
doc/test/plugin/xdist.txt
