Welcome to the tox automation project — tox 3.14.6.dev4 document

Welcome to the tox automation project¶ [#welcome-to-the-tox-automation-project] vision: standardize testing in Python ¶ tox aims to automate and standardize testing in Python. It is part of a larger vision of easing the packaging, testing and release process of Python software. What is tox? ¶ tox 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 . 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 = py27,py36 [testenv] # install pytest in the virtualenv where commands will be executed deps = pytest commands = # NOTE: you can run any command line tool here - not just tests pytest You can also try generating a tox.ini file automatically, by running tox-quickstart and then answering a few simple questions. To sdist-package, install and test your project against Python2.7 and Python3.6, just type: tox and watch things happening (you must have python2.7 and python3.6 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. System overview ¶ tox workflow diagram ¶ tox roughly follows the following phases: configuration: load tox.ini and merge it with options from the command line and the operating system environment variables. packaging (optional): create a source distribution of the current project by invoking python setup.py sdist Note that for this operation the same Python environment will be used as the one tox is installed into (therefore you need to make sure that it contains your build dependencies). Skip this step for application projects that don’t have a setup.py . environment - for each tox environment (e.g. py27 , py36 ) do: 1. environment creation : create a fresh environment, by default virtualenv is used. tox will automatically try to discover a valid Python interpreter version by using the environment name (e.g. py27 means Python 2.7 and the basepython configuration value) and the current operating system PATH value. This is created at first run only to be re-used at subsequent runs. If certain aspects of the project change, a re-creation of the environment is automatically triggered. To force the recreation tox can be invoked with -r / --recreate . 2. install (optional): install the environment dependencies specified inside the deps configuration section, and then the earlier packaged source distribution. By default pip is used to install packages, however one can customise this via install_command . Note pip will not update project dependencies (specified either in the install_requires or the extras section of the setup.py ) if any version already exists in the virtual environment; therefore we recommend to recreate your environments whenever your project dependencies change. 3. commands : run the specified commands in the specified order. Whenever the exit code of any of them is not zero stop, and mark the environment failed. Note, starting a command with a single dash character means ignore exit code. report print out a report of outcomes for each tox environment: ____________________ summary ____________________ py27: commands succeeded ERROR: py36: commands failed Only if all environments ran successfully tox will return exit code 0 (success). In this case you’ll also see the message congratulations :) . tox will take care of environment isolation for you: it will strip away all operating system environment variables not specified via passenv . Furthermore, it will also alter the PATH variable so that your commands resolve first and foremost within the current active tox environment. In general all executables in the path are available in commands , but tox will emit a warning if it was not explicitly allowed via whitelist_externals . 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 pytest, nose or unittests in a uniform manner plugin system to modify tox execution with simple hooks. uses pip and setuptools by default. Support for configuring the installer command through install_command=ARGV . cross-Python compatible : CPython-2.7, 3.4 and higher, Jython and 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. full interoperability with devpi : is integrated with and is used for testing in the devpi system, a versatile PyPI index server and release managing tool. driven by a simple ini-style config file documented examples and configuration concise reporting about tool invocations and configuration errors professionally supported supports using different / multiple PyPI index servers Related projects ¶ tox has influenced several other projects in the Python test automation space. If tox doesn’t quite fit your needs or you want to do more research, we recommend taking a look at these projects: Invoke is a general-purpose task execution library, similar to Make. Invoke is far more general-purpose than tox but it does not contain the Python testing-specific features that tox specializes in. Nox is a project similar in spirit to tox but different in approach. Nox’s key difference is that it uses Python scripts instead of a configuration file. Nox might be useful if you find tox’s configuration too limiting but aren’t looking to move to something as general-purpose as Invoke or Make. standardise testing in Python quicklinks home examples install changelog config issues[gh] support plugins/hooks Table of Contents Welcome to the tox automation project vision: standardize testing in Python What is tox? Basic example System overview Current features Related projects Related Topics Documentation overview Next: tox installation Quick search ©2010-2020, holger krekel and others. | Powered by Sphinx 2.4.4 & Alabaster 0.7.12