Welcome to the tox automation project — tox v0.9 documentation
tox: virtualenv-based automation of test activities
home | install | examples | config | support
Table Of Contents
Welcome to the tox automation project
vision: merge testing and deployment
What is Tox?
Basic example
Current features
Notes and known limitations
Download
Current: 0.9 [Changes]
tox on PyPI
pip install tox
Questions? Suggestions?
Checkout support channels
Quick search
Enter search terms or a module, class or function name.
Welcome to the tox automation project¶
Note
tox is a a young project and still considered beta. Bug reports, feedback, contributions welcome: see support and contact channels.
vision: merge testing and deployment¶
tox aims to automate state-of-the-art packaging, testing and deployment of Python software right from your console or CI server, invoking your tools of choice.
What is Tox?¶
Tox as is a generic virtualenv management and test command line tool you can use for:
checking your package installs correctly with different Python versions and interpreters
running your tests in each of the environments, configuring your test tool of choice
acting as a frontend to Continous Integration servers, greatly reducing boilerplate and merging CI and shell-based testing.
Basic example¶
First, install tox with pip install tox or easy_install tox. Then put basic information about your project and the test environments you want your project to run in into a tox.ini file residing right 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 against Python2.6 and Python2.7, just type:
tox
and watch things happening (you must have python2.6 and python2.7 installed in your environment otherwise you will see errors). When you run tox a second time you’ll note that it runs much faster because it keeps track of virtualenv details and will not recreate or re-install dependencies. You also might want to checkout tox configuration and usage examples to get some more ideas.
Current features¶
automation of tedious Python related test activities
test your Python package against many interpreter and dependency configs
automatic customizable (re)creation of virtualenv test environments
installs your setup.py based project into each virtual environment
test-tool agnostic: runs py.test, nose or unittests a uniform manner
supports using different / multiple PyPI index servers
uses pip (for Python2 environments) and distribute (for all environments) by default
cross-Python compatible: Python2.4 up to Python2.7, Jython and experimental Python3 support as well as for pypy
cross-platform: Windows and Unix style environments
integrates with continous integration servers like Hudson and helps you to avoid boilerplatish and platform-specific build-step hacks.
unified automatic artifact management between tox runs both in a local developer shell as well as in a CI/Hudson context.
driven by a simple ini-style config file
documented examples and configuration
concise reporting about tool invocations and configuration errors
professionally supported
Notes and known limitations¶
tox always operates in virtualenv environments, it cannot work with globally installed Python interpreters because there are no reliable means to install and recreate dependencies. Or does it still makes sense to allow using global Python installations?
tox is fresh on the Python testing scene (first release July 2010) and needs some battle testing and feedback. It is is likely to evolve in (possibly incompatible) increments as it provides more power to configure and customize the test process.
tox uses virtualenv and virtualenv5, the latter being a fork of virtualenv3 which roughly works with Python3 but has less features (no “pip” and other problems). This comes with limitations and you may run into them when trying to create python3 based virtual environments. IMO the proper solution is: virtualenv needs to merge and grow proper native Python3 support, preferably in a “single-source” way.
tox currently uses a setup.py sdist invocation to create an installable package and then invokes pip or easy_install to install into each test environment. There is no support for other installation methods.