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 = True
           tags =
             check
             format
           deps =
             ...

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:

     --arg argument | -A argument
             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-spec spec | -m spec
             Pass an additional specification for Tox environments to satisfy, e.g.  “-m
             '@check'” to only run static checkers and not unit tests.

     --parallel spec | -p spec
             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 run

     Group 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-tests

     Execute 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⟩.