Skip to content

Commit 75daf26

Browse files
committed
docs(contributing): document fast/container test split and tox dev-headers
Two CONTRIBUTING additions to match the current test layout: - "Running tests" now explains the fast vs container split, documents the `--no-container` / `--only-container` flags and `tools/run-container-tests`, and notes that `tox` runs the fast suite via `tools/run-unit-tests --no-container`. - Add a dev-headers note: `linuxfabrik-lib` pulls in `netifaces`, which has no binary wheels on PyPI, so every Python version used in the `tox` matrix needs the matching `pythonX.Y-devel` / `pythonX.Y-dev` package installed on the host. Without that, pip falls back to building `netifaces` from source and aborts with `fatal error: Python.h: No such file or directory`.
1 parent b57c313 commit 75daf26

2 files changed

Lines changed: 39 additions & 3 deletions

File tree

CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
6363
* CONTRIBUTING: add README structure guidelines with fixed section order, Fact Sheet template, and Nagios/Icinga check name for SEO
6464
* CONTRIBUTING: remove inline `pylint: disable` comments from code examples
6565
* CONTRIBUTING: require Nagios range support (`type=str`, `_operator='range'`) for threshold parameters in new plugins ([#1067](https://github.com/Linuxfabrik/monitoring-plugins/issues/1067))
66+
* CONTRIBUTING: document the fast-vs-container unit test split, the new `--no-container` / `--only-container` flags on `tools/run-unit-tests`, the `tools/run-container-tests` wrapper, and the `pythonX.Y-devel` system packages needed locally for `tox` to build `netifaces` from source under each matrix interpreter
6667
* CONTRIBUTING: rewrite unit test fixture naming convention - fixtures in `stdout/` are named by scenario (e.g. `cpu-80-percent`), the expected state is encoded in the testcase `id` instead, so a single fixture can be reused by multiple testcases that vary plugin parameters to reach different states
6768
* CONTRIBUTING: rewrite unit-test section with declarative test pattern, naming conventions, and tox usage
6869
* CONTRIBUTING: run pylint without `--disable` flags

CONTRIBUTING.md

Lines changed: 38 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -802,6 +802,13 @@ Available assertion keys in each testcase dict:
802802

803803
#### Running tests
804804

805+
Unit tests come in two flavors:
806+
807+
* **Fast tests** use `--test` to inject fixture data and run in a fraction of a second. They are safe for CI and for the multi-Python-version `tox` matrix.
808+
* **Container tests** build a podman image per target OS, inject the plugin and `lib/`, and exercise the check against a live service. They need podman on the host and take minutes per plugin. A plugin counts as a container test when its `unit-test/` directory has a `containerfiles/` subdirectory.
809+
810+
Everyday commands:
811+
805812
```bash
806813
# single plugin (from its unit-test directory)
807814
cd check-plugins/my-check/unit-test
@@ -810,13 +817,40 @@ cd check-plugins/my-check/unit-test
810817
# single plugin (from the repo root)
811818
python tools/run-unit-tests my-check
812819

813-
# all plugins
820+
# all plugins (fast + container)
814821
python tools/run-unit-tests
815822

816-
# all plugins across multiple Python versions (via tox)
817-
tox
823+
# only the fast tests (used by tox)
824+
python tools/run-unit-tests --no-container
825+
826+
# only the container tests (also available as a thin wrapper)
827+
python tools/run-unit-tests --only-container
828+
python tools/run-container-tests
829+
```
830+
831+
Multi-Python coverage via `tox`:
832+
833+
```bash
834+
tox # all supported Python versions, fast tests only
835+
tox -e py39 # single environment
818836
```
819837

838+
`tox` invokes `tools/run-unit-tests --no-container` so the multi-Python matrix skips the container suite. Run `tools/run-container-tests` separately before a release for full integration coverage.
839+
840+
`tox` builds each Python environment from sdist, and `linuxfabrik-lib` pulls in `netifaces` which has no binary wheels on PyPI. For every Python version in the `tox` matrix you want to run locally, the matching development headers must be installed on the host, otherwise pip falls back to building `netifaces` from source and aborts with `fatal error: Python.h: No such file or directory`:
841+
842+
```bash
843+
# Fedora
844+
sudo dnf install python3.9-devel python3.10-devel python3.11-devel \
845+
python3.12-devel python3.13-devel python3.14-devel
846+
847+
# Debian / Ubuntu
848+
sudo apt install python3.9-dev python3.10-dev python3.11-dev \
849+
python3.12-dev python3.13-dev python3.14-dev
850+
```
851+
852+
`skip_missing_interpreters = true` already skips environments for Python versions that are not installed at all.
853+
820854

821855
#### Container-based tests
822856

@@ -825,6 +859,7 @@ If you want to implement unit tests based on containers, the following rules app
825859
* Each container file does everything necessary to set up a running environment for the check plugin (e.g. install Python if you want to run the plugin inside the container).
826860
* The `./run` unit test simply calls podman and, for each containerfile found, builds the container, injects the libs and the check plugin, and runs the tests - but does not modify the container in any other way.
827861
* See the `keycloak-version` plugin for how to do this.
862+
* `tools/run-unit-tests` auto-detects container tests by looking for a `containerfiles/` subdirectory, so `--no-container` / `--only-container` filter correctly without any per-plugin annotation.
828863

829864

830865
### sudoers File

0 commit comments

Comments
 (0)