blob: 489ab1558b4549ad48320e8e27f8b4522e97e40c (
plain)
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
|
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 ``[...]`` in your
test commands, for example using ``py.test``::
# in the testenv or testenv:NAME section of your tox.ini
commands =
py.test []
or using ``nosetests``::
commands =
nosetests []
the above ``tox`` invocation will trigger the test runners to
stop after the first failure and to only run a particular test file.
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.
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 # default list
and override it from the command line or from the environment variable
``TOXENVLIST``.
Access package artifacts between multiple tox-runs
--------------------------------------------------------
If you have multiple projects using tox and you can arrange for them
to have access to a common directory then ``tox`` provides help to access
packaging artifacts between the projects. You can create make use of
a ``distshare`` directory where tox jobs copy in and copy out dependencies.
This feature allows to to test a package against an unreleased development version
or even an uncommitted version on your own machine.
Example ``tox.ini`` for project ``one``::
[tox]
distshare={homedir}/.tox/dist # share sdist-packages on a per-user basis
Example ``tox.ini`` for project ``two``:
[tox]
distshare={homedir}/.tox/dist # share sdist-packages on a per-user basis
[testenv]
deps=
{distshare}/two-*.zip # install latest package from "two" project
Project ``one`` will copy its sdist-package into the ``distshare`` directory
while project ``two`` will grab it because the dependencies list
the ``two-*.zip`` pattern. If there is more than one matching package
then the highest version will be taken. ``tox`` uses verlib_ to
compare version strings which must be compliant with :pep:`385`.
.. _verlib: http://bitbucket.org/tarek/distutilsversion/
.. include:: ../links.txt
|
