@iobroker/testing 5.2.1 → 5.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024-2025 AlCalzone <d.griesel@gmx.net>
+Copyright (c) 2024-2026 AlCalzone <d.griesel@gmx.net>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -148,11 +148,72 @@ These methods take a mock database and adapter and create a set of asserts for y
 
 #### MockDatabase
 
-TODO
+`MockDatabase` is a minimalistic reimplementation of ioBroker's Objects and States DB that operates purely on in-memory `Map`s. It is created for you by `createMocks()`, but you can also instantiate it directly:
+
+```ts
+const { MockDatabase } = require("@iobroker/testing");
+const database = new MockDatabase();
+```
+
+Objects and states are stored under their fully qualified ID (e.g. `"adapter.0.some.state"`). Wherever a method comes in two overloads, you can either pass the full ID as a single string or pass the namespace and the rest of the ID separately (they are joined with `"."`). Pattern-based getters accept `ioBroker`-style wildcards (`*`).
+
+Populating the database:
+
+-   `publishObject(obj: ioBroker.PartialObject)` adds or replaces an object. The object **must** have an `_id` and a `type`; missing `common`/`native` are filled from a default template.
+-   `publishObjects(...objects)` publishes multiple objects at once.
+-   `publishStateObjects(...objects)` / `publishChannelObjects(...objects)` / `publishDeviceObjects(...objects)` publish objects while forcing their `type` to `state` / `channel` / `device`.
+-   `publishState(id: string, state: Partial<ioBroker.State> | null | undefined)` sets a state (missing properties are filled from a default template). Passing `null`/`undefined` deletes it.
+-   `publishStates(states: Record<string, Partial<ioBroker.State> | null | undefined>)` sets multiple states at once.
+
+Reading and querying:
+
+-   `hasObject(id)` / `hasObject(namespace, id)` returns whether an object exists.
+-   `getObject(id)` / `getObject(namespace, id)` returns an object or `undefined`.
+-   `getObjects(pattern, type?)` / `getObjects(namespace, pattern, type?)` returns all matching objects as a `Record<string, ioBroker.Object>`, optionally filtered by `type`.
+-   `hasState(id)` / `hasState(namespace, id)` returns whether a state exists.
+-   `getState(id)` / `getState(namespace, id)` returns a state or `undefined`.
+-   `getStates(pattern)` returns all matching states as a `Record<string, ioBroker.State>`.
+
+Deleting and resetting:
+
+-   `deleteObject(objOrID)` removes an object (accepts the object or its ID).
+-   `deleteState(id)` removes a state.
+-   `clearObjects()` / `clearStates()` empty the respective store, `clear()` empties both. Call this between tests to start with a fresh database.
 
 #### MockAdapter
 
-TODO
+`MockAdapter` is a mock of ioBroker's `Adapter` class in which every method is replaced by a [Sinon stub](https://sinonjs.org/releases/latest/stubs/). It is created by `createMocks()` and is backed by a `MockDatabase`, so the DB-related methods actually read from and write to that database instead of a real DB.
+
+```ts
+const { database, adapter } = utils.unit.createMocks();
+// or with custom adapter options (name, instance, config, ...)
+const { database, adapter } = utils.unit.createMocks({ name: "my-adapter" });
+```
+
+Because the methods are Sinon stubs, you can assert on how your adapter code called them and override their behavior in individual tests:
+
+```ts
+// Assert that a state was set
+adapter.setState.callCount.should.equal(1);
+adapter.setState.getCall(0).args[0].should.equal("info.connection");
+
+// Override the return value / behavior for a single test
+adapter.getForeignObjectAsync.resolves({ common: { name: "test" } });
+```
+
+Key features:
+
+-   **Connected to the database:** methods like `getObject`, `setObject`, `setObjectNotExists`, `extendObject`, `getState`, `setState`, `setStateChanged`, `delState`, their `Foreign` variants and `getObjectView` / `getObjectList` are implemented to operate on the backing `MockDatabase`. IDs that are not fully qualified are automatically prefixed with the adapter namespace. The remaining methods are plain stubs that do nothing until you give them a behavior.
+-   **Promisified methods:** for every callback-style method, the corresponding `...Async` version (e.g. `getStateAsync`) is available, just like on a real adapter.
+-   **Event handlers:** the handlers your adapter registers (via `adapter.on(...)` or the adapter options) are captured and exposed so you can invoke them from your tests: `readyHandler`, `stateChangeHandler`, `objectChangeHandler`, `messageHandler` and `unloadHandler`. For example, call `await adapter.readyHandler()` to simulate the adapter's startup.
+-   **Logger:** `adapter.log` is a `MockLogger` whose `debug` / `info` / `warn` / `error` methods are stubs you can assert on.
+-   **`terminate()`** throws an error (carrying the exit reason) instead of exiting the process, so you can assert that your adapter tried to terminate.
+
+Resetting the mock between tests:
+
+-   `resetMockHistory()` clears the recorded call history (call counts, arguments, ...) of all stubs and the logger, but keeps any custom behavior you configured.
+-   `resetMockBehavior()` restores the default behavior of all stubs, discarding your overrides.
+-   `resetMock()` does both.
 
 ### Example
 

package/build/lib/adapterTools.js

@@ -51,7 +51,7 @@ exports.getAdapterDependencies = getAdapterDependencies;
 const typeguards_1 = require("alcalzone-shared/typeguards");
 const debug_1 = __importDefault(require("debug"));
 const fs_extra_1 = require("fs-extra");
-const path = __importStar(require("path"));
+const path = __importStar(require("node:path"));
 const debug = (0, debug_1.default)('testing:unit:adapterTools');
 /**
  * Loads an adapter's package.json

package/build/lib/executeCommand.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.executeCommand = executeCommand;
-const child_process_1 = require("child_process");
+const node_child_process_1 = require("node:child_process");
 const isWindows = /^win/.test(process.platform);
 /**
  * Executes a command and returns the exit code and (if requested) the stdout
@@ -55,7 +55,7 @@ function executeCommand(command, argsOrOptions, options) {
         try {
             let bufferedStdout;
             let bufferedStderr;
-            const cmd = (0, child_process_1.spawn)(command, args, spawnOptions).on('close', (code, signal) => {
+            const cmd = (0, node_child_process_1.spawn)(command, args, spawnOptions).on('close', (code, signal) => {
                 resolve({
                     exitCode: code ?? undefined,
                     signal: signal ?? undefined,

package/build/lib/str2regex.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.str2regex = str2regex;
 function str2regex(pattern) {
     return new RegExp(pattern
-        .replace(/\\/g, '\\\\') // Backslashes escapen
+        .replace(/\\/g, '\\\\') // Backslashes escape
         .replace(/\./g, '\\.') // Punkte als solche matchen
         .replace(/\*/g, '.*') // Wildcard in Regex umsetzen
         .replace(/!/g, '?!'));

package/build/tests/integration/index.d.ts

@@ -6,7 +6,9 @@ export interface TestAdapterOptions {
     /** How long to wait before the adapter startup is considered successful */
     waitBeforeStartupSuccess?: number;
     /**
-     * Which JS-Controller version or dist-tag should be used for the tests. Default: dev
+     * Which JS-Controller version or dist-tag should be used for the tests.
+     * Default: `dev`, except on Node.js <= 20 where it defaults to `7.2.2`, the last
+     * js-controller version that still supports Node.js 18 and 20.
      * This should only be changed during active development.
      */
     controllerVersion?: string;

package/build/tests/integration/lib/adapterSetup.js

@@ -46,6 +46,8 @@ const executeCommand_1 = require("../../../lib/executeCommand");
 const tools_1 = require("./tools");
 const debug = (0, debug_1.default)('testing:integration:AdapterSetup');
 class AdapterSetup {
+    adapterDir;
+    testDir;
     constructor(adapterDir, testDir) {
         this.adapterDir = adapterDir;
         this.testDir = testDir;
@@ -61,6 +63,11 @@ class AdapterSetup {
         debug(`  appName:           ${this.appName}`);
         debug(`  adapterName:       ${this.adapterName}`);
     }
+    testAdapterDir;
+    adapterName;
+    adapterFullName;
+    appName;
+    testControllerDir;
     /**
      * Tests if the adapter is already installed in the test directory
      */

package/build/tests/integration/lib/controllerSetup.js

@@ -47,6 +47,8 @@ const executeCommand_1 = require("../../../lib/executeCommand");
 const tools_1 = require("./tools");
 const debug = (0, debug_1.default)('testing:integration:ControllerSetup');
 class ControllerSetup {
+    adapterDir;
+    testDir;
     constructor(adapterDir, testDir) {
         this.adapterDir = adapterDir;
         this.testDir = testDir;
@@ -63,7 +65,19 @@ class ControllerSetup {
         debug(`  appName:      ${this.appName}`);
         debug(`  adapterName:  ${this.adapterName}`);
     }
-    async prepareTestDir(controllerVersion = 'dev') {
+    appName;
+    adapterName;
+    testAdapterDir;
+    testControllerDir;
+    testDataDir;
+    async prepareTestDir(controllerVersion) {
+        const nodeMajorVersion = parseInt(process.versions.node.split('.')[0], 10);
+        // js-controller 7.2.3 dropped support for Node.js 18 and 20. If no specific
+        // version was requested, and we are running on such a Node.js version, pin
+        // js-controller to the last version that still supports it.
+        if (!controllerVersion) {
+            controllerVersion = nodeMajorVersion <= 20 ? '7.2.2' : 'dev';
+        }
         debug(`Preparing the test directory. JS-Controller version: "${controllerVersion}"...`);
         // Make sure the test dir exists
         await (0, fs_extra_1.ensureDir)(this.testDir);
@@ -94,7 +108,6 @@ class ControllerSetup {
             await (0, fs_extra_1.unlink)(pckLockPath);
         }
         // Set the engineStrict flag on new Node.js versions to be in line with newer ioBroker installations
-        const nodeMajorVersion = parseInt(process.versions.node.split('.')[0], 10);
         if (nodeMajorVersion >= 10) {
             await (0, fs_extra_1.writeFile)(path.join(this.testDir, '.npmrc'), 'engine-strict=true', 'utf8');
         }

package/build/tests/integration/lib/dbConnection.js

@@ -45,6 +45,9 @@ const tools_1 = require("./tools");
 const debug = (0, debug_1.default)('testing:integration:DBConnection');
 /** The DB connection capsules access to the states and objects DB */
 class DBConnection extends node_events_1.default {
+    appName;
+    testDir;
+    logger;
     /**
      * @param appName The branded name of "iobroker"
      * @param testDir The directory the integration tests are executed in
@@ -55,63 +58,20 @@ class DBConnection extends node_events_1.default {
         this.appName = appName;
         this.testDir = testDir;
         this.logger = logger;
-        this._isRunning = false;
-        this.getObject = id => {
-            if (!this._objectsClient) {
-                throw new Error('Objects DB is not running');
-            }
-            return this._objectsClient.getObjectAsync(id);
-        };
-        this.setObject = (...args) => {
-            if (!this._objectsClient) {
-                throw new Error('Objects DB is not running');
-            }
-            return this._objectsClient.setObjectAsync(...args);
-        };
-        this.delObject = (...args) => {
-            if (!this._objectsClient) {
-                throw new Error('Objects DB is not running');
-            }
-            return this._objectsClient.delObjectAsync(...args);
-        };
-        this.getState = (id) => {
-            if (!this._statesClient) {
-                throw new Error('States DB is not running');
-            }
-            return this._statesClient.getStateAsync(id);
-        };
-        this.setState = ((...args) => {
-            if (!this._statesClient) {
-                throw new Error('States DB is not running');
-            }
-            return this._statesClient.setStateAsync(...args);
-        });
-        this.delState = async (...args) => {
-            if (!this._statesClient) {
-                throw new Error('States DB is not running');
-            }
-            await new Promise((resolve, reject) => this._statesClient.delState(args[0], (err) => {
-                if (err) {
-                    reject(err);
-                }
-                else {
-                    resolve();
-                }
-            }));
-        };
-        this.getObjectViewAsync = (...args) => {
-            if (!this._objectsClient) {
-                throw new Error('Objects DB is not running');
-            }
-            return this._objectsClient.getObjectViewAsync(...args);
-        };
         this.testControllerDir = (0, tools_1.getTestControllerDir)(this.appName, testDir);
         this.testDataDir = (0, tools_1.getTestDataDir)(appName, testDir);
     }
+    testDataDir;
+    testControllerDir;
+    // TODO: These could use some better type definitions
+    _objectsServer;
+    _statesServer;
+    _objectsClient;
     /** The underlying objects client instance that can be used to access the objects DB */
     get objectsClient() {
         return this._objectsClient;
     }
+    _statesClient;
     /** The underlying states client instance that can be used to access the states DB */
     get statesClient() {
         return this._statesClient;
@@ -157,6 +117,7 @@ class DBConnection extends node_events_1.default {
         const systemFilename = path.join(this.testDataDir, `${this.appName}.json`);
         (0, fs_extra_1.writeJSONSync)(systemFilename, systemConfig, { spaces: 2 });
     }
+    _isRunning = false;
     get isRunning() {
         return this._isRunning;
     }
@@ -277,6 +238,49 @@ class DBConnection extends node_events_1.default {
         });
         debug('  => done!');
     }
+    getObject = id => {
+        if (!this._objectsClient) {
+            throw new Error('Objects DB is not running');
+        }
+        return this._objectsClient.getObjectAsync(id);
+    };
+    setObject = (...args) => {
+        if (!this._objectsClient) {
+            throw new Error('Objects DB is not running');
+        }
+        return this._objectsClient.setObjectAsync(...args);
+    };
+    delObject = (...args) => {
+        if (!this._objectsClient) {
+            throw new Error('Objects DB is not running');
+        }
+        return this._objectsClient.delObjectAsync(...args);
+    };
+    getState = (id) => {
+        if (!this._statesClient) {
+            throw new Error('States DB is not running');
+        }
+        return this._statesClient.getStateAsync(id);
+    };
+    setState = ((...args) => {
+        if (!this._statesClient) {
+            throw new Error('States DB is not running');
+        }
+        return this._statesClient.setStateAsync(...args);
+    });
+    delState = async (...args) => {
+        if (!this._statesClient) {
+            throw new Error('States DB is not running');
+        }
+        await new Promise((resolve, reject) => this._statesClient.delState(args[0], (err) => {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve();
+            }
+        }));
+    };
     subscribeMessage(id) {
         if (!this._statesClient) {
             throw new Error('States DB is not running');
@@ -289,6 +293,12 @@ class DBConnection extends node_events_1.default {
         }
         this._statesClient.pushMessage(instanceId, msg, callback);
     }
+    getObjectViewAsync = (...args) => {
+        if (!this._objectsClient) {
+            throw new Error('Objects DB is not running');
+        }
+        return this._objectsClient.getObjectViewAsync(...args);
+    };
     getStateIDs(pattern = '*') {
         if (!this._statesClient) {
             throw new Error('States DB is not running');

package/build/tests/integration/lib/harness.js

@@ -53,6 +53,9 @@ const fromAdapterID = 'system.adapter.test.0';
  * Use it in every test to start a fresh adapter instance
  */
 class TestHarness extends node_events_1.EventEmitter {
+    adapterDir;
+    testDir;
+    dbConnection;
     /**
      * @param adapterDir The root directory of the adapter
      * @param testDir The directory the integration tests are executed in
@@ -62,7 +65,6 @@ class TestHarness extends node_events_1.EventEmitter {
         this.adapterDir = adapterDir;
         this.testDir = testDir;
         this.dbConnection = dbConnection;
-        this.sendToID = 1;
         debug('Creating instance');
         this.adapterName = (0, adapterTools_1.getAdapterName)(this.adapterDir);
         this.appName = (0, adapterTools_1.getAppName)(adapterDir);
@@ -80,6 +82,10 @@ class TestHarness extends node_events_1.EventEmitter {
             this.emit('stateChange', id, state);
         });
     }
+    adapterName;
+    appName;
+    testControllerDir;
+    testAdapterDir;
     /** Gives direct access to the Objects DB */
     get objects() {
         if (!this.dbConnection.objectsClient) {
@@ -94,10 +100,12 @@ class TestHarness extends node_events_1.EventEmitter {
         }
         return this.dbConnection.statesClient;
     }
+    _adapterProcess;
     /** The process the adapter is running in */
     get adapterProcess() {
         return this._adapterProcess;
     }
+    _adapterExit;
     /** Contains the adapter exit code or signal if it was terminated unexpectedly */
     get adapterExit() {
         return this._adapterExit;
@@ -266,6 +274,7 @@ class TestHarness extends node_events_1.EventEmitter {
         });
         this.dbConnection.subscribeMessage(fromAdapterID);
     }
+    sendToID = 1;
     /** Sends a message to an adapter instance */
     sendTo(target, command, message, callback) {
         const stateChangedHandler = (id, state) => {

package/build/tests/packageFiles/index.js

@@ -291,12 +291,26 @@ function validatePackageFiles(adapterDir) {
             });
         });
         describe(`Validate JSON files`, () => {
+            // Validate base directory JSON files
+            describe(`Base directory JSON files`, () => {
+                for (const filename of ['package.json', 'io-package.json']) {
+                    const filePath = path.join(adapterDir, filename);
+                    if (fs.existsSync(filePath)) {
+                        it(`${filename} contains valid JSON`, () => {
+                            (0, chai_1.expect)(() => {
+                                JSON.parse(fs.readFileSync(filePath, 'utf8'));
+                            }, `${filename} contains invalid JSON!`).not.to.throw();
+                        });
+                    }
+                }
+            });
             // Find all JSON and JSON5 files in admin/ directory (recursively)
             const adminDir = path.join(adapterDir, 'admin');
             const allAdminJsonFiles = findFiles(adminDir, /\.json$/);
             const allAdminJson5Files = findFiles(adminDir, /\.json5$/);
             // Split JSON files into admin/*.json and admin/i18n/**/*.json
-            const adminDirectJsonFiles = allAdminJsonFiles.filter(file => !file.includes(`${path.sep}i18n${path.sep}`));
+            // Exclude tsconfig.json as it may contain JSON5 syntax (comments, trailing commas)
+            const adminDirectJsonFiles = allAdminJsonFiles.filter(file => !file.includes(`${path.sep}i18n${path.sep}`) && !file.endsWith(`${path.sep}tsconfig.json`));
             const i18nJsonFiles = allAdminJsonFiles.filter(file => file.includes(`${path.sep}i18n${path.sep}`));
             if (adminDirectJsonFiles.length > 0) {
                 describe(`admin/*.json files`, () => {

package/build/tests/unit/mocks/mockDatabase.js

@@ -17,10 +17,8 @@ const stateTemplate = Object.freeze({
  * A minimalistic version of ioBroker's Objects and States DB that just operates on a Map
  */
 class MockDatabase {
-    constructor() {
-        this.objects = new Map();
-        this.states = new Map();
-    }
+    objects = new Map();
+    states = new Map();
     clearObjects() {
         this.objects.clear();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iobroker/testing",
-  "version": "5.2.1",
+  "version": "5.3.0",
   "description": "Shared utilities for adapter and module testing in ioBroker",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -39,35 +39,35 @@
   },
   "homepage": "https://github.com/AlCalzone/testing#readme",
   "devDependencies": {
-    "@alcalzone/release-script": "^5.0.0",
-    "@alcalzone/release-script-plugin-license": "^4.0.0",
-    "@iobroker/adapter-core": "^3.3.2",
-    "@iobroker/eslint-config": "^2.2.0",
-    "@iobroker/types": "^7.0.7",
-    "@tsconfig/node16": "^16.1.6",
-    "@types/debug": "^4.1.12",
+    "@alcalzone/release-script": "^5.2.1",
+    "@alcalzone/release-script-plugin-license": "^5.2.0",
+    "@iobroker/adapter-core": "^3.4.1",
+    "@iobroker/eslint-config": "^2.3.4",
+    "@iobroker/types": "^7.2.2",
+    "@tsconfig/node18": "^18.2.6",
+    "@types/debug": "^4.1.13",
     "@types/fs-extra": "^11.0.4",
-    "@types/node": "^24.6.1",
-    "rimraf": "^6.1.0",
+    "@types/node": "^26.1.1",
+    "rimraf": "^6.1.3",
     "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
-    "typescript": "~5.9.3"
+    "typescript": "~6.0.3"
   },
   "dependencies": {
     "@alcalzone/esbuild-register": "^2.5.1-1",
     "@types/chai": "^4.3.20",
     "@types/chai-as-promised": "^7.1.8",
     "@types/mocha": "^10.0.10",
-    "@types/sinon": "^17.0.4",
+    "@types/sinon": "^22.0.0",
     "@types/sinon-chai": "^3.2.12",
     "alcalzone-shared": "~5.0.0",
     "chai": "^4.5.0",
     "chai-as-promised": "^7.1.2",
     "debug": "^4.4.3",
-    "fs-extra": "^11.3.2",
+    "fs-extra": "^11.3.6",
     "json5": "^2.2.3",
-    "mocha": "^11.7.3",
-    "sinon": "^21.0.0",
+    "mocha": "^11.7.6",
+    "sinon": "^22.0.0",
     "sinon-chai": "^3.7.0"
   }
 }