tox: virtualenv-based automation of test activities

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.