/usr/share/doc/python-pytest-doc/html/xdist.html is in python-pytest-doc 2.6.3-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>xdist: pytest distributed testing plugin</title>
<link rel="stylesheet" href="_static/flasky.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.6.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="shortcut icon" href="_static/pytest1favi.ico"/>
<link rel="top" title="None" href="index.html" />
<link rel="up" title="pytest reference documentation" href="apiref.html" />
<link rel="next" title="Temporary directories and files" href="tmpdir.html" />
<link rel="prev" title="Monkeypatching/mocking modules and environments" href="monkeypatch.html" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="tmpdir.html" title="Temporary directories and files"
accesskey="N">next</a></li>
<li class="right" >
<a href="monkeypatch.html" title="Monkeypatching/mocking modules and environments"
accesskey="P">previous</a> |</li>
<li><a href="contents.html">pytest-2.6.2</a> »</li>
<li><a href="apiref.html" accesskey="U">pytest reference documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="xdist-pytest-distributed-testing-plugin">
<span id="xdist"></span><h1>xdist: pytest distributed testing plugin<a class="headerlink" href="#xdist-pytest-distributed-testing-plugin" title="Permalink to this headline">¶</a></h1>
<p>The <a class="reference external" href="http://pypi.python.org/pypi/pytest-xdist">pytest-xdist</a> plugin extends <tt class="docutils literal"><span class="pre">pytest</span></tt> with some unique
test execution modes:</p>
<ul class="simple">
<li>Looponfail: run your tests repeatedly in a subprocess. After each
run, <tt class="docutils literal"><span class="pre">pytest</span></tt> waits until a file in your project changes and then
re-runs the previously failing tests. This is repeated until all
tests pass. At this point a full run is again performed.</li>
<li>multiprocess Load-balancing: if you have multiple CPUs or hosts you can use
them for a combined test run. This allows to speed up
development or to use special resources of remote machines.</li>
<li>Multi-Platform coverage: you can specify different Python interpreters
or different platforms and run tests in parallel on all of them.</li>
</ul>
<p>Before running tests remotely, <tt class="docutils literal"><span class="pre">pytest</span></tt> efficiently “rsyncs” your
program source code to the remote place. All test results
are reported back and displayed to your local terminal.
You may specify different Python versions and interpreters.</p>
<div class="section" id="installation-of-xdist-plugin">
<h2>Installation of xdist plugin<a class="headerlink" href="#installation-of-xdist-plugin" title="Permalink to this headline">¶</a></h2>
<p>Install the plugin with:</p>
<div class="highlight-python"><div class="highlight"><pre>easy_install pytest-xdist
# or
pip install pytest-xdist
</pre></div>
</div>
<p>or use the package in develop/in-place mode with
a checkout of the <a class="reference external" href="http://bitbucket.org/hpk42/pytest-xdist">pytest-xdist repository</a></p>
<div class="highlight-python"><div class="highlight"><pre>python setup.py develop
</pre></div>
</div>
</div>
<div class="section" id="usage-examples">
<h2>Usage examples<a class="headerlink" href="#usage-examples" title="Permalink to this headline">¶</a></h2>
<div class="section" id="speed-up-test-runs-by-sending-tests-to-multiple-cpus">
<span id="xdistcpu"></span><h3>Speed up test runs by sending tests to multiple CPUs<a class="headerlink" href="#speed-up-test-runs-by-sending-tests-to-multiple-cpus" title="Permalink to this headline">¶</a></h3>
<p>To send tests to multiple CPUs, type:</p>
<div class="highlight-python"><div class="highlight"><pre>py.test -n NUM
</pre></div>
</div>
<p>Especially for longer running tests or tests requiring
a lot of I/O this can lead to considerable speed ups.</p>
</div>
<div class="section" id="running-tests-in-a-python-subprocess">
<h3>Running tests in a Python subprocess<a class="headerlink" href="#running-tests-in-a-python-subprocess" title="Permalink to this headline">¶</a></h3>
<p>To instantiate a Python-2.4 subprocess and send tests to it, you may type:</p>
<div class="highlight-python"><div class="highlight"><pre>py.test -d --tx popen//python=python2.4
</pre></div>
</div>
<p>This will start a subprocess which is run with the “python2.4”
Python interpreter, found in your system binary lookup path.</p>
<p>If you prefix the –tx option value like this:</p>
<div class="highlight-python"><div class="highlight"><pre>py.test -d --tx 3*popen//python=python2.4
</pre></div>
</div>
<p>then three subprocesses would be created and the tests
will be distributed to three subprocesses and run simultanously.</p>
</div>
<div class="section" id="running-tests-in-looponfailing-mode">
<span id="looponfailing"></span><h3>Running tests in looponfailing mode<a class="headerlink" href="#running-tests-in-looponfailing-mode" title="Permalink to this headline">¶</a></h3>
<p>For refactoring a project with a medium or large test suite
you can use the looponfailing mode. Simply add the <tt class="docutils literal"><span class="pre">--f</span></tt> option:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">py</span><span class="o">.</span><span class="n">test</span> <span class="o">-</span><span class="n">f</span>
</pre></div>
</div>
<p>and <tt class="docutils literal"><span class="pre">pytest</span></tt> will run your tests. Assuming you have failures it will then
wait for file changes and re-run the failing test set. File changes are detected by looking at <tt class="docutils literal"><span class="pre">looponfailingroots</span></tt> root directories and all of their contents (recursively). If the default for this value does not work for you you
can change it in your project by setting a configuration option:</p>
<div class="highlight-python"><div class="highlight"><pre># content of a pytest.ini, setup.cfg or tox.ini file
[pytest]
looponfailroots = mypkg testdir
</pre></div>
</div>
<p>This would lead to only looking for file changes in the respective directories, specified relatively to the ini-file’s directory.</p>
</div>
<div class="section" id="sending-tests-to-remote-ssh-accounts">
<h3>Sending tests to remote SSH accounts<a class="headerlink" href="#sending-tests-to-remote-ssh-accounts" title="Permalink to this headline">¶</a></h3>
<p>Suppose you have a package <tt class="docutils literal"><span class="pre">mypkg</span></tt> which contains some
tests that you can successfully run locally. And you also
have a ssh-reachable machine <tt class="docutils literal"><span class="pre">myhost</span></tt>. Then
you can ad-hoc distribute your tests by typing:</p>
<div class="highlight-python"><div class="highlight"><pre>py.test -d --tx ssh=myhostpopen --rsyncdir mypkg mypkg
</pre></div>
</div>
<p>This will synchronize your <tt class="docutils literal"><span class="pre">mypkg</span></tt> package directory
with a remote ssh account and then collect and run your
tests at the remote side.</p>
<p>You can specify multiple <tt class="docutils literal"><span class="pre">--rsyncdir</span></tt> directories
to be sent to the remote side.</p>
</div>
<div class="section" id="sending-tests-to-remote-socket-servers">
<h3>Sending tests to remote Socket Servers<a class="headerlink" href="#sending-tests-to-remote-socket-servers" title="Permalink to this headline">¶</a></h3>
<p>Download the single-module <a class="reference external" href="http://bitbucket.org/hpk42/execnet/raw/2af991418160/execnet/script/socketserver.py">socketserver.py</a> Python program
and run it like this:</p>
<div class="highlight-python"><div class="highlight"><pre>python socketserver.py
</pre></div>
</div>
<p>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:</p>
<div class="highlight-python"><div class="highlight"><pre>py.test -d --tx socket=192.168.1.102:8888 --rsyncdir mypkg mypkg
</pre></div>
</div>
</div>
<div class="section" id="running-tests-on-many-platforms-at-once">
<span id="atonce"></span><h3>Running tests on many platforms at once<a class="headerlink" href="#running-tests-on-many-platforms-at-once" title="Permalink to this headline">¶</a></h3>
<p>The basic command to run tests on multiple platforms is:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">py</span><span class="o">.</span><span class="n">test</span> <span class="o">--</span><span class="n">dist</span><span class="o">=</span><span class="n">each</span> <span class="o">--</span><span class="n">tx</span><span class="o">=</span><span class="n">spec1</span> <span class="o">--</span><span class="n">tx</span><span class="o">=</span><span class="n">spec2</span>
</pre></div>
</div>
<p>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 <a class="reference external" href="http://codespeak.net/execnet/basics.html#xspec">xspec syntax</a>.</p>
</div>
<div class="section" id="specifying-test-exec-environments-in-an-ini-file">
<h3>Specifying test exec environments in an ini file<a class="headerlink" href="#specifying-test-exec-environments-in-an-ini-file" title="Permalink to this headline">¶</a></h3>
<p>pytest (since version 2.0) supports ini-style configuration.
For example, you could make running with three subprocesses your default:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="p">[</span><span class="n">pytest</span><span class="p">]</span>
<span class="n">addopts</span> <span class="o">=</span> <span class="o">-</span><span class="n">n3</span>
</pre></div>
</div>
<p>You can also add default environments like this:</p>
<div class="highlight-python"><div class="highlight"><pre>[pytest]
addopts = --tx ssh=myhost//python=python2.5 --tx ssh=myhost//python=python2.6
</pre></div>
</div>
<p>and then just type:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="n">py</span><span class="o">.</span><span class="n">test</span> <span class="o">--</span><span class="n">dist</span><span class="o">=</span><span class="n">each</span>
</pre></div>
</div>
<p>to run tests in each of the environments.</p>
</div>
<div class="section" id="specifying-rsync-dirs-in-an-ini-file">
<h3>Specifying “rsync” dirs in an ini-file<a class="headerlink" href="#specifying-rsync-dirs-in-an-ini-file" title="Permalink to this headline">¶</a></h3>
<p>In a <tt class="docutils literal"><span class="pre">tox.ini</span></tt> or <tt class="docutils literal"><span class="pre">setup.cfg</span></tt> file in your root project directory
you may specify directories to include or to exclude in synchronisation:</p>
<div class="highlight-python"><div class="highlight"><pre>[pytest]
rsyncdirs = . mypkg helperpkg
rsyncignore = .hg
</pre></div>
</div>
<p>These directory specifications are relative to the directory
where the configuration file was found.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="contents.html">
<img class="logo" src="_static/pytest1.png" alt="Logo"/>
</a></p><h3><a href="contents.html">Table Of Contents</a></h3>
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="contents.html">Contents</a></li>
<li><a href="getting-started.html">Install</a></li>
<li><a href="example/index.html">Examples</a></li>
<li><a href="customize.html">Customize</a></li>
<li><a href="contact.html">Contact</a></li>
<li><a href="talks.html">Talks/Posts</a></li>
<li><a href="changelog.html">Changelog</a></li>
</ul>
<hr>
<ul>
<li><a class="reference internal" href="#">xdist: pytest distributed testing plugin</a><ul>
<li><a class="reference internal" href="#installation-of-xdist-plugin">Installation of xdist plugin</a></li>
<li><a class="reference internal" href="#usage-examples">Usage examples</a><ul>
<li><a class="reference internal" href="#speed-up-test-runs-by-sending-tests-to-multiple-cpus">Speed up test runs by sending tests to multiple CPUs</a></li>
<li><a class="reference internal" href="#running-tests-in-a-python-subprocess">Running tests in a Python subprocess</a></li>
<li><a class="reference internal" href="#running-tests-in-looponfailing-mode">Running tests in looponfailing mode</a></li>
<li><a class="reference internal" href="#sending-tests-to-remote-ssh-accounts">Sending tests to remote SSH accounts</a></li>
<li><a class="reference internal" href="#sending-tests-to-remote-socket-servers">Sending tests to remote Socket Servers</a></li>
<li><a class="reference internal" href="#running-tests-on-many-platforms-at-once">Running tests on many platforms at once</a></li>
<li><a class="reference internal" href="#specifying-test-exec-environments-in-an-ini-file">Specifying test exec environments in an ini file</a></li>
<li><a class="reference internal" href="#specifying-rsync-dirs-in-an-ini-file">Specifying “rsync” dirs in an ini-file</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Related Topics</h3>
<ul>
<li><a href="contents.html">Documentation overview</a><ul>
<li><a href="apiref.html">pytest reference documentation</a><ul>
<li>Previous: <a href="monkeypatch.html" title="previous chapter">Monkeypatching/mocking modules and environments</a></li>
<li>Next: <a href="tmpdir.html" title="next chapter">Temporary directories and files</a></li>
</ul></li>
</ul></li>
</ul><h3>Useful Links</h3>
<ul>
<li><a href="index.html">The pytest Website</a></li>
<li><a href="contributing.html">Contribution Guide</a></li>
<li><a href="https://pypi.python.org/pypi/pytest">pytest @ PyPI</a></li>
<li><a href="https://bitbucket.org/hpk42/pytest/">pytest @ Bitbucket</a></li>
<li><a href="http://pytest.org/latest/plugins_index/index.html">3rd party plugins</a></li>
<li><a href="https://bitbucket.org/hpk42/pytest/issues?status=new&status=open">Issue Tracker</a></li>
<li><a href="http://pytest.org/latest/pytest.pdf">PDF Documentation</a>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright 2014, holger krekel.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
|