summaryrefslogtreecommitdiff
path: root/doc/example/basic.txt
blob: f4df2339deeadf055053ce0ab9ba6dc0af2adb8b (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
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
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
Basic usage
=============================================

a simple tox.ini / default environments
-----------------------------------------------

Put basic information about your project and the test environments you
want your project to run in into a ``tox.ini`` file that should
reside next to your ``setup.py`` file::

    # content of: tox.ini , put in same dir as setup.py
    [tox]
    envlist = py26,py27
    [testenv]
    deps=pytest # or 'nose' or ...
    commands=py.test  # or 'nosetests' or ...

To sdist-package, install and test your project, you can
now type at the command prompt::

    tox

This will sdist-package your current project, create two virtualenv_
Environments, install the sdist-package into the environments and run
the specified command in each of them.  With::

    tox -e py26

you can run restrict the test run to the python2.6 environment.

Available "default" test environments names are::

    py24
    py25
    py26
    py27
    py30
    py31
    py32
    py33
    py34
    jython
    pypy
    pypy3

However, you can also create your own test environment names,
see some of the examples in :doc:`examples <../examples>`.

specifying a platform
-----------------------------------------------

.. versionadded:: 2.0

If you want to specify which platform(s) your test environment
runs on you can set a platform regular expression like this::

    platform = linux2|darwin

If the expression does not match against ``sys.platform``
the test environment will be skipped.

whitelisting non-virtualenv commands
-----------------------------------------------

.. versionadded:: 1.5

Sometimes you may want to use tools not contained in your
virtualenv such as ``make``, ``bash`` or others. To avoid
warnings you can use the ``whitelist_externals`` testenv
configuration::

    # content of tox.ini
    [testenv]
    whitelist_externals = make
                          /bin/bash


.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _multiindex:

depending on requirements.txt
-----------------------------------------------

.. versionadded:: 1.6.1

(experimental) If you have a ``requirements.txt`` file
you can add it to your ``deps`` variable like this::

    deps = -rrequirements.txt

All installation commands are executed using ``{toxinidir}``
(the directory where ``tox.ini`` resides) as the current
working directory.  Therefore, the underlying ``pip`` installation
will assume ``requirements.txt`` to exist at ``{toxinidir}/requirements.txt``.

using a different default PyPI url
-----------------------------------------------

.. versionadded:: 0.9

To install dependencies and packages from a different
default PyPI server you can type interactively::

    tox -i http://pypi.testrun.org

This causes tox to install dependencies and the sdist install step
to use the specificied url as the index server.

You can cause the same effect by this ``tox.ini`` content::

    [tox]
    indexserver =
        default = http://pypi.testrun.org

installing dependencies from multiple PyPI servers
---------------------------------------------------

.. versionadded:: 0.9

You can instrument tox to install dependencies from
different PyPI servers, example::

    [tox]
    indexserver =
        DEV = http://mypypiserver.org

    [testenv]
    deps =
        docutils        # comes from standard PyPI
        :DEV:mypackage  # will be installed from custom "DEV" pypi url

This configuration will install ``docutils`` from the default
Python PYPI server and will install the ``mypackage`` from
our ``DEV`` indexserver, and the respective ``http://mypypiserver.org``
url.  You can override config file settings from the command line
like this::

    tox -i DEV=http://pypi.python.org/simple  # changes :DEV: package URLs
    tox -i http://pypi.python.org/simple      # changes default

further customizing installation
---------------------------------

.. versionadded:: 1.6

By default tox uses `pip`_ to install packages, both the
package-under-test and any dependencies you specify in ``tox.ini``.
You can fully customize tox's install-command through the
testenv-specific :confval:`install_command=ARGV` setting.
For instance, to use ``easy_install`` instead of `pip`_::

    [testenv]
    install_command = easy_install {opts} {packages}

Or to use pip's ``--find-links`` and ``--no-index`` options to specify
an alternative source for your dependencies::

    [testenv]
    install_command = pip install --pre --find-links http://packages.example.com --no-index {opts} {packages}

.. _pip: http://pip-installer.org

forcing re-creation of virtual environments
-----------------------------------------------

.. versionadded:: 0.9

To force tox to recreate a (particular) virtual environment::

    tox --recreate -e py27

would trigger a complete reinstallation of the existing py27 environment
(or create it afresh if it doesn't exist).

passing down environment variables
-------------------------------------------

.. versionadded:: 2.0

By default tox will only pass the ``PATH`` environment variable (and on
windows ``SYSTEMROOT`` and ``PATHEXT``) from the tox invocation to the
test environments.  If you want to pass down additional environment
variables you can use the ``passenv`` option::

    [testenv]
    passenv = LANG

When your test commands execute they will execute with
the same LANG setting as the one with which tox was invoked.

setting environment variables
-------------------------------------------

.. versionadded:: 1.0

If you need to set an environment variable like ``PYTHONPATH`` you
can use the ``setenv`` directive::

    [testenv]
    setenv =
        PYTHONPATH = {toxinidir}/subdir

When your test commands execute they will execute with
a PYTHONPATH setting that will lead Python to also import
from the ``subdir`` below the directory where your ``tox.ini``
file resides.

special handling of PYTHONHASHSEED
-------------------------------------------

.. versionadded:: 1.6.2

By default, Tox sets PYTHONHASHSEED_ for test commands to a random integer
generated when ``tox`` is invoked.  This mimics Python's hash randomization
enabled by default starting `in Python 3.3`_.  To aid in reproducing test
failures, Tox displays the value of ``PYTHONHASHSEED`` in the test output.

You can tell Tox to use an explicit hash seed value via the ``--hashseed``
command-line option to ``tox``.  You can also override the hash seed value
per test environment in ``tox.ini`` as follows::

    [testenv]
    setenv =
        PYTHONHASHSEED = 100

If you wish to disable this feature, you can pass the command line option
``--hashseed=noset`` when ``tox`` is invoked. You can also disable it from the
``tox.ini`` by setting ``PYTHONHASHSEED = 0`` as described above.

.. _`in Python 3.3`: http://docs.python.org/3/whatsnew/3.3.html#builtin-functions-and-types
.. _PYTHONHASHSEED: http://docs.python.org/using/cmdline.html#envvar-PYTHONHASHSEED

Integration with setuptools/distribute test commands
----------------------------------------------------

Distribute/Setuptools support test requirements
and you can extend its test command to trigger
a test run when ``python setup.py test`` is issued::

    from setuptools.command.test import test as TestCommand
    import sys

    class Tox(TestCommand):
        user_options = [('tox-args=', 'a', "Arguments to pass to tox")]
        def initialize_options(self):
            TestCommand.initialize_options(self)
            self.tox_args = None
        def finalize_options(self):
            TestCommand.finalize_options(self)
            self.test_args = []
            self.test_suite = True
        def run_tests(self):
            #import here, cause outside the eggs aren't loaded
            import tox
            import shlex
            errno = tox.cmdline(args=shlex.split(self.tox_args))
            sys.exit(errno)

    setup(
        #...,
        tests_require=['tox'],
        cmdclass = {'test': Tox},
        )

Now if you run::

    python setup.py test

this will install tox and then run tox. You can pass arguments to ``tox``
using the ``--tox-args`` or ``-a`` command-line options. For example::

    python setup.py test -a "-epy27"

is equivalent to running ``tox -epy27``.

Ignoring a command exit code
----------------------------

In some cases, you may want to ignore a command exit code. For example::

    [testenv:py27]
    commands = coverage erase
           {envbindir}/python setup.py develop
           coverage run -p setup.py test
           coverage combine
           - coverage html
           {envbindir}/flake8 loads

By using the ``-`` prefix, similar to a ``make`` recipe line, you can ignore
the exit code for that command.

Compressing dependency matrix
-----------------------------

If you have a large matrix of dependencies, python versions and/or environments you can
use :ref:`generative-envlist` and :ref:`conditional settings <factors>` to express that in a concise form::

    [tox]
    envlist = py{26,27,33}-django{15,16}-{sqlite,mysql}

    [testenv]
    deps =
        django15: Django>=1.5,<1.6
        django16: Django>=1.6,<1.7
        py33-mysql: PyMySQL     ; use if both py33 and mysql are in an env name
        py26,py27: urllib3      ; use if any of py26 or py27 are in an env name
        py{26,27}-sqlite: mock  ; mocking sqlite in python 2.x