Skip to content

Run Tox tests in groups, stopping on errors

[Home | GitLab | PyPI | ReadTheDocs]

The test-stages library provides command-line tools that wrap Python test environment runners such as Tox or Nox, invoking them so as the various tests are run in parallel, in groups, as specified on the command line. This allows the fastest tests to be run first, and the slower ones to only be started if it makes sense (e.g. if tools like ruff or flake8 did not uncover any trivial syntax errors).

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.

The syntax for grouping the test environments to be run is described in the parse-stages library's documentation.

Running Tox tests in groups

The tox-stages tool may be invoked with a list of stages specified on the command line:

    tox-stages run @check @tests

If the tox-stages run command is invoked without any stage specifications, the tool looks for the stages list of strings in the [tool.test-stages] section of the pyproject.toml file:

    stages = ["ruff and not @manual", "@check", "@tests"]


The test-stages library is developed by Peter Pentchev in a GitLab repository. This documentation is hosted at Ringlet with a copy at ReadTheDocs.