Source

tox / doc / index.txt

Welcome to the tox automation project
===============================================

vision: merge packaging, testing and release
---------------------------------------------

``tox`` aims to automate state-of-the-art packaging, testing and
releasing 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 Continuous 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]
    deps=pytest       # install pytest in the venvs
    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 :doc:`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 in a uniform manner

* supports :ref:`using different / multiple PyPI index servers  <multiindex>`

* uses pip_ (for Python2 environments) and distribute_ (for all environments) by default

* **cross-Python compatible**: Python-2.5 up to Python-3.2, Jython and 
  Python3 support as well as for pypy_

* **cross-platform**: Windows and Unix style environments

* **integrates with continuous integration servers** like Jenkins_
  (formerly known as 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/Jenkins context.

* **driven by a simple ini-style config file**

* **documented** :doc:`examples <examples>` and :doc:`configuration <config>`

* **concise reporting** about tool invocations and configuration errors

* **professionally** :doc:`supported <support>`

.. _pypy: http://pypy.org

.. _`tox.ini`: :doc:configfile

.. toctree::
   :hidden:

   install
   examples
   config
   support
   changelog
   links
   announce/release-0.5
   announce/release-1.0
   announce/release-1.1
   announce/release-1.2
   announce/release-1.3
   announce/release-1.4


.. include:: links.txt
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.