tox

Run tests on all test environments

$ tox

$ tox-quickstart

$ tox [[-a|--listenvs-all]]

$ tox -e [py36]

$ tox [[-r|--recreate]] -e [py27]

tox [options] [posargs]
tox -e ENVLIST [posargs]
tox --help
tox --version

-e ENVLIST, --envlist ENVLIST
    Run only specific test environments from the tox.ini file. You can specify multiple environments separated by commas, e.g., py38,py39,lint.

-r, --recreate
    Recreate the virtual environments even if they already exist. This is useful for ensuring a clean build and avoiding cached issues.

-v, --verbose
    Increase the verbosity of tox's output. Can be specified multiple times (e.g., -vvv) for even more detailed logs.

-i CMD, --install-command CMD
    Command to use for installing packages instead of the default. For example, pip install {opts} {packages}.

--skip-missing-interpreters
    Do not fail if an interpreter specified in tox.ini (e.g., python3.10) is not found on the system.

--parallel [MODE]
    Run environments in parallel. MODE can be auto, all, skip (default), or a specific number of parallel processes.

-c FILE, --config FILE
    Use a specific tox.ini configuration file instead of searching for the default in the current directory or parent directories.

-w DIR, --workdir DIR
    Set the working directory for tox environments and their associated files.

--result-json FILE
    Write a JSON report of the tox run results to the specified FILE, useful for programmatic analysis.

--help
    Show tox's help message and exit.

--version
    Show tox's version and exit.

posargs
    Positional arguments passed directly to the test command defined in tox.ini. These arguments are typically separated from tox options by -- (e.g., tox -- pytest -k 'my_test').

tox is a command-line tool that automates and standardizes the testing of Python projects across various environments. It achieves this by creating isolated virtual environments for each specified test configuration (e.g., different Python versions, dependency sets). For each environment, tox installs the project and its dependencies, then runs the defined test commands. This ensures that a project's tests pass consistently across different Python interpreters and dependency combinations, preventing unexpected failures due to environment-specific issues. It relies on a tox.ini configuration file to define these environments and testing steps, making the testing process reproducible and easy to integrate into CI/CD pipelines. It's important to note that tox is not a native Linux system command, but a Python application typically installed via pip.

tox requires Python and pip to be installed on the system to function. Its operation is entirely dependent on a valid tox.ini configuration file in the project's root directory. Virtual environments created by tox can consume significant disk space over time, especially when managing many Python versions and diverse dependencies. Internet access is often necessary for tox to download project dependencies during environment setup.

tox relies heavily on a tox.ini file, typically located in the project's root directory. This file defines the various test environments, their specific dependencies, the commands to execute within each environment, and other custom settings. It is the central hub for customizing tox's behavior for a given project, making the test setup reproducible and shareable.

For each specified test environment, tox creates and manages a separate, isolated Python virtual environment. This crucial isolation ensures that dependencies for one test configuration do not conflict with another, providing a clean and reproducible testing sandpit for each run. tox handles the entire lifecycle of these environments, including creation, package installation, and execution of test commands.

tox was initially created by Holger Krekel (also known for pytest) to address the challenge of consistently testing Python packages against multiple Python versions and dependency combinations. Its development focused on standardizing the test execution process for Python projects, making it a critical tool for maintaining software quality and ensuring compatibility across different environments. It has since become an industry standard for Python project testing and CI/CD integration, widely adopted in open-source and commercial projects.

python(1), pip(1), virtualenv(1), pytest(1)