docs(testing): improve tox test execution and document workflow

amimas · amimas · commit 88e4841cc290 · 2026-03-21T14:53:07.000-04:00
This improves the developer experience by making the testing workflow
more discoverable and flexible.

- Updates `tox.ini` to use `posargs` with default values for the test
  environments. This allows developers to run the full test suite by
  default, or easily specify a single test file to run.

- Adds `description` fields to the unit and functional test
  environments in `tox.ini`. This makes instructions on how to run
  specific tests visible in the output of `tox list`.

- Updates `CONTRIBUTING.rst` with concrete examples for running
  specific unit, API functional, and CLI functional tests, aligning the
  documentation with the new `tox` configuration.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -111,6 +111,9 @@ You need to install ``tox`` (``pip3 install tox``) to run tests and lint checks
    # run unit tests in one python environment only (useful for quick testing during development):
    tox -e py311
 
+   # run a specific unit test file:
+   tox -e py311 -- tests/unit/objects/test_projects.py
+
    # run unit and smoke tests in one python environment only
    tox -e py312,smoke
 
@@ -148,9 +151,15 @@ To run these tests:
    # run the CLI tests:
    tox -e cli_func_v4
 
+   # run a specific CLI functional test file:
+   tox -e cli_func_v4 -- tests/functional/cli/test_cli_v4.py
+
    # run the python API tests:
    tox -e api_func_v4
 
+   # run a specific API functional test file:
+   tox -e api_func_v4 -- tests/functional/api/test_projects.py
+
 When developing tests it can be a little frustrating to wait for GitLab to spin
 up every run. To prevent the containers from being cleaned up afterwards, pass
 ``--keep-containers`` to pytest, i.e.:
diff --git a/tox.ini b/tox.ini
@@ -26,6 +26,7 @@ passenv =
   NO_COLOR
   PWD
   PY_COLORS
+  USER
 setenv = 
   DOCS_SOURCE = docs
   DOCS_BUILD = build/sphinx/html
@@ -35,10 +36,13 @@ usedevelop = True
 install_command = pip install {opts} {packages} -e .
 isolated_build = True
 
+
+[testenv:py{314,313,312,311,310}]
+description = Runs unit tests. For a specific test: tox -e py311 -- <path>
 deps = -r{toxinidir}/requirements.txt
        -r{toxinidir}/requirements-test.txt
 commands =
-  pytest tests/unit {posargs}
+  pytest {posargs:tests/unit}
 
 [testenv:black]
 basepython = python3
@@ -131,14 +135,18 @@ exclude_lines =
   return NotImplemented
 
 [testenv:cli_func_v4]
+description =
+  Runs CLI functional tests. For a specific test: tox -e cli_func_v4 -- <path>
 deps = -r{toxinidir}/requirements-docker.txt
 commands =
-  pytest --script-launch-mode=subprocess --cov --cov-report xml tests/functional/cli {posargs}
+  pytest --script-launch-mode=subprocess --cov --cov-report xml {posargs:tests/functional/cli}
 
 [testenv:api_func_v4]
+description =
+  Runs API functional tests. For a specific test: tox -e api_func_v4 -- <path>
 deps = -r{toxinidir}/requirements-docker.txt
 commands =
-  pytest --cov --cov-report xml tests/functional/api {posargs}
+  pytest --cov --cov-report xml {posargs:tests/functional/api}
 
 [testenv:smoke]
 deps = -r{toxinidir}/requirements-test.txt
