TOX-STAGES(1)

💖 TOX-STAGES(1) 💖

okay so bestie, welcome to the manual for tox-stages — she runs your Tox environments in groups (aka stages), and she stops on failure. this is the Gen Z-friendly tour, but every single flag and fact is still in here, no cap. 🫶

---

✨ 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 🦋

so the whole vibe of tox-stages is: run Tox test environments in several stages, with one or more environments running in parallel at each stage. main character scheduling energy. 👑

and here's the dramatic part — 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. periodt. 💀

why is that iconic? because it lets quick static check tools like e.g. ruff stop the testing process early. it also lets you do scenarios like running all the static check tools before the package's unit or functional tests, so you don't get unnecessary failures on simple errors. ate. 💅

---

🎀 TAGGING TOX TEST ENVIRONMENTS 🎀

here's the tea: tox-stages 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. 🧚

that module adds a tags list of strings to the definition of each Tox environment. and you specify those tags in the tox.ini file like this:

[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 (which means success, bestie ✅) 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. and yeah — 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. no second chances, she's done. 🙈

the run subcommand accepts the following options:

• --arg argument | -A argument — pass an additional command-line argument to each Tox invocation. you can specify this option 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. (yes bestie, this is the same tea as above — she said it twice, it's that important. 💅)

---

🔥 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⟩. 💖

---

and that's the whole page bestie, you're officially a tox-stages expert 🎓✨ this one came from the Debian manual, dated May 13, 2023. go forth and stage your tests, ily 💜🦋🌸