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
|
.. be in -*- rst -*- mode!
General tips and tricks
================================
Interactively passing positional arguments
-----------------------------------------------
If you invoke ``tox`` like this::
tox -- -x tests/test_something.py
the arguments after the ``--`` will be substituted
everywhere where you specify ``{posargs}`` in your
test commands, for example using ``py.test``::
# in the testenv or testenv:NAME section of your tox.ini
commands =
py.test {posargs}
or using ``nosetests``::
commands =
nosetests {posargs}
the above ``tox`` invocation will trigger the test runners to
stop after the first failure and to only run a particular test file.
You can specify defaults for the positional arguments using this
syntax::
commands =
nosetests {posargs:--with-coverage}
.. _`sphinx checks`:
Integrating "sphinx" documentation checks
----------------------------------------------
In a ``testenv`` environment you can specify any command and
thus you can easily integrate sphinx_ documentation integrity during
a tox test run. Here is an example ``tox.ini`` configuration::
[testenv:docs]
basepython=python
changedir=doc
deps=sphinx
commands=
sphinx-build -W -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
This will create a dedicated ``docs`` virtual environment and install
the ``sphinx`` dependency which itself will install the ``sphinx-build`` tool
which you can then use as a test command. Note that sphinx output is redirected
to the virtualenv environment temporary directory to prevent sphinx
from caching results between runs.
You can now call::
tox
which will make the sphinx tests part of your test run.
.. _`TOXENV`:
Selecting one or more environments to run tests against
--------------------------------------------------------
Using the ``-e ENV[,ENV2,...]`` option you explicitely list
the environments where you want to run tests against. For
example, given the previous sphinx example you may call::
tox -e docs
which will make ``tox`` only manage the ``docs`` environment
and call its test commands. You may specify more than
one environment like this::
tox -e py25,py26
which would run the commands of the ``py25`` and ``py26`` testenvironments
respectively. The special value ``ALL`` selects all environments.
You can also specify an environment list in your ``tox.ini``::
[tox]
envlist = py25,py26
or override it from the command line or from the environment variable
``TOXENV``::
export TOXENV=py25,py26 # in bash style shells
.. _artifacts:
Access package artifacts between multiple tox-runs
--------------------------------------------------------
If you have multiple projects using tox you can make use of
a ``distshare`` directory where ``tox`` will copy in sdist-packages so
that another tox run can find the "latest" dependency. This feature
allows to test a package against an unreleased development version
or even an uncommitted version on your own machine.
By default, ``{homedir}/.tox/distshare`` will be used for
copying in and copying out artifacts (i.e. Python packages).
For project ``two`` to depend on the ``one`` package you use
the following entry::
# example two/tox.ini
[testenv]
deps=
{distshare}/one-*.zip # install latest package from "one" project
That's all. Tox running on project ``one`` will copy the sdist-package
into the ``distshare`` directory after which a ``tox`` run on project
``two`` will grab it because ``deps`` contain an entry with the
``one-*.zip`` pattern. If there is more than one matching package the
highest version will be taken. ``tox`` uses verlib_ to compare version
strings which must be compliant with :pep:`386`.
If you want to use this with Jenkins_, also checkout the :ref:`jenkins artifact example`.
.. _verlib: https://bitbucket.org/tarek/distutilsversion/
basepython defaults, overriding
++++++++++++++++++++++++++++++++++++++++++
By default, for any ``pyXY`` test environment name
the underlying "pythonX.Y" executable will be searched in
your system ``PATH``. It must exist in order to successfully create
virtualenv environments. On Windows a ``pythonX.Y`` named executable
will be searched in typical default locations using the
``C:\PythonX.Y\python.exe`` pattern.
For ``jython`` and ``pypy`` the respective ``jython``
and ``pypy-c`` names will be looked for.
You can override any of the default settings by defining
the ``basepython`` variable in a specific test environment
section, for example::
[testenv:py27]
basepython=/my/path/to/python2.7
Avoiding expensive sdist
------------------------
Some projects are large enough that running an sdist, followed by
an install every time can be prohibitively costly. To solve this,
there are two different options you can add to the ``tox`` section. First,
you can simply ask tox to please not make an sdist::
[tox]
skipsdist=True
If you do this, your local software package will not be installed into
the virtualenv. You should probably be okay with that, or take steps
to deal with it in your commands section::
[testenv]
commands =
python setup.py develop
py.test
Running ``setup.py develop`` is a common enough model that it has its own
option::
[testenv]
usedevelop=True
And a corresponding command line option ``--develop``, which will set
``skipsdist`` to True and then perform the ``setup.py develop``
step at the place where ``tox`` normally perfoms the installation of the sdist.
Specifically, it actually runs ``pip install -e .`` behind the scenes, which
itself calls ``setup.py develop``.
There is an optimization coded in to not bother re-running the command if
``$projectname.egg-info`` is newer than ``setup.py`` or ``setup.cfg``.
.. include:: ../links.txt
|
