NAME¶

tox-stages — run Tox tests in groups, stopping on errors

SYNOPSIS¶

DESCRIPTION¶

The tox-stages tool runs Tox with the specified groups of test environments, stopping if any of the tests in a group should fail. This allows quick static check tools like e.g. ruff to stop the testing process early, and also allows scenarios like running all the static check tools before the package's unit or functional tests to avoid unnecessary failures on simple errors.

If run with the available subcommand, the tox-stages tool will check whether the Python environment that it is running from has a suitable version of Tox installed. If this is so, tox-stages will exit with a status code of 0 without actually running Tox. If a suitable version of Tox is not installed, tox-stages will exit with a non-zero exit code.

If run with the run subcommand, tox-stages will parse the tox.ini file (or the file specified by the -f command-line option), read the definitions of the Tox test environments, group them according to the specified stages, and run the tests in each group in parallel. If the tests in one group fail, the ones in the rest of the groups are not executed at all.

Note that a tag specified for a stage will only match Tox environments that have that exact tag name in their tags list, but an environment name will be matched as a substring; thus, @check will only match the “check” tag, but not “check-manual”, while ruff will match both “ruff” and “ruff-all”.

If the run subcommand is invoked without any parameters, the tox-stages tool will read the pyproject.toml file in the same directory as the tox.ini file being processed, and will look for a tool.test-stages.stages list of strings to use.

ENVIRONMENT¶

The operation of the tox-stages utility is not directly influenced by any environment variables.

FILES¶

If no stage specifications are given to the run subcommand, the pyproject.toml file is read and its tool.test-stages.stages variable (expected to be a list of strings) is used instead.

EXAMPLES¶

Run the very quick checks in any test environments with names that include the string “ruff”, then run all the environments that specify the “check” tag exactly, and then run the environments that specify the “tests” tag:

Do the same, but exclude the ruff-like environments that specify the “manual” tag, and also run the environments that specify the “ci” tag in the last stage:

DIAGNOSTICS¶

The tox-stages utility exits 0 on success, and >0 if an error occurs.

SEE ALSO¶

tox(1)

A description of the stage specification mini-language: https://gitlab.com/ppentchev/parse-stages

STANDARDS¶

No standards were harmed during the production of the tox-stages utility.

HISTORY¶

The tox-stages utility was written by Peter Pentchev in 2023.

AUTHORS¶

Peter Pentchev ⟨roam@ringlet.net⟩

BUGS¶

No, thank you :) But if you should actually find any, please report them to the author.