feat(lftest): add run() function for declarative unit tests

Author: markuslf

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Add GitHub Actions workflow to automatically build and deploy API documentation to GitHub Pages
 * Add pre-commit hooks
 * disk.py: add `get_owner()`
+* lftest.py: add `run()` function for declarative, data-driven unit tests using `subTest()`
 * nextcloud.py: new library
 * txt.py: add `exception2text()`
 * winrm.py: add `WINRM_CONFIGURATION_NAME` option to `run_ps()`

lftest.py

@@ -6,23 +6,99 @@
 #          https://www.linuxfabrik.ch/
 # License: The Unlicense, see LICENSE file.
 
-# https://github.com/Linuxfabrik/monitoring-plugins/blob/main/CONTRIBUTING.rst
+# https://github.com/Linuxfabrik/monitoring-plugins/blob/main/CONTRIBUTING.md
 
 """Provides test functions for unit tests.
 """
 
 import os
 
+from . import base
 from . import disk
+from . import shell
 
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2025042001'
+__version__ = '2026040901'
+
+
+def run(test_instance, plugin, testcase):
+    """Run a single testcase against a plugin and assert the results.
+
+    Designed to be used with unittest.TestCase.subTest() for declarative,
+    data-driven test definitions. Each testcase is a dict describing what
+    to run and what to expect.
+
+    ### Parameters
+    - **test_instance** (`unittest.TestCase`): The test instance (self)
+      for assertions.
+    - **plugin** (`str`): Path to the plugin executable.
+    - **testcase** (`dict`): Test definition with keys:
+      - `test` (`str`): --test parameter value,
+        e.g. `'stdout/ok-healthy,,0'`.
+      - `params` (`str`, optional): Additional plugin parameters.
+        Default: `''`.
+      - `assert-retc` (`int`): Expected return code (STATE_OK, etc.).
+      - `assert-in` (`list` of `str`, optional): Strings that must
+        appear in stdout.
+      - `assert-not-in` (`list` of `str`, optional): Strings that must
+        not appear in stdout.
+      - `assert-regex` (`str`, optional): Regex pattern that must match
+        stdout.
+      - `assert-stderr` (`str`, optional): Expected stderr content.
+        Default: `''`.
+
+    ### Example
+    >>> TESTS = [
+    ...     {
+    ...         'id': 'ok-all-healthy',
+    ...         'test': 'stdout/ok-all-healthy,,0',
+    ...         'assert-retc': STATE_OK,
+    ...         'assert-in': ['Everything is ok.'],
+    ...     },
+    ...     {
+    ...         'id': 'crit-threshold-exceeded',
+    ...         'test': 'stdout/crit-threshold-exceeded,,0',
+    ...         'params': '--critical 50',
+    ...         'assert-retc': STATE_CRIT,
+    ...         'assert-regex': r'90.0%.*\\[CRITICAL\\]',
+    ...     },
+    ... ]
+    ...
+    ... class TestCheck(unittest.TestCase):
+    ...     check = '../my-plugin'
+    ...
+    ...     def test(self):
+    ...         for t in TESTS:
+    ...             with self.subTest(id=t['id']):
+    ...                 lib.lftest.run(self, self.check, t)
+    """
+    params = testcase.get('params', '')
+    cmd = f'{plugin} {params} --test={testcase["test"]}'.strip()
+    stdout, stderr, retc = base.coe(shell.shell_exec(cmd))
+
+    test_instance.assertEqual(
+        retc,
+        testcase['assert-retc'],
+        f'Expected retc {testcase["assert-retc"]}, got {retc}',
+    )
+
+    expected_stderr = testcase.get('assert-stderr', '')
+    test_instance.assertEqual(stderr, expected_stderr)
+
+    for text in testcase.get('assert-in', []):
+        test_instance.assertIn(text, stdout)
+
+    for text in testcase.get('assert-not-in', []):
+        test_instance.assertNotIn(text, stdout)
+
+    if 'assert-regex' in testcase:
+        test_instance.assertRegex(stdout, testcase['assert-regex'])
 
 
 def test(args):
     """
-    Returns the content of two files and the provided return code. The first file represents STDOUT, 
+    Returns the content of two files and the provided return code. The first file represents STDOUT,
     and the second represents STDERR. This function is useful for enabling unit tests.
 
     ### Parameters