test: add --test hooks and fixture-based unit tests to 7 psutil plugins

Extend the sensors-* pattern to seven plugins that previously had no
unit tests at all, because they call `psutil.*` (or similar host-local
APIs) directly instead of parsing a shell command's output.

Each plugin now has a `--test` argument that short-circuits the live
data fetch and loads the return value from a JSON fixture mirroring
psutil's own shape:

- **load**: fakes `psutil.getloadavg()` + `psutil.cpu_count()` via
  `{loadavg, cpu_count}`. 4 fixtures, 6 testcases.
- **uptime**: fakes `psutil.boot_time()` and `lib.time.now()` via
  `{now, boot_time}` and bypasses the host cache DB under `--test`.
  Asserts stay timezone-agnostic. 4 fixtures, 6 testcases.
- **memory-usage**: mocks `psutil.virtual_memory()` and forces
  `--top=0` in the test path so the live `/proc/<pid>/status` walk
  is skipped. 3 fixtures, 5 testcases.
- **swap-usage**: mocks `psutil.swap_memory()` and skips the live
  per-process swap scan under `--test`. 4 fixtures, 6 testcases.
- **file-descriptors**: replaces the `/proc/sys/fs/file-nr` read with
  a 3-field JSON fixture and forces `--top=0`. 3 fixtures, 5
  testcases.
- **disk-usage**: mocks both `psutil.disk_partitions()` and the
  per-mountpoint `psutil.disk_usage()` via a combined
  `{partitions, usage}` fixture. 4 fixtures, 6 testcases.
- **network-connections**: mocks `psutil.net_connections(kind='inet')`
  with a list of `sconn` namedtuples; the fixture uses a
  human-friendly `{proto, status}` form that the loader maps to the
  right `(family, type)` pair. 3 fixtures, 6 testcases.

All seven plugins bump `__version__` and all 118 unit tests still
pass under `tools/run-unit-tests --no-container`.

Six plugins from the original Category A list were left for a
follow-up because a thin `--test` hook is not enough to cover them:

- **about-me**: 1500-line plugin with data from psutil, lib.net,
  lib.cpu, lib.distro, platform, /etc/os-release, /proc/cpuinfo.
- **disk-io**, **network-io**: SQLite-backed trend state and a
  `lib.cache` max-tracker on top of psutil counters. A clean fixture
  branch needs cache mocking on top of the psutil branch.
- **procs**: iterates `psutil.process_iter()` returning live
  `Process` objects with an `.info` dict; faking the generator is
  bigger than the rest of the plugin.
- **mysql-memory**, **mysql-system**: need a live MySQL connection
  and are better tested with testcontainers-python.

Author: markuslf

check-plugins/disk-usage/disk-usage

@@ -11,12 +11,15 @@
 """See the check's README for more details."""
 
 import argparse
+import json
 import re
 import sys
+from collections import namedtuple
 
 import lib.args
 import lib.base
 import lib.human
+import lib.lftest
 from lib.globals import STATE_CRIT, STATE_OK, STATE_UNKNOWN, STATE_WARN
 
 try:
@@ -25,9 +28,25 @@ except ImportError:
     print('Python module "psutil" is not installed.')
     sys.exit(STATE_UNKNOWN)
 
+# psutil 5.x exposes sdiskpart/sdiskusage under psutil._common,
+# psutil 6+ under psutil._ntuples. Fall back to plain namedtuples
+# with the fields we touch if neither is available.
+try:
+    from psutil._ntuples import sdiskpart, sdiskusage
+except ImportError:
+    try:
+        from psutil._common import sdiskpart, sdiskusage
+    except ImportError:
+        sdiskpart = namedtuple(
+            'sdiskpart', ['device', 'mountpoint', 'fstype', 'opts']
+        )
+        sdiskusage = namedtuple(
+            'sdiskusage', ['total', 'used', 'free', 'percent']
+        )
+
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026040801'
+__version__ = '2026041301'
 
 DESCRIPTION = """Checks used or free disk space for each mounted partition. By default, only physical
 devices are checked (hard disks, USB drives), ignoring pseudo and memory filesystems.
@@ -149,6 +168,13 @@ def parse_args():
         default=None,
     )
 
+    parser.add_argument(
+        '--test',
+        help=lib.args.help('--test'),
+        dest='TEST',
+        type=lib.args.csv,
+    )
+
     parser.add_argument(
         '-w',
         '--warning',
@@ -167,6 +193,48 @@ def parse_args():
     return args
 
 
+def _load_disk_usage_fixture(raw_json):
+    """Convert a test fixture into the two data structures the plugin
+    expects from `psutil.disk_partitions()` and
+    `psutil.disk_usage(mountpoint)`:
+
+    - `partitions`: a list of `sdiskpart(device, mountpoint, fstype, opts)`
+      namedtuples
+    - `usage`: a dict keyed by mountpoint, each value an
+      `sdiskusage(total, used, free, percent)` namedtuple
+
+    Fixture shape:
+
+        {
+          "partitions": [
+            {"device": "/dev/vda1", "mountpoint": "/", "fstype": "ext4",
+             "opts": "rw,relatime"},
+            ...
+          ],
+          "usage": {
+            "/": {"total": <bytes>, "used": <bytes>, "free": <bytes>,
+                  "percent": <0..100>},
+            ...
+          }
+        }
+    """
+    data = json.loads(raw_json)
+    partitions = [
+        sdiskpart(
+            p['device'],
+            p['mountpoint'],
+            p.get('fstype', ''),
+            p.get('opts', ''),
+        )
+        for p in data.get('partitions', [])
+    ]
+    usage = {
+        mp: sdiskusage(u['total'], u['used'], u['free'], u['percent'])
+        for mp, u in data.get('usage', {}).items()
+    }
+    return partitions, usage
+
+
 def compile_regex(regex, what):
     """Return a compiled regex."""
     try:
@@ -255,19 +323,25 @@ def main():
     compiled_exclude_regex = compile_regex(args.EXCLUDE_REGEX, 'exclude-regex')
     compiled_perfdata_regex = compile_regex(args.PERFDATA_REGEX, 'perfdata-regex')
 
-    # analyze data
-    if args.FSTYPE:
-        # user wants to check file system types on his own
-        parts = psutil.disk_partitions(all=True)
+    # fetch data
+    fixture_usage = None
+    if args.TEST is None:
+        if args.FSTYPE:
+            # user wants to check file system types on his own
+            parts = psutil.disk_partitions(all=True)
+        else:
+            # default behaviour - check physical devices only (e.g. hard disks, cd-rom drives,
+            # USB keys) and ignore all others (e.g. pseudo, memory, duplicate, inaccessible
+            # filesystems)
+            try:
+                parts = psutil.disk_partitions(all=False)
+            except AttributeError:
+                lib.base.cu(
+                    'Did not find physical devices (e.g. hard disks, cd-rom drives, USB keys).'
+                )
     else:
-        # default behaviour - check physical devices only (e.g. hard disks, cd-rom drives, USB keys)
-        # and ignore all others (e.g. pseudo, memory, duplicate, inaccessible filesystems)
-        try:
-            parts = psutil.disk_partitions(all=False)
-        except AttributeError:
-            lib.base.cu(
-                'Did not find physical devices (e.g. hard disks, cd-rom drives, USB keys).'
-            )
+        stdout, _, _ = lib.lftest.test(args.TEST)
+        parts, fixture_usage = _load_disk_usage_fixture(stdout)
 
     for part in parts:
         # sdiskpart(device='/dev/vda2', mountpoint='/', fstype='ext4', opts='rw,relatime')
@@ -307,7 +381,12 @@ def main():
                 continue
 
         try:
-            usage = psutil.disk_usage(part.mountpoint)
+            if fixture_usage is not None:
+                if part.mountpoint not in fixture_usage:
+                    raise FileNotFoundError(part.mountpoint)
+                usage = fixture_usage[part.mountpoint]
+            else:
+                usage = psutil.disk_usage(part.mountpoint)
         except (PermissionError, FileNotFoundError, OSError):
             table_data.append(
                 {

check-plugins/disk-usage/unit-test/run

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8; py-indent-offset: 4 -*-
+#
+# Author:  Linuxfabrik GmbH, Zurich, Switzerland
+# Contact: info (at) linuxfabrik (dot) ch
+#          https://www.linuxfabrik.ch/
+# License: The Unlicense, see LICENSE file.
+
+# https://github.com/Linuxfabrik/monitoring-plugins/blob/main/CONTRIBUTING.md
+
+import sys
+sys.path.insert(0, '..')
+
+import unittest
+
+from lib.globals import STATE_CRIT, STATE_OK, STATE_WARN
+import lib.lftest
+
+
+# The disk-usage plugin normally calls `psutil.disk_partitions()` to
+# enumerate mountpoints and then `psutil.disk_usage(mountpoint)` for
+# each one. Its `--test` hook replaces both calls with a JSON
+# fixture:
+#
+#     {
+#       "partitions": [
+#         {"device": "...", "mountpoint": "...", "fstype": "...", "opts": "..."},
+#         ...
+#       ],
+#       "usage": {
+#         "<mountpoint>": {"total": <bytes>, "used": <bytes>,
+#                          "free": <bytes>, "percent": <0..100>},
+#         ...
+#       }
+#     }
+TESTS = [
+    {
+        'id': 'ok-single-root-nominal',
+        'test': 'stdout/single-root-nominal,,0',
+        'assert-retc': STATE_OK,
+        'assert-in': ['/ 30.0%'],
+    },
+    {
+        'id': 'ok-two-mounts-root-and-boot',
+        'test': 'stdout/two-mounts-root-and-boot,,0',
+        'assert-retc': STATE_OK,
+        'assert-in': [
+            'Everything is ok.',
+            '/',
+            '/boot',
+        ],
+    },
+    {
+        'id': 'warn-single-root-above-warn',
+        'test': 'stdout/single-root-warn,,0',
+        'assert-retc': STATE_WARN,
+        'assert-in': ['91.0%', '[WARNING]'],
+    },
+    {
+        'id': 'crit-single-root-above-crit',
+        'test': 'stdout/single-root-crit,,0',
+        'assert-retc': STATE_CRIT,
+        'assert-in': ['98.0%', '[CRITICAL]'],
+    },
+    {
+        'id': 'ok-always-ok-masks-critical',
+        'test': 'stdout/single-root-crit,,0',
+        'params': '--always-ok',
+        'assert-retc': STATE_OK,
+        'assert-in': ['98.0%'],
+    },
+    {
+        'id': 'ok-exclude-boot-leaves-only-root',
+        'test': 'stdout/two-mounts-root-and-boot,,0',
+        'params': '--exclude-pattern=boot',
+        'assert-retc': STATE_OK,
+        'assert-not-in': ['/boot'],
+    },
+]
+
+
+class TestCheck(unittest.TestCase):
+
+    check = '../disk-usage'
+
+    def test(self):
+        for t in TESTS:
+            with self.subTest(id=t['id']):
+                lib.lftest.run(self, self.check, t)
+
+
+if __name__ == '__main__':
+    unittest.main()

check-plugins/disk-usage/unit-test/stdout/single-root-crit

@@ -0,0 +1,8 @@
+{
+  "partitions": [
+    {"device": "/dev/vda1", "mountpoint": "/", "fstype": "ext4", "opts": "rw,relatime"}
+  ],
+  "usage": {
+    "/": {"total": 107374182400, "used": 104857600000, "free": 2516582400, "percent": 98.0}
+  }
+}

check-plugins/disk-usage/unit-test/stdout/single-root-nominal

@@ -0,0 +1,8 @@
+{
+  "partitions": [
+    {"device": "/dev/vda1", "mountpoint": "/", "fstype": "ext4", "opts": "rw,relatime"}
+  ],
+  "usage": {
+    "/": {"total": 107374182400, "used": 32212254720, "free": 75161927680, "percent": 30.0}
+  }
+}

check-plugins/disk-usage/unit-test/stdout/single-root-warn

@@ -0,0 +1,8 @@
+{
+  "partitions": [
+    {"device": "/dev/vda1", "mountpoint": "/", "fstype": "ext4", "opts": "rw,relatime"}
+  ],
+  "usage": {
+    "/": {"total": 107374182400, "used": 96636764160, "free": 10737418240, "percent": 91.0}
+  }
+}

check-plugins/disk-usage/unit-test/stdout/two-mounts-root-and-boot

@@ -0,0 +1,10 @@
+{
+  "partitions": [
+    {"device": "/dev/vda1", "mountpoint": "/", "fstype": "ext4", "opts": "rw,relatime"},
+    {"device": "/dev/vda2", "mountpoint": "/boot", "fstype": "ext4", "opts": "rw,relatime"}
+  ],
+  "usage": {
+    "/":     {"total": 107374182400, "used": 40000000000, "free": 67374182400, "percent": 37.0},
+    "/boot": {"total": 1073741824, "used": 314572800, "free": 759169024, "percent": 29.0}
+  }
+}

check-plugins/file-descriptors/file-descriptors

@@ -11,12 +11,14 @@
 """See the check's README for more details."""
 
 import argparse
+import json
 import sys
 from collections import Counter
 
 import lib.args
 import lib.base
 import lib.human
+import lib.lftest
 import lib.version
 from lib.globals import STATE_OK, STATE_UNKNOWN
 
@@ -28,7 +30,7 @@ except ImportError:
 
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026040801'
+__version__ = '2026041301'
 
 DESCRIPTION = """Checks the system-wide file descriptor usage as a percentage of the kernel maximum.
 Also lists the top processes consuming the most file descriptors to help identify
@@ -78,6 +80,13 @@ def parse_args():
         default=DEFAULT_TOP,
     )
 
+    parser.add_argument(
+        '--test',
+        help=lib.args.help('--test'),
+        dest='TEST',
+        type=lib.args.csv,
+    )
+
     parser.add_argument(
         '-w',
         '--warning',
@@ -92,6 +101,22 @@ def parse_args():
     return args
 
 
+def _load_file_descriptors_fixture(raw_json):
+    """Convert a test fixture into the list of floats the plugin
+    expects from parsing `/proc/sys/fs/file-nr`. The kernel file has
+    the form "<allocated>\\t<unused>\\t<max>\\n"; our fixture JSON
+    supplies the three numbers directly:
+
+        {"allocated": <int>, "unused": <int>, "max": <int>}
+    """
+    data = json.loads(raw_json)
+    return [
+        float(data['allocated']),
+        float(data.get('unused', 0)),
+        float(data['max']),
+    ]
+
+
 def top(count):
     """Get top X processes opening file descriptors."""
     cnt = Counter()
@@ -132,8 +157,15 @@ def main():
     perfdata = ''
     state = STATE_OK
 
-    with open('/proc/sys/fs/file-nr') as file:
-        fs = [float(item) for item in file.readline().split('\t')]
+    # fetch data
+    if args.TEST is None:
+        with open('/proc/sys/fs/file-nr') as file:
+            fs = [float(item) for item in file.readline().split('\t')]
+    else:
+        stdout, _, _ = lib.lftest.test(args.TEST)
+        fs = _load_file_descriptors_fixture(stdout)
+        # force --top=0 under --test so we don't walk real processes
+        args.TOP = 0
 
     files_allocated = fs[0]  # The number of allocated file handles
     files_max = fs[2]  # The number of system-wide maximum number of file handles