quicklinks

home examples
install changelog
config issues[bb]
support

Table Of Contents

Previous topic

tox configuration and usage examples

Next topic

py.test and tox

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]
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
jython
pypy

However, you can also create your own test environment names, see some of the examples in examples.

whitelisting a non-virtualenv commands

New in version 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

using a different default PyPI url

New in version 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

New in version 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

forcing re-creation of virtual environments

New in version 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).

setting environment variables

New in version 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.

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):
    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
        errno = tox.cmdline(self.test_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.