refactor(example): fixture-driven unit testing and Nagios range defaults

Fixture files in unit-test/stdout/ are now named after the scenario
(e.g. humidity-42-percent), not after an expected plugin state. The
expected state is encoded in the testcase `id` instead, so a single
fixture can drive multiple testcases that vary --warning / --critical
(or any other parameter) to reach OK, WARN and CRIT.

example plugin:
- Parse the threshold value from the fetched data (first integer in
  stdout, populated from a hwmon humidity sensor reading) so unit
  tests can drive the state machine via fixtures.
- Skip SQLite delta calculation in --test mode to avoid persistent
  state between runs.
- Default --warning / --critical are now Nagios range strings ('80',
  '90') to match the type=str parser contract.

example unit tests:
- Rename stdout/ok-basic to stdout/humidity-42-percent.
- Expand TESTS to four cases that reuse the same fixture:
  ok-below-warn, warn-above-warn, crit-above-crit,
  ok-always-ok-masks-crit.

CONTRIBUTING.md: rewrite the unit test naming convention accordingly.

Author: markuslf

CHANGELOG.md

@@ -31,10 +31,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * CONTRIBUTING: add PEP 8 string quoting convention (single quotes, `"""` for triple-quoted)
 * CONTRIBUTING: add README structure guidelines with fixed section order, Fact Sheet template, and Nagios/Icinga check name for SEO
 * CONTRIBUTING: rewrite unit-test section with declarative test pattern, naming conventions, and tox usage
+* 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
 * CONTRIBUTING: run pylint without `--disable` flags
 * CONTRIBUTING: remove inline `pylint: disable` comments from code examples
 * All plugins: improve and expand DESCRIPTION to clearly explain what each plugin does for the admin deploying it
 * All plugins: rewrite all READMEs to follow consistent structure (Overview, Fact Sheet, Help, Usage Examples, States, Perfdata, Troubleshooting, Credits)
+* example: default `--warning` and `--critical` are now Nagios range strings (`'80'`, `'90'`) to match the `type=str` parser contract
+* example: parse the threshold value from the fetched data (humidity sensor reading from the Linux hwmon interface) so unit tests can drive OK/WARN/CRIT transitions via fixtures; skip SQLite delta calculation in `--test` mode to avoid persistent state between runs
+* example: rename unit test fixture `stdout/ok-basic` to `stdout/humidity-42-percent` (scenario-based) and expand tests to demonstrate fixture reuse across threshold combinations
 * example: rewrite as comprehensive skeleton covering all standard patterns (argparse, SQLite delta calculations, regex filtering, `--lengthy` table output, human-readable formatting, get_state/get_worst, Grafana-compatible perfdata)
 * example: rewrite README as skeleton template with Overview, Fact Sheet, States, Perfdata, and Troubleshooting sections
 * Update and extend pre-commit hooks (add `check-added-large-files`, `check-merge-conflict`, `check-yaml`; update all hook versions)

CONTRIBUTING.md

@@ -699,28 +699,33 @@ Unit tests are implemented using the `unittest` framework (<https://docs.python.
 ```text
 check-plugins/my-check/unit-test/
 ├── run                     # the test file
-└── stdout/                 # test data files
-    ├── ok-basic            # descriptive names, not EXAMPLE01
-    ├── warn-threshold
-    └── crit-service-down
+└── stdout/                 # test data files (fixtures)
+    ├── empty-response      # scenario-based names, not EXAMPLE01
+    ├── three-nodes-healthy
+    └── three-nodes-one-down
 ```
 
 Only create `stderr/` if a test actually needs to inject stderr data. Do not create empty `retc/` or `stderr/` directories.
 
 
 #### Test data file naming
 
-Use descriptive, lowercase, hyphenated names that indicate the expected state and scenario:
+Fixture files in `stdout/` are named after the **scenario** they represent, not after an expected plugin state. The expected state depends on the combination of fixture content and plugin parameters (thresholds, filters, switches) and therefore cannot be encoded in the fixture filename alone.
 
-* `ok-basic`, `ok-empty-result`, `ok-all-healthy`
-* `warn-threshold-exceeded`, `warn-high-load`
-* `crit-service-down`, `crit-disk-full`
-* `unknown-missing-dependency`
+Use descriptive, lowercase, hyphenated names that describe the shape of the data:
+
+* `empty-response`, `single-node`, `three-nodes-healthy`
+* `cpu-80-percent`, `disk-nearly-full`, `memory-400mb-used`
+* `three-nodes-one-down`, `malformed-json`, `service-unreachable`
+
+The same fixture may (and should) be reused by multiple testcases that vary the plugin parameters to reach different states. For example, a single `cpu-80-percent` fixture can drive an `ok-below-warn` test with `--warning 90 --critical 95`, a `warn-above-warn` test with `--warning 70 --critical 95`, and a `crit-above-crit` test with `--warning 50 --critical 75`.
+
+The expected state is encoded in the testcase `id` instead (see below).
 
 
 #### Writing tests
 
-Define a `TESTS` list and use `lib.lftest.run()` to execute each testcase:
+Define a `TESTS` list and use `lib.lftest.run()` to execute each testcase. The testcase `id` should lead with the expected state (`ok-`, `warn-`, `crit-`, `unknown-`), followed by a short description of what is being verified. This is what appears in the subtest output and documents the intent of each case.
 
 ```python
 #!/usr/bin/env python3
@@ -734,19 +739,34 @@ import lib.lftest
 
 
 TESTS = [
+    # Same fixture, three different threshold combinations.
     {
-        'id': 'ok-basic',
-        'test': 'stdout/ok-basic,,0',
-        'params': '--warning 80 --critical 90',
+        'id': 'ok-below-warn',
+        'test': 'stdout/cpu-80-percent,,0',
+        'params': '--warning 90 --critical 95',
         'assert-retc': STATE_OK,
-        'assert-in': ['Everything is ok.'],
+        'assert-in': ['80%'],
+    },
+    {
+        'id': 'warn-above-warn',
+        'test': 'stdout/cpu-80-percent,,0',
+        'params': '--warning 70 --critical 95',
+        'assert-retc': STATE_WARN,
+        'assert-regex': r'80%.*\[WARNING\]',
     },
     {
-        'id': 'crit-threshold-exceeded',
-        'test': 'stdout/crit-threshold-exceeded,,0',
-        'params': '--critical 50',
+        'id': 'crit-above-crit',
+        'test': 'stdout/cpu-80-percent,,0',
+        'params': '--warning 50 --critical 75',
         'assert-retc': STATE_CRIT,
-        'assert-regex': r'95.0%.*\[CRITICAL\]',
+        'assert-regex': r'80%.*\[CRITICAL\]',
+    },
+    # Different fixture, different scenario.
+    {
+        'id': 'unknown-malformed-json',
+        'test': 'stdout/malformed-json,,0',
+        'params': '--warning 80 --critical 90',
+        'assert-retc': STATE_UNKNOWN,
     },
 ]
 
@@ -765,6 +785,12 @@ if __name__ == '__main__':
     unittest.main()
 ```
 
+Naming rules for the testcase `id`:
+
+* Lead with the expected state: `ok-`, `warn-`, `crit-`, `unknown-`.
+* Follow with a short description of what the test verifies (not the fixture name): `ok-below-warn`, `warn-above-warn`, `crit-disk-full`, `unknown-missing-dependency`.
+* `id` must be unique within the `TESTS` list.
+
 Available assertion keys in each testcase dict:
 
 * `assert-retc` (`int`, required): Expected return code (`STATE_OK`, `STATE_WARN`, `STATE_CRIT`, `STATE_UNKNOWN`).

check-plugins/example/example

@@ -31,19 +31,19 @@ except ImportError:
 
 
 __author__ = 'Linuxfabrik GmbH, Zurich/Switzerland'
-__version__ = '2026040903'
+__version__ = '2026041202'
 
 DESCRIPTION = """Skeleton plugin demonstrating all standard patterns and library functions:
 argparse with append/deprecated/suppress parameters, (success, result) error handling,
 SQLite delta calculations (no continuous counters), regex filtering, --lengthy table output,
 human-readable formatting (bytes, seconds, numbers), perfdata, get_state/get_worst, and
 Grafana-compatible panel design."""
 
-DEFAULT_CRIT = 90
+DEFAULT_CRIT = '90'
 DEFAULT_LENGTHY = False
 DEFAULT_MODULE = ['calendar', 'Core', 'ctype', 'date']
 DEFAULT_TIMEOUT = 8
-DEFAULT_WARN = 80
+DEFAULT_WARN = '80'
 
 
 def parse_args():
@@ -228,23 +228,9 @@ def main():
         args.MODULE = DEFAULT_MODULE
     # args.NAME is not set here          # case 3: None means "check all"
 
-    # create the SQLite database and table for delta calculations
-    conn = lib.base.coe(
-        lib.db_sqlite.connect(
-            filename='linuxfabrik-monitoring-plugins-example.db',
-        ),
-    )
-    definition = """
-        name        TEXT NOT NULL,
-        rx_bytes    INT NOT NULL,
-        timestamp   INT NOT NULL
-    """
-    lib.base.coe(lib.db_sqlite.create_table(conn, definition, drop_table_first=False))
-    lib.base.coe(lib.db_sqlite.create_index(conn, 'name'))
-
     # fetch data
     if args.TEST is None:
-        cmd = 'cat /etc/os-release'
+        cmd = 'cat /sys/class/hwmon/hwmon0/humidity1_input'
         stdout = lib.base.coe(get_data(cmd, timeout=args.TIMEOUT))
     else:
         # do not call the command, put in test data
@@ -263,14 +249,20 @@ def main():
         lib.base.cu('Unable to compile regex.')
 
     # analyze data
-    title = 'Lorem ipsum'
+    title = 'humidity1'
     if args.NAME is not None:
         # case 3: user specified --name, so filter
         if title not in args.NAME:
             pass  # in loops: continue
     if any(item.search(title) for item in compiled_ignore_regex):
         pass  # in loops: continue
-    value = str(lib.time.now())[-2:]
+    # Parse the value to evaluate from the fetched data. Real plugins parse
+    # their own data formats (JSON, regex, SNMP walks, etc.). This skeleton
+    # reads a humidity sensor from the Linux `hwmon` interface and picks
+    # the first integer from stdout, so unit tests can drive the state
+    # machine via fixtures.
+    match = re.search(r'(\d+)', stdout)
+    value = match.group(1) if match else '0'
     uptime = 123456
     rx_bytes = 1073741824
     # multiline f-string: use parentheses for implicit concatenation
@@ -282,61 +274,80 @@ def main():
     item_state = lib.base.get_state(value, args.WARN, args.CRIT, _operator='range')
     state = lib.base.get_worst(state, item_state)
 
-    # store current measurement and calculate delta from previous run
-    now = lib.time.now()
-    lib.base.coe(
-        lib.db_sqlite.insert(
-            conn,
-            {'name': title, 'rx_bytes': rx_bytes, 'timestamp': now},
+    # calculate delta from the previous run using a local SQLite database.
+    # In test mode (--test), skip persistent state entirely and use a
+    # fixed stand-in so unit tests can exercise the full state machine
+    # without depending on run order or leftover temp files.
+    if args.TEST is None:
+        conn = lib.base.coe(
+            lib.db_sqlite.connect(
+                filename='linuxfabrik-monitoring-plugins-example.db',
+            ),
         )
-    )
-    lib.base.coe(lib.db_sqlite.cut(conn, _max=2))
-    lib.base.coe(lib.db_sqlite.commit(conn))
-
-    rows = lib.base.coe(
-        lib.db_sqlite.select(
-            conn,
-            """
-        SELECT *
-        FROM perfdata
-        WHERE name = :name
-        ORDER BY timestamp DESC
-        """,
-            {'name': title},
+        definition = """
+            name        TEXT NOT NULL,
+            rx_bytes    INT NOT NULL,
+            timestamp   INT NOT NULL
+        """
+        lib.base.coe(lib.db_sqlite.create_table(conn, definition, drop_table_first=False))
+        lib.base.coe(lib.db_sqlite.create_index(conn, 'name'))
+
+        now = lib.time.now()
+        lib.base.coe(
+            lib.db_sqlite.insert(
+                conn,
+                {'name': title, 'rx_bytes': rx_bytes, 'timestamp': now},
+            )
         )
-    )
-    if len(rows) < 2:
-        lib.db_sqlite.close(conn)
-        lib.base.oao('Waiting for more data.', STATE_OK)
+        lib.base.coe(lib.db_sqlite.cut(conn, _max=2))
+        lib.base.coe(lib.db_sqlite.commit(conn))
+
+        rows = lib.base.coe(
+            lib.db_sqlite.select(
+                conn,
+                """
+            SELECT *
+            FROM perfdata
+            WHERE name = :name
+            ORDER BY timestamp DESC
+            """,
+                {'name': title},
+            )
+        )
+        if len(rows) < 2:
+            lib.db_sqlite.close(conn)
+            lib.base.oao('Waiting for more data.', STATE_OK)
+
+        timestamp_diff = rows[0]['timestamp'] - rows[1]['timestamp']
+        if timestamp_diff == 0:
+            timestamp_diff = 1
+        rx_bytes_per_second = int(
+            float(rows[0]['rx_bytes'] - rows[1]['rx_bytes']) / timestamp_diff,
+        )
+        if any(
+            [
+                timestamp_diff < 0,
+                rx_bytes_per_second < 0,
+            ]
+        ):
+            # happens after a reboot
+            lib.db_sqlite.close(conn)
+            lib.base.oao('Waiting for more data.', STATE_OK)
 
-    timestamp_diff = rows[0]['timestamp'] - rows[1]['timestamp']
-    if timestamp_diff == 0:
-        timestamp_diff = 1
-    rx_bytes_per_second = int(
-        float(rows[0]['rx_bytes'] - rows[1]['rx_bytes']) / timestamp_diff,
-    )
-    if any(
-        [
-            timestamp_diff < 0,
-            rx_bytes_per_second < 0,
-        ]
-    ):
-        # happens after a reboot
         lib.db_sqlite.close(conn)
-        lib.base.oao('Waiting for more data.', STATE_OK)
-
-    lib.db_sqlite.close(conn)
+    else:
+        rx_bytes_per_second = 1234567
 
     # build the message
     msg += (
-        f'{value}% used{lib.base.state2str(item_state, prefix=" ")}'
+        f'{value}% humidity{lib.base.state2str(item_state, prefix=" ")}'
         f', up {lib.human.seconds2human(uptime)}'
         f' since {lib.time.epoch2iso(lib.time.now() - uptime)}'
         f', {lib.human.bytes2human(rx_bytes_per_second)}/s'
         f', {lib.human.number2human(42000)} items'
     )
     perfdata += lib.base.get_perfdata(
-        'cpu-usage',
+        'humidity',
         value,
         uom='%',
         warn=args.WARN,

check-plugins/example/unit-test/run

@@ -17,13 +17,45 @@ from lib.globals import STATE_CRIT, STATE_OK, STATE_UNKNOWN, STATE_WARN
 import lib.lftest
 
 
+# Fixture files in stdout/ are named after the scenario (the shape of the
+# data), not after the expected plugin state. The expected state lives in
+# the testcase `id` and depends on the combination of fixture content and
+# plugin parameters. The same fixture can therefore drive multiple
+# testcases that vary --warning/--critical (or any other parameter) to
+# reach different states. See CONTRIBUTING.md for the full convention.
+#
+# The humidity-42-percent fixture contains the raw reading from the
+# Linux hwmon humidity sensor. The skeleton parses the first integer
+# from stdout as its value. The four testcases below reuse that one
+# fixture and only differ in thresholds and switches.
 TESTS = [
     {
-        'id': 'ok-basic',
-        'test': 'stdout/ok-basic,,0',
-        'params': '--token=dummy',
+        'id': 'ok-below-warn',
+        'test': 'stdout/humidity-42-percent,,0',
+        'params': '--token=dummy --warning 80 --critical 90',
+        'assert-retc': STATE_OK,
+        'assert-in': ['42%'],
+    },
+    {
+        'id': 'warn-above-warn',
+        'test': 'stdout/humidity-42-percent,,0',
+        'params': '--token=dummy --warning 40 --critical 90',
+        'assert-retc': STATE_WARN,
+        'assert-regex': r'42%.*\[WARNING\]',
+    },
+    {
+        'id': 'crit-above-crit',
+        'test': 'stdout/humidity-42-percent,,0',
+        'params': '--token=dummy --warning 30 --critical 40',
+        'assert-retc': STATE_CRIT,
+        'assert-regex': r'42%.*\[CRITICAL\]',
+    },
+    {
+        'id': 'ok-always-ok-masks-crit',
+        'test': 'stdout/humidity-42-percent,,0',
+        'params': '--token=dummy --warning 30 --critical 40 --always-ok',
         'assert-retc': STATE_OK,
-        'assert-in': ['Waiting for more data.'],
+        'assert-regex': r'42%.*\[CRITICAL\]',
     },
 ]
 

check-plugins/example/unit-test/stdout/humidity-42-percent

@@ -0,0 +1 @@
+42