test(coverage): expand unit tests for core helpers and handlers

Incrementally improve test coverage by adding focused tests for:

- Alert handling (SHOW_ALERT/HIDE_ALERT with timer conversion)
- Notification wrappers (socket/value/simple/delayed routing)
- Action and data handler factories (getActionHandlers, getDataHandlers)
- Config utilities (getConfigPath, getModuleDir, getConfig merging)
- Helper utilities (translate, sendResponse, checkForExecError, getIpAddresses)
- Changelog retrieval (answerGetChangelog error handling)
- Socket notifications (CURRENT_STATUS, REQUEST_DEFAULT_SETTINGS, REMOTE_ACTION)

Coverage improvements:
- Statements: 39% → 49% (+10%)
- Functions: 29% → 57% (+28%)
- Branches: 71% → 83% (+12%)
- Total tests: 81 → 152 (+71 tests, +88%)

All new tests follow incremental testing strategy: minimal mocking,
high-value assertions, focused on catching real regressions.

Update coverage thresholds to reflect achieved stability (45%/50%/75%)
and document why we stop here (diminishing returns, hardware/system
commands require E2E testing).

Author: KristjanESPERANTO

package.json

@@ -90,9 +90,9 @@
       "**/*.md"
     ],
     "check-coverage": true,
-    "branches": 60,
-    "lines": 30,
-    "functions": 20,
-    "statements": 30
+    "branches": 75,
+    "lines": 45,
+    "functions": 50,
+    "statements": 45
   }
 }

tests/README.md

@@ -53,13 +53,22 @@ All tests run in CI/CD without MagicMirror runtime or browser dependencies.
 | `executeQuery.core.test.js`                       | Module visibility, notifications, system actions (SHOW/HIDE/REFRESH/RESTART)             |
 | `executeQuery.error.test.js`                      | Error handling for malformed JSON, missing params                                        |
 | `api.helpers.test.js`                             | JSON payload parsing, delay parameter handling                                           |
+| `executeQuery.alerts.test.js`                     | Alert handling (SHOW_ALERT/HIDE_ALERT parameter handling)                                |
+| `executeQuery.notifications.test.js`              | Notification wrapper functions and routing logic                                         |
+| `executeQuery.handlers.test.js`                   | Action handlers, delayed queries, callback scheduling                                    |
+| `helper.config.test.js`                           | Config path resolution, module directory handling                                        |
+| `helper.utils.test.js`                            | Response handling, translation, error checking, network utilities                        |
+| `answerGetChangelog.test.js`                      | Changelog file retrieval and error handling                                              |
+| `socketNotification.test.js`                      | Socket notification routing (CURRENT_STATUS, REQUEST_DEFAULT_SETTINGS, REMOTE_ACTION)    |
+| `helper.getConfig.test.js`                        | Config merging with defaults from moduleData                                             |
 | `utils.test.js`, `configUtils.test.js`            | String-format helpers and `cleanConfig` regressions                                      |
 
 ### DOM tests (`tests/dom/`)
 
-| Suite                  | Purpose                                                    |
-| ---------------------- | ---------------------------------------------------------- |
-| `remote.smoke.test.js` | Frontend logic tests using happy-dom (no browser required) |
+| Suite                        | Purpose                                                              |
+| ---------------------------- | -------------------------------------------------------------------- |
+| `remote.smoke.test.js`       | Frontend logic tests using happy-dom (no browser required)           |
+| `MMM-Remote-Control.test.js` | Module initialization and lockStrings handling with edge case checks |
 
 ### HTTP-layer tests (`tests/integration/`)
 
@@ -73,16 +82,16 @@ Together these suites focus on isolated logic (unit tests) and HTTP contract ver
 
 As of December 2024, actual coverage stands at:
 
-| Metric           | Value | Threshold | Notes                                   |
-| ---------------- | ----- | --------- | --------------------------------------- |
-| Statements       | ~43%  | 30%       | Improved from ~26% with Priority 1+2    |
-| Branches         | ~79%  | 60%       | Strong branch coverage                  |
-| Functions        | ~46%  | 20%       | Improved from ~17% with edge case tests |
-| Lines            | ~43%  | 30%       | Mirrors statement coverage              |
-| `node_helper.js` | ~15%  | -         | Improved with state/value action tests  |
-| `API/api.js`     | ~62%  | -         | Edge cases covered                      |
+| Metric           | Value | Threshold | Notes                                      |
+| ---------------- | ----- | --------- | ------------------------------------------ |
+| Statements       | ~49%  | 30%       | Reached plateau with core logic covered    |
+| Branches         | ~83%  | 60%       | Strong branch coverage                     |
+| Functions        | ~57%  | 20%       | Major handlers and utilities tested        |
+| Lines            | ~49%  | 30%       | Mirrors statement coverage                 |
+| `node_helper.js` | ~28%  | -         | Core actions and notification flow covered |
+| `API/api.js`     | ~62%  | -         | Edge cases and routing verified            |
 
-Thresholds now provide meaningful regression protection while remaining achievable.
+Thresholds now provide meaningful regression protection while remaining achievable. Further gains would require testing system commands and hardware integration better suited for E2E or manual testing.
 
 ## What we deliberately skip (and why)
 
@@ -160,24 +169,31 @@ This approach catches route wiring bugs, middleware issues, and response format
 - Hardware-dependent command testing (shutdown, reboot, monitor control)
 - Git/network-dependent install/update flows
 
-## Coverage improvement strategy
+## Coverage status and philosophy
 
-To reach 50%+ coverage efficiently, follow an incremental approach focusing on **high-impact, low-mock areas**:
+As of December 2025, coverage has reached a healthy plateau through **incremental, high-value testing**:
 
-1. Pick **one** untested function from `node_helper.js` or `API/api.js`
-2. Write test with **minimal setup** (reuse existing helper factories)
-3. Verify it catches a real regression (e.g., bounds checking, null handling)
-4. Check coverage gain and repeat until diminishing returns
+- **~49% statements** – Core logic paths covered
+- **~57% functions** – Major handlers tested
+- **~83% branches** – Strong conditional coverage
+- **152 tests** – Mix of unit, integration, and DOM tests
 
-**Target: 50% statements** is realistic and valuable. Beyond that, focus shifts to integration/manual testing.
+### Why we stop here
 
-### What NOT to chase:
+Further coverage gains would hit **diminishing returns**:
 
-- **Don't test for coverage percentage alone** – Every test should catch real bugs or prevent regressions
-- **Avoid mocking complexity** – If a test needs >5 mocks, it's testing the wrong thing
-- **Skip brittle integration points** – File system, network, hardware, DOM manipulation
-- **Don't duplicate HTTP-layer tests** – Already covered at the right abstraction level
-- **Helper utilities** – Only add edge cases to `lib/configUtils.js` and `lib/utils.js` if behavior changes
+- Remaining untested code is primarily **system commands** (`shutdown`, `reboot`, monitor control) requiring hardware/privileges
+- **Complex integration points** (PM2, Electron, git operations) need E2E tests, not unit tests
+- **Express routing details** already verified at HTTP layer
+- Mock complexity would exceed test value
+
+### Testing principles (when adding new tests)
+
+- **Test behavior, not coverage** – Every test should catch real bugs or prevent regressions
+- **Minimal mocking** – If a test needs >5 mocks, reconsider the abstraction
+- **Skip brittle integration points** – File system, network, hardware, DOM manipulation better suited for E2E
+- **Avoid duplication** – Don't re-test what HTTP-layer tests already cover
+- **Edge cases only** – For utilities (`lib/configUtils.js`, `lib/utils.js`), add tests when behavior changes
 
 ---
 

tests/unit/answerGetChangelog.test.js

@@ -0,0 +1,93 @@
+const assert = require("node:assert/strict");
+const {test, describe, before, after} = require("node:test");
+const path = require("node:path");
+const fs = require("node:fs");
+
+// Add tests/shims to module resolution
+const ModuleLib = require("node:module");
+const shimDir = path.resolve(__dirname, "../shims");
+process.env.NODE_PATH = shimDir + (process.env.NODE_PATH ? path.delimiter + process.env.NODE_PATH : "");
+if (typeof ModuleLib._initPaths === "function") ModuleLib._initPaths();
+
+const helperFactory = require("../../node_helper.js");
+
+function freshHelper () {
+  const h = Object.create(helperFactory);
+  h.__responses = [];
+  h.sendResponse = (res, error, data) => {
+    h.__responses.push({err: error, data});
+    if (res && res.json) {
+      res.json(data || {success: !error});
+    }
+  };
+  h.getModuleDir = () => "test_modules";
+  return h;
+}
+
+describe("answerGetChangelog", () => {
+  const testModulesDir = path.join(__dirname, "../..", "test_modules");
+  const testModuleDir = path.join(testModulesDir, "test-module");
+  const changelogPath = path.join(testModuleDir, "CHANGELOG.md");
+
+  before(() => {
+    // Create test module directory and CHANGELOG
+    fs.mkdirSync(testModuleDir, {recursive: true});
+    fs.writeFileSync(changelogPath, "# Changelog\n\n## v1.0.0\n- Initial release\n");
+  });
+
+  after(() => {
+    // Clean up test files
+    try {
+      fs.rmSync(testModulesDir, {recursive: true, force: true});
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  test("returns changelog content when file exists", () => {
+    const helper = freshHelper();
+    helper.answerGetChangelog = helperFactory.answerGetChangelog.bind(helper);
+    const mockRes = {
+      json: (data) => {
+        mockRes.jsonData = data;
+      }
+    };
+
+    helper.answerGetChangelog({module: "test-module"}, mockRes);
+
+    assert.equal(helper.__responses.length, 1);
+    assert.equal(helper.__responses[0].err, undefined);
+    assert.equal(helper.__responses[0].data.action, "GET_CHANGELOG");
+    assert.equal(helper.__responses[0].data.module, "test-module");
+    assert.ok(helper.__responses[0].data.changelog.includes("# Changelog"));
+    assert.ok(helper.__responses[0].data.changelog.includes("Initial release"));
+  });
+
+  test("returns error when changelog not found", () => {
+    const helper = freshHelper();
+    helper.answerGetChangelog = helperFactory.answerGetChangelog.bind(helper);
+    const mockRes = {
+      json: (data) => {
+        mockRes.jsonData = data;
+      }
+    };
+
+    helper.answerGetChangelog({module: "nonexistent-module"}, mockRes);
+
+    assert.equal(helper.__responses.length, 1);
+    assert.ok(helper.__responses[0].err instanceof Error);
+    assert.equal(helper.__responses[0].err.message, "Changelog not found");
+    assert.equal(helper.__responses[0].data.action, "GET_CHANGELOG");
+  });
+
+  test("includes query in error response", () => {
+    const helper = freshHelper();
+    helper.answerGetChangelog = helperFactory.answerGetChangelog.bind(helper);
+    const mockRes = {};
+    const query = {module: "missing-module", other: "data"};
+
+    helper.answerGetChangelog(query, mockRes);
+
+    assert.equal(helper.__responses[0].data.query, query);
+  });
+});

tests/unit/executeQuery.handlers.test.js

@@ -0,0 +1,176 @@
+const assert = require("node:assert/strict");
+const {test, describe} = require("node:test");
+
+// Add tests/shims to module resolution
+const path = require("node:path");
+const ModuleLib = require("node:module");
+const shimDir = path.resolve(__dirname, "../shims");
+process.env.NODE_PATH = shimDir + (process.env.NODE_PATH ? path.delimiter + process.env.NODE_PATH : "");
+if (typeof ModuleLib._initPaths === "function") ModuleLib._initPaths();
+
+const helperFactory = require("../../node_helper.js");
+
+function freshHelper () {
+  const h = Object.create(helperFactory);
+  h.__socketNotifications = [];
+  h.__responses = [];
+  h.sendSocketNotification = (action, payload) => {
+    h.__socketNotifications.push({action, payload});
+  };
+  h.sendResponse = (_res, error, data) => { h.__responses.push({err: error, data}); };
+  h.waiting = [];
+  return h;
+}
+
+describe("callAfterUpdate", () => {
+  test("schedules callback and sends UPDATE notification", () => {
+    const helper = freshHelper();
+    helper.callAfterUpdate = helperFactory.callAfterUpdate.bind(helper);
+    let callbackExecuted = false;
+
+    helper.callAfterUpdate(() => {
+      callbackExecuted = true;
+    }, 50);
+
+    // Should add to waiting array
+    assert.equal(helper.waiting.length, 1);
+    assert.equal(helper.waiting[0].finished, false);
+
+    // Should send UPDATE notification
+    assert.equal(helper.__socketNotifications.length, 1);
+    assert.equal(helper.__socketNotifications[0].action, "UPDATE");
+
+    // Wait for timeout and trigger callback
+    return new Promise((resolve) => {
+      setTimeout(() => {
+        helper.waiting[0].run();
+        assert.ok(callbackExecuted, "Callback should be executed");
+        resolve();
+      }, 60);
+    });
+  });
+
+  test("waitObject.run() marks as finished and executes callback once", () => {
+    const helper = freshHelper();
+    helper.callAfterUpdate = helperFactory.callAfterUpdate.bind(helper);
+    let callCount = 0;
+
+    helper.callAfterUpdate(() => {
+      callCount++;
+    });
+
+    const waitObject = helper.waiting[0];
+    waitObject.run();
+    assert.equal(waitObject.finished, true);
+    assert.equal(callCount, 1);
+
+    // Second run should not execute callback
+    waitObject.run();
+    assert.equal(callCount, 1, "Callback should only execute once");
+  });
+
+  test("uses default timeout of 3000ms when not specified", () => {
+    const helper = freshHelper();
+    helper.callAfterUpdate = helperFactory.callAfterUpdate.bind(helper);
+
+    helper.callAfterUpdate(() => {});
+
+    // Just verify it doesn't throw and creates wait object
+    assert.equal(helper.waiting.length, 1);
+    assert.ok(helper.waiting[0].callback);
+  });
+});
+
+describe("getActionHandlers", () => {
+  test("returns object with all action handlers", () => {
+    const helper = freshHelper();
+    helper.thisConfig = {};
+    helper.getActionHandlers = helperFactory.getActionHandlers.bind(helper);
+
+    const handlers = helper.getActionHandlers();
+
+    // Verify some key handlers exist
+    assert.ok(typeof handlers.SHOW === "function");
+    assert.ok(typeof handlers.HIDE === "function");
+    assert.ok(typeof handlers.TOGGLE === "function");
+    assert.ok(typeof handlers.BRIGHTNESS === "function");
+    assert.ok(typeof handlers.REFRESH === "function");
+    assert.ok(typeof handlers.SHOW_ALERT === "function");
+    assert.ok(typeof handlers.NOTIFICATION === "function");
+    assert.ok(typeof handlers.DELAYED === "function");
+  });
+
+  test("handler functions are bound with correct context", () => {
+    const helper = freshHelper();
+    helper.thisConfig = {};
+    helper.getActionHandlers = helperFactory.getActionHandlers.bind(helper);
+    helper.handleSimpleNotification = helperFactory.handleSimpleNotification.bind(helper);
+
+    const handlers = helper.getActionHandlers();
+
+    // Call REFRESH handler
+    handlers.REFRESH({action: "REFRESH"});
+
+    // Should send notification via helper's method
+    assert.equal(helper.__socketNotifications.length, 1);
+    assert.equal(helper.__socketNotifications[0].action, "REFRESH");
+  });
+});
+
+describe("getDataHandlers", () => {
+  test("returns object with all data handlers", () => {
+    const helper = freshHelper();
+    helper.translation = {};
+    helper.userPresence = true;
+    helper.getConfig = () => ({});
+    helper.getDataHandlers = helperFactory.getDataHandlers.bind(helper);
+
+    const handlers = helper.getDataHandlers();
+
+    // Verify key handlers exist
+    assert.ok(typeof handlers.translations === "function");
+    assert.ok(typeof handlers.config === "function");
+    assert.ok(typeof handlers.brightness === "function");
+    assert.ok(typeof handlers.temp === "function");
+    assert.ok(typeof handlers.userPresence === "function");
+    assert.ok(typeof handlers.classes === "function");
+  });
+
+  test("translations handler returns translation data", () => {
+    const helper = freshHelper();
+    helper.translation = {HELLO: "Hello", WORLD: "World"};
+    helper.sendResponse = helperFactory.sendResponse.bind(helper);
+    helper.getDataHandlers = helperFactory.getDataHandlers.bind(helper);
+    const mockRes = {
+      status: () => mockRes,
+      json: (data) => {
+        mockRes.jsonData = data;
+      }
+    };
+
+    const handlers = helper.getDataHandlers();
+    handlers.translations({data: "translations"}, mockRes);
+
+    assert.equal(mockRes.jsonData.success, true);
+    assert.deepEqual(mockRes.jsonData.data, {HELLO: "Hello", WORLD: "World"});
+  });
+
+  test("userPresence handler returns presence status", () => {
+    const helper = freshHelper();
+    helper.userPresence = false;
+    helper.sendResponse = helperFactory.sendResponse.bind(helper);
+    helper.getDataHandlers = helperFactory.getDataHandlers.bind(helper);
+    const mockRes = {
+      status: () => mockRes,
+      json: (data) => {
+        mockRes.jsonData = data;
+      }
+    };
+
+    const handlers = helper.getDataHandlers();
+    handlers.userPresence({data: "userPresence"}, mockRes);
+
+    assert.equal(mockRes.jsonData.success, true);
+    assert.equal(mockRes.jsonData.result, false);
+  });
+});