Testing: tox

Introduction

tox is a command-line tool that automates testing in isolated environments. It’s primarily used to ensure code works consistently across different Python versions and environments, while simplifying setup and integration with CI/CD pipelines.

tox can run test suites, linters, or any shell command within virtual environments it creates and manages automatically.

Docs: https://tox.readthedocs.io/en/latest/

Key Features

  • Automates multi-version Python testing

  • Manages isolated test environments with virtualenv

  • Integrates seamlessly with pytest, pre-commit, and linters

  • Simplifies CI setup and ensures local-dev parity

  • Highly configurable and extensible with plugins

Installation

Install tox as a development dependency using uv:

uv add --dev tox

Configuration

Define environments and commands in a tox.ini file at your project root:

[tox]
envlist = py312, py313, pre-commit
skipsdist = true

[testenv]
deps = uv
allowlist_externals = uv
commands_pre = uv pip install -e .
commands = uv run pytest

[testenv:pre-commit]
skip_install = true
deps = pre-commit
setenv = SKIP=install-dependencies,test
commands = pre-commit run --all-files

Explanation:

  • envlist: Environments to run (e.g., Python versions, pre-commit)

  • commands_pre: Run setup commands like editable install

  • commands: Run tests with pytest

  • skip_install: Skip package install for environments like pre-commit

Usage

Run all defined environments:

tox

Run a specific environment (e.g., pre-commit only):

tox -e pre-commit

Run multiple environments:

tox -e py312,pre-commit

View the full configuration and environment list:

tox -av

Additional Resources

Next Step

Set up Sphinx for generating clean, versioned project documentation. Sphinx is highly extensible and integrates with reStructuredText, Markdown, and docstring introspection.

Uninstall

To remove tox:

uv remove --dev tox