table of contents
| TOX-STAGES(1) | General Commands Manual | TOX-STAGES(1) |
NAME¶
tox-stages — run
Tox environments in groups, stop on failure
SYNOPSIS¶
tox-stages |
[-f filename]
available |
tox-stages |
[-f filename]
run [--arg
arg... | -A
arg...] [--match-spec
spec | -m
spec] [--parallel
spec | -p
spec] [stage...] |
DESCRIPTION¶
The tox-stages tool is used to run Tox
test environments in several stages, one or more environments running in
parallel at each stage. If any of the test environments run at some stage
should fail, tox-stages will stop, not run anything
further, and exit with a non-zero exit code. 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.
TAGGING TOX TEST ENVIRONMENTS¶
The tox-stages tool expects to be able to
invoke an installation of Tox that will load the
tox_trivtags plugin module distributed as part of
the test-stages library. This module will add a
tags list of strings to the definition of each Tox
environment; those tags can be specified in the
tox.ini file as follows:
[testenv:format]skip_install = Truetags = check formatdeps = ...SUBCOMMANDS¶
available - can the tox-stages tool be run on this system¶
The tox-stages
available subcommand exits with a code of zero
(indicating success) if there is a suitable version of Tox installed in the
same Python execution environment as the tox-stages
tool itself.
run - run some Tox environments in stages¶
The tox-stages run
subcommand starts the process of running Tox test environments, grouped in
stages. If any of the test environments run at some stage should fail,
tox-stages will stop, not run anything further, and
exit with a non-zero exit code.
The run subcommand accepts the following
options:
--argargument |-Aargument- Pass an additional command-line argument to each Tox invocation. This option may be specified more than once, and the arguments will be passed in the order given.
--match-specspec |-mspec- Pass an additional specification for Tox environments to satisfy, e.g. “-m '@check'” to only run static checkers and not unit tests.
--parallelspec |-pspec- Specify which stages to run in parallel. The spec parameter is a list of stage indices (1, 2, etc.) or ranges (4-6); the tests in the specified stages will be run in parallel, while the tests in the rest of the stages will not. By default, all tests are run in parallel. The special values “” (an empty string), “0” (a single character, the digit zero), or “none” will be treated as an empty set, and no tests will be run in parallel.
The positional arguments to the run
subcommand are interpreted as test stage specifications as described in the
parse-stages library's documentation. If no stage specifications are given
on the command line, tox-stages will read the
pyproject.toml file in the same directory as the
tox.ini file, and will look for a
tool.test-stages.stages list of strings to use.
FILES¶
If no stage specifications are given on the command line,
tox-stages will read the
pyproject.toml file in the same directory as the
tox.ini file, and will look for a
tool.test-stages.stages list of strings to use.
EXAMPLES¶
Run all the stages as defined in the
pyproject.toml
file's tool.test-stages.stages parameter:
tox-stages runGroup Tox environments into stages as defined in the pyproject.toml file, but then only run the ones marked with the "check" tag that also have names containing the string "format":
tox-stages run -m '@check and
format'Run a specific set of stages, passing -- -k
slug as additional Tox arguments so that e.g. a
pytest environment that uses the Tox
{posargs} variable may only run a selected subset of
tests:
tox-stages -A -- -A -k -A slug @check
unit-testsExecute a somewhat more complicated recipe:
- -
- first, run all test environments with names containing "ruff" in parallel
- -
- then, run the rest of the test environments marked with the "check" tag, but not marked with the "manual" tag, one by one
- -
- then, run all test environments with names containing "unit" in parallel
- -
- finally, run the rest of the test environments marked with the "tests" tag, but not marked with the "manual" tag, in parallel
tox-stages -p 1,3-4 ruff '@check and
not @manual' unit '@tests and not @manual'AUTHORS¶
The tox-stages tool, along with its
documentation, is developed as part of the test-stages
library by Peter Pentchev
⟨roam@ringlet.net⟩.
| May 13, 2023 | Debian |