From 6d85ed42f11b67ca6082d3d07c36d012d75fa632 Mon Sep 17 00:00:00 2001 From: Geetika Kapoor Date: Tue, 9 Jun 2026 13:44:46 +0100 Subject: [PATCH] docs: clarify local tox setup and unit test matrix usage Document tox 4 requirement and PATH fix for --user installs so make targets use the correct tox binary. Describe how to use selective unit test environments instead of running the full matrix. Signed-off-by: Geetika Kapoor --- docs/developing.md | 18 +++++++++++++++--- docs/testing.md | 11 ++++++++++- 2 files changed, 25 insertions(+), 4 deletions(-) diff --git a/docs/developing.md b/docs/developing.md index 0434ed6..1b5022c 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -14,11 +14,23 @@ ## Development environment -To develop and to run tests you need to install `tox` and `tox-ansible` on -your machine. +Install `tox` (version 4 or newer) and `tox-ansible`: ``` -pip install --user tox tox-ansible +pip install --user 'tox>=4' tox-ansible +``` + +With `--user`, `tox` is in `~/.local/bin`. Put it first on `PATH` before +`make` targets that use `tox` (`build-venv`, `test-unit`, `test-sanity`): + +``` +export PATH="$HOME/.local/bin:$PATH" # whole shell session +``` + +or + +``` +PATH="$HOME/.local/bin:$PATH" make # command only ``` ### Virtualenv for development diff --git a/docs/testing.md b/docs/testing.md index 965f417..423fcb7 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -27,6 +27,16 @@ Run unit tests with `tox-ansible` like so: make test-unit ``` +`make test-unit` runs the full matrix in parallel. For local development, run +one environment instead. If you installed tox with `--user`, put `~/.local/bin` +first on `PATH` before running `tox`. See [developing.md](developing.md). + +``` +tox -e unit-py3.11-2.16 --ansible --conf tox-ansible.ini +``` + +List available unit envs with `tox -f unit --ansible --conf tox-ansible.ini -l`. + ### Running tests with ansible-test In order to test changes with `ansible-test`, it is recommended to bind mount @@ -135,4 +145,3 @@ ansible-playbook -i examples/inventory.kubevirt.yml examples/play-delete.yml # terminate the environment hack/e2e-setup.sh --cleanup ``` -