CheatPress

tox Test automation

Version 4.67.1 · source

tox, Postcard, light preview Light · Postcard 102 × 152 mm · PDF tox, Postcard, dark preview Dark · Postcard 102 × 152 mm · PDF tox, Postcard, ink saver preview Ink saver · Postcard 102 × 152 mm · PDF
tox, A5, light preview Light · A5 148 × 210 mm · PDF tox, A5, dark preview Dark · A5 148 × 210 mm · PDF tox, A5, ink saver preview Ink saver · A5 148 × 210 mm · PDF
tox, A4, light preview Light · A4 210 × 297 mm · PDF tox, A4, dark preview Dark · A4 210 × 297 mm · PDF tox, A4, ink saver preview Ink saver · A4 210 × 297 mm · PDF
tox, A4 landscape, light preview Light · A4 landscape 297 × 210 mm · PDF tox, A4 landscape, dark preview Dark · A4 landscape 297 × 210 mm · PDF tox, A4 landscape, ink saver preview Ink saver · A4 landscape 297 × 210 mm · PDF
tox, A3, light preview Light · A3 297 × 420 mm · PDF tox, A3, dark preview Dark · A3 297 × 420 mm · PDF tox, A3, ink saver preview Ink saver · A3 297 × 420 mm · PDF
tox, A3 landscape, light preview Light · A3 landscape 420 × 297 mm · PDF tox, A3 landscape, dark preview Dark · A3 landscape 420 × 297 mm · PDF tox, A3 landscape, ink saver preview Ink saver · A3 landscape 420 × 297 mm · PDF
tox, Letter, light preview Light · Letter 8.5 × 11 in · PDF tox, Letter, dark preview Dark · Letter 8.5 × 11 in · PDF tox, Letter, ink saver preview Ink saver · Letter 8.5 × 11 in · PDF
tox, Tabloid, light preview Light · Tabloid 11 × 17 in · PDF tox, Tabloid, dark preview Dark · Tabloid 11 × 17 in · PDF tox, Tabloid, ink saver preview Ink saver · Tabloid 11 × 17 in · PDF

Start here

tox quickstart
Create a config
tox
Run default envs
tox -e <env>
Run one env
tox -e <env> -- <args>
Pass args to commands
tox run -e <e1>,<e2>
Run several envs
tox p
Run envs in parallel
tox -r -e <env>
Rebuild the env
tox l
List environments

Concepts

  1. Package build sdist/wheel
  2. Env virtualenv in .tox/
  3. Install deps + package
  4. Run exit code = result

Running

tox
Run the envs in env_list
tox run
Same, explicit subcommand (alias r)
tox -e <env>
Run a single environment
tox -e <e1>,<e2>
Run several named environments
tox -e <env> -- <args>
Forward args to {posargs}
tox -e ALL
Run every defined environment
tox -r -e <env>
Recreate the env from scratch
tox -f <factor>
Run envs containing a factor
Several names after one -f must all match; repeat -f for OR.
tox -m <label>
Run envs under a label
tox --skip-env <regex>
Exclude envs matching a regex
tox -s
Skip missing interpreters
tox --fail-fast
Stop after the first failing env
tox -n -e <env>
Build the env, skip the commands
tox -i
Disable output capture
tox -v
More verbose (repeat for more)
tox -c <file>
Use another config file or folder
tox -x <env>.<key>=<val>
Override one config value
tox --installpkg <file>
Test a prebuilt sdist or wheel

Parallel

tox p
Run envs in parallel (alias of run-parallel)
tox p -p <n>
Limit to n parallel envs
Default is auto = CPU count; 0 disables.
tox p -o
Stream output live while running
tox p -e <e1>,<e2>
Parallel run of chosen envs

Inspect

tox l
List envs with descriptions
tox l -d
List only default envs
tox c -e <env>
Show the resolved config of an env
tox c -e <env> -k <key>
Show only chosen keys
tox c -e ALL
Resolved config of every env
tox c --core
Show core (non-env) settings
tox c --format toml
Output as ini, json or toml
tox depends
Show env run order
tox --version
Show tox and plugin versions

Other commands

tox quickstart
Interactively create a config (alias q)
tox exec -e <env> -- <cmd>
Run any command inside an env
tox devenv <dir>
Create a dev virtualenv from an env
-e picks the env; default is py.

Config file

[tox]
Core section in tox.ini
env_list = <e1>, <e2>
Default environments
requires = tox>=4.2
Needed tox and plugins (auto-provisioned)
labels = <name>=<e1>,<e2>
Name a group of envs
[testenv]
Base section for all envs
[testenv:<env>]
Settings for one env
description = <text>
Shown by tox l
deps = <pkg>
Packages to install
commands = <cmd> {posargs}
Commands to run, one per line
commands_pre = <cmd>
Run before commands
commands_post = <cmd>
Run after commands, even on failure
extras = <name>
Install optional dependencies
pass_env = <VAR>
Let env vars through to the env
set_env = <VAR>=<val>
Set env vars
change_dir = <dir>
Working dir for commands
allowlist_externals = <cmd>
Allow commands from outside the env
Without this tox refuses system commands such as make.
base_python = python3.13
Pick the interpreter
skip_install = true
Do not install your package
package = wheel
sdist, wheel, editable or skip
dependency_groups = <group>
Install PEP 735 groups (tox 4.22+)
depends = <env>
Run only after another env (parallel)
ignore_outcome = true
Report failure without failing the run
ignore_errors = true
Continue after a failing command

Substitution & factors

{posargs}
Args after -- on the command line
{posargs:<default>}
Args, or a default if none given
{env_name}
Name of the current env
{tox_root}
Directory of the config file
{env_python}
Interpreter of the env
{env:<VAR>:<default>}
Read an environment variable
<factor>: <value>
Line applies only if the env has the factor
py3{12,13}-{a,b}
Expand into every combination
[testenv:py3{12,13}]
Section for a set of generated envs
Common factors
Name Python
py313 3.13
py current interpreter
pypy3 PyPy 3
3.13 3.13 (tox 4)

Recipes

Minimal tox.ini
[tox]env_list = lint, py313[testenv]deps = pytestcommands = pytest {posargs}[testenv:lint]skip_install = truedeps = ruffcommands = ruff check .
Matrix with factors
[tox]env_list = py3{12,13}-{django,flask}[testenv]deps =  pytest  django: django  flask: flaskcommands = pytest
Native tox.toml
env_list = ["lint", "3.13"][env_run_base]dependency_groups = ["test"]commands = [["pytest", { replace = "posargs", extend = true }]][env.lint]skip_install = truedeps = ["ruff"]commands = [["ruff", "check", "."]]
One test, fresh env
tox -r -e py313 -- -x -k <name>
Same matrix in CI
# one job per Pythontox -e py313# or all at once on a runnertox p