NAME

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

SYNOPSIS

     tox-stages [-f filename] available
     tox-stages [-f filename] run [stage-spec...]
     tox-stages --help

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:

           tox-stages run ruff @check @tests

     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:

           tox-stages run 'ruff and not @manual' @check '@tests or @ci'

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.