You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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`.
Copy file name to clipboardExpand all lines: CHANGELOG.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -63,6 +63,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
63
63
* CONTRIBUTING: add README structure guidelines with fixed section order, Fact Sheet template, and Nagios/Icinga check name for SEO
64
64
* CONTRIBUTING: remove inline `pylint: disable` comments from code examples
65
65
* 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
66
67
* 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
67
68
* CONTRIBUTING: rewrite unit-test section with declarative test pattern, naming conventions, and tox usage
68
69
* CONTRIBUTING: run pylint without `--disable` flags
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+38-3Lines changed: 38 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -802,6 +802,13 @@ Available assertion keys in each testcase dict:
802
802
803
803
#### Running tests
804
804
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
+
805
812
```bash
806
813
# single plugin (from its unit-test directory)
807
814
cd check-plugins/my-check/unit-test
@@ -810,13 +817,40 @@ cd check-plugins/my-check/unit-test
810
817
# single plugin (from the repo root)
811
818
python tools/run-unit-tests my-check
812
819
813
-
# all plugins
820
+
# all plugins (fast + container)
814
821
python tools/run-unit-tests
815
822
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
818
836
```
819
837
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`:
`skip_missing_interpreters = true` already skips environments for Python versions that are not installed at all.
853
+
820
854
821
855
#### Container-based tests
822
856
@@ -825,6 +859,7 @@ If you want to implement unit tests based on containers, the following rules app
825
859
* 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).
826
860
* 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.
827
861
* 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.
0 commit comments