@iobroker/testing 3.0.1 → 4.1.0

package/README.md

@@ -43,6 +43,10 @@ tests.integration(path.join(__dirname, ".."), {
 	// By default, termination during startup is not allowed.
 	allowedExitCodes: [11],
 
+	// To test against a different version of JS-Controller, you can change the version or dist-tag here.
+	// Make sure to remove this setting when you're done testing.
+	controllerVersion: "latest", // or a specific version like "4.0.1"
+
 	// Define your own tests inside defineAdditionalTests
 	defineAdditionalTests({ suite }) {
 		// All tests (it, describe) must be grouped in one or more suites. Each suite sets up a fresh environment for the adapter tests.
@@ -50,7 +54,13 @@ tests.integration(path.join(__dirname, ".."), {
 		// The adapter will run until the end of each suite.
 
 		// Since the tests are heavily instrumented, each suite gives access to a so called "harness" to control the tests.
-		suite("Test sendTo()", (harness) => {
+		suite("Test sendTo()", (getHarness) => {
+			// For convenience, get the current suite's harness before all tests
+			let harness;
+			before(() => {
+				harness = getHarness();
+			});
+
 			it("Should work", () => {
 				return new Promise(async (resolve) => {
 					// Start the adapter and wait until it has started
@@ -64,6 +74,15 @@ tests.integration(path.join(__dirname, ".."), {
 				});
 			});
 		});
+
+		// While developing the tests, you can run only a single suite using `suite.only`...
+		suite.only("Only this will run", (getHarness) => {
+			// ...
+		});
+		// ...or prevent a suite from running using `suite.skip`:
+		suite.skip("This will never run", (getHarness) => {
+			// ...
+		});
 	},
 });
 ```

package/build/lib/executeCommand.js

@@ -46,8 +46,8 @@ function executeCommand(command, argsOrOptions, options) {
             let bufferedStderr;
             const cmd = (0, child_process_1.spawn)(command, args, spawnOptions).on("close", (code, signal) => {
                 resolve({
-                    exitCode: code !== null && code !== void 0 ? code : undefined,
-                    signal: signal !== null && signal !== void 0 ? signal : undefined,
+                    exitCode: code ?? undefined,
+                    signal: signal ?? undefined,
                     stdout: bufferedStdout,
                     stderr: bufferedStderr,
                 });

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

@@ -7,17 +7,31 @@ export interface TestAdapterOptions {
     loglevel?: ioBroker.LogLevel;
     /** 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
+     * This should only be changed during active development.
+     */
+    controllerVersion?: string;
     /** Allows you to define additional tests */
     defineAdditionalTests?: (args: TestContext) => void;
 }
+export interface TestSuiteFn {
+    (name: string, fn: (getHarness: () => TestHarness) => void): void;
+}
+export interface TestSuite extends TestSuiteFn {
+    /** Only runs the tests inside this `suite` for the current file */
+    only: TestSuiteFn;
+    /** Skips running the tests inside this `suite` for the current file */
+    skip: TestSuiteFn;
+}
 export interface TestContext {
     /**
      * Defines a test suite. At the start of each suite, the adapter will be started with a fresh environment.
      * To define tests in each suite, use describe and it as usual.
      *
-     * Each suite has its own test harness, which gets passed as an argument.
+     * Each suite has its own test harness, which can be retrieved using the function that is passed to the suite callback.
      */
-    suite: (name: string, fn: (harness: TestHarness) => void) => void;
+    suite: TestSuite;
     describe: Mocha.SuiteFunction;
     it: Mocha.TestFunction;
 }

package/build/tests/integration/index.js

@@ -48,7 +48,6 @@ function testAdapter(adapterDir, options = {}) {
     console.log(`Running tests in ${testDir}`);
     console.log();
     async function prepareTests() {
-        var _a;
         // Installation may take a while - especially if rsa-compat needs to be installed
         const oneMinute = 60000;
         this.timeout(30 * oneMinute);
@@ -59,11 +58,11 @@ function testAdapter(adapterDir, options = {}) {
         // Installation happens in two steps:
         // First we need to set up JS Controller, so the databases etc. can be created
         // First we need to copy all files and execute an npm install
-        await controllerSetup.prepareTestDir();
+        await controllerSetup.prepareTestDir(options.controllerVersion);
         // Only then we can install the adapter, because some (including VIS) try to access
         // the databases if JS Controller is installed
         await adapterSetup.installAdapterInTestDir();
-        const dbConnection = new dbConnection_1.DBConnection(appName, testDir, (0, logger_1.createLogger)((_a = options.loglevel) !== null && _a !== void 0 ? _a : "debug"));
+        const dbConnection = new dbConnection_1.DBConnection(appName, testDir, (0, logger_1.createLogger)(options.loglevel ?? "debug"));
         await dbConnection.start();
         controllerSetup.setupSystemConfig(dbConnection);
         await controllerSetup.disableAdminInstances(dbConnection);
@@ -82,9 +81,8 @@ function testAdapter(adapterDir, options = {}) {
         harness.removeAllListeners();
     }
     async function resetDbAndStartHarness() {
-        var _a, _b;
         this.timeout(30000);
-        dbConnection = new dbConnection_1.DBConnection(appName, testDir, (0, logger_1.createLogger)((_a = options.loglevel) !== null && _a !== void 0 ? _a : "debug"));
+        dbConnection = new dbConnection_1.DBConnection(appName, testDir, (0, logger_1.createLogger)(options.loglevel ?? "debug"));
         // Clean up before every single test
         await Promise.all([
             controllerSetup.clearDBDir(),
@@ -98,7 +96,7 @@ function testAdapter(adapterDir, options = {}) {
         await harness.changeAdapterConfig(adapterName, {
             common: {
                 enabled: true,
-                loglevel: (_b = options.loglevel) !== null && _b !== void 0 ? _b : "debug",
+                loglevel: options.loglevel ?? "debug",
             },
         });
         // And enable the sendTo emulation
@@ -110,9 +108,8 @@ function testAdapter(adapterDir, options = {}) {
             beforeEach(resetDbAndStartHarness);
             afterEach(shutdownTests);
             it("The adapter starts", function () {
-                var _a;
                 this.timeout(60000);
-                const allowedExitCodes = new Set((_a = options.allowedExitCodes) !== null && _a !== void 0 ? _a : []);
+                const allowedExitCodes = new Set(options.allowedExitCodes ?? []);
                 // Adapters with these modes are allowed to "immediately" exit with code 0
                 switch (harness.getAdapterExecutionMode()) {
                     case "schedule":
@@ -175,22 +172,26 @@ function testAdapter(adapterDir, options = {}) {
             describe("User-defined tests", () => {
                 // patch the global it() function so nobody can bypass the checks
                 global.it = patchedIt;
-                const lazyHarness = new Proxy({}, {
-                    get(target, propKey) {
-                        return harness[propKey];
-                    },
+                // a test suite is a special describe which sets up and tears down the test environment before and after ALL tests
+                const suiteBody = (fn) => {
+                    isInSuite = true;
+                    before(resetDbAndStartHarness);
+                    fn(() => harness);
+                    after(shutdownTests);
+                    isInSuite = false;
+                };
+                const suite = ((name, fn) => {
+                    describe(name, () => suiteBody(fn));
                 });
+                // Support .skip and .only
+                suite.skip = (name, fn) => {
+                    describe.skip(name, () => suiteBody(fn));
+                };
+                suite.only = (name, fn) => {
+                    describe.only(name, () => suiteBody(fn));
+                };
                 const args = {
-                    // a test suite is a special describe which sets up and tears down the test environment before and after ALL tests
-                    suite: (name, fn) => {
-                        describe(name, () => {
-                            isInSuite = true;
-                            before(resetDbAndStartHarness);
-                            fn(lazyHarness);
-                            after(shutdownTests);
-                            isInSuite = false;
-                        });
-                    },
+                    suite,
                     describe,
                     it: patchedIt,
                 };

package/build/tests/integration/lib/controllerSetup.d.ts

@@ -8,7 +8,7 @@ export declare class ControllerSetup {
     private testAdapterDir;
     private testControllerDir;
     private testDataDir;
-    prepareTestDir(): Promise<void>;
+    prepareTestDir(controllerVersion?: string): Promise<void>;
     /**
      * Tests if JS-Controller is already installed
      * @param appName The branded name of "iobroker"

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

@@ -53,8 +53,8 @@ class ControllerSetup {
         debug(`  appName:      ${this.appName}`);
         debug(`  adapterName:  ${this.adapterName}`);
     }
-    async prepareTestDir() {
-        debug("Preparing the test directory...");
+    async prepareTestDir(controllerVersion = "dev") {
+        debug(`Preparing the test directory. JS-Controller version: "${controllerVersion}"...`);
         // Make sure the test dir exists
         await (0, fs_extra_1.ensureDir)(this.testDir);
         // Write the package.json
@@ -69,7 +69,7 @@ class ControllerSetup {
             author: "",
             license: "ISC",
             dependencies: {
-                [`${this.appName}.js-controller`]: "dev",
+                [`${this.appName}.js-controller`]: controllerVersion,
             },
             description: "",
         };

package/build/tests/integration/lib/dbConnection.d.ts

@@ -1,4 +1,6 @@
 /// <reference types="iobroker" />
+/// <reference types="iobroker" />
+/// <reference types="node" />
 /// <reference types="node" />
 import EventEmitter from "events";
 export declare type ObjectsDB = Record<string, ioBroker.Object>;

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

@@ -152,17 +152,16 @@ class DBConnection extends events_1.default {
         debug("DB instances started");
     }
     async stop() {
-        var _a, _b, _c, _d;
         if (!this._isRunning) {
             debug("No DB instance is running, nothing to stop...");
             return;
         }
         debug("Stopping DB instances...");
         // Stop clients before servers
-        await ((_a = this._objectsClient) === null || _a === void 0 ? void 0 : _a.destroy());
-        await ((_b = this._objectsServer) === null || _b === void 0 ? void 0 : _b.destroy());
-        await ((_c = this._statesClient) === null || _c === void 0 ? void 0 : _c.destroy());
-        await ((_d = this._statesServer) === null || _d === void 0 ? void 0 : _d.destroy());
+        await this._objectsClient?.destroy();
+        await this._objectsServer?.destroy();
+        await this._statesClient?.destroy();
+        await this._statesServer?.destroy();
         this._objectsClient = null;
         this._objectsServer = null;
         this._statesClient = null;
@@ -279,20 +278,18 @@ class DBConnection extends events_1.default {
         this._statesClient.pushMessage(instanceId, msg, callback);
     }
     async getStateIDs(pattern = "*") {
-        var _a, _b, _c, _d;
         if (!this._statesClient) {
             throw new Error("States DB is not running");
         }
-        return (((_b = (_a = this._statesClient).getKeysAsync) === null || _b === void 0 ? void 0 : _b.call(_a, pattern)) ||
-            ((_d = (_c = this._statesClient).getKeys) === null || _d === void 0 ? void 0 : _d.call(_c, pattern)));
+        return (this._statesClient.getKeysAsync?.(pattern) ||
+            this._statesClient.getKeys?.(pattern));
     }
     async getObjectIDs(pattern = "*") {
-        var _a, _b, _c, _d;
         if (!this._objectsClient) {
             throw new Error("Objects DB is not running");
         }
-        return (((_b = (_a = this._objectsClient).getKeysAsync) === null || _b === void 0 ? void 0 : _b.call(_a, pattern)) ||
-            ((_d = (_c = this._objectsClient).getKeys) === null || _d === void 0 ? void 0 : _d.call(_c, pattern)));
+        return (this._objectsClient.getKeysAsync?.(pattern) ||
+            this._objectsClient.getKeys?.(pattern));
     }
 }
 exports.DBConnection = DBConnection;

package/build/tests/integration/lib/harness.d.ts

@@ -1,5 +1,8 @@
 /// <reference types="iobroker" />
 /// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="iobroker" />
+/// <reference types="node" />
 import { ChildProcess } from "child_process";
 import { EventEmitter } from "events";
 import type { DBConnection } from "./dbConnection";

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

@@ -190,7 +190,6 @@ class TestHarness extends events_1.EventEmitter {
         if (!this.isAdapterRunning())
             return;
         return new Promise(async (resolve) => {
-            var _a;
             const onClose = (code, signal) => {
                 if (!this._adapterProcess)
                     return;
@@ -214,7 +213,7 @@ class TestHarness extends events_1.EventEmitter {
             }
             catch {
                 // DB connection may be closed already, kill the process
-                (_a = this._adapterProcess) === null || _a === void 0 ? void 0 : _a.kill("SIGTERM");
+                this._adapterProcess?.kill("SIGTERM");
             }
         });
     }

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

@@ -10,8 +10,7 @@ var LoglevelOrder;
     LoglevelOrder[LoglevelOrder["silly"] = 4] = "silly";
 })(LoglevelOrder || (LoglevelOrder = {}));
 function createLogger(loglevel) {
-    var _a;
-    const loglevelNumeric = (_a = LoglevelOrder[loglevel !== null && loglevel !== void 0 ? loglevel : "debug"]) !== null && _a !== void 0 ? _a : LoglevelOrder.debug;
+    const loglevelNumeric = LoglevelOrder[loglevel ?? "debug"] ?? LoglevelOrder.debug;
     // eslint-disable-next-line @typescript-eslint/no-empty-function
     const ignore = () => { };
     return {

package/build/tests/packageFiles/index.js

@@ -130,7 +130,6 @@ function validatePackageFiles(adapterDir) {
             });
         });
         describe(`Check contents of io-package.json`, () => {
-            var _a;
             beforeEach(function () {
                 skipIfInvalid.call(this, "io-package.json");
             });
@@ -178,13 +177,12 @@ function validatePackageFiles(adapterDir) {
             // If the adapter has a configuration page, check that a supported admin UI is used
             const hasNoConfigPage = iopackContent.common.noConfig === true ||
                 iopackContent.common.noConfig === "true" ||
-                ((_a = iopackContent.common.adminUI) === null || _a === void 0 ? void 0 : _a.config) === "none";
+                iopackContent.common.adminUI?.config === "none";
             if (!hasNoConfigPage) {
                 it("The adapter uses Material UI or JSON Config for the admin UI", () => {
-                    var _a, _b;
                     const hasSupportedUI = !!iopackContent.common.materialize ||
-                        ((_a = iopackContent.common.adminUI) === null || _a === void 0 ? void 0 : _a.config) === "json" ||
-                        ((_b = iopackContent.common.adminUI) === null || _b === void 0 ? void 0 : _b.config) === "materialize";
+                        iopackContent.common.adminUI?.config === "json" ||
+                        iopackContent.common.adminUI?.config === "materialize";
                     (0, chai_1.expect)(hasSupportedUI, "Unsupported Admin UI, must be materialize or json config!").to.be.true;
                 });
             }

package/build/tests/unit/mocks/mockDatabase.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="iobroker" />
+/// <reference types="iobroker" />
 import type { MockAdapter } from "./mockAdapter";
 /**
  * A minimalistic version of ioBroker's Objects and States DB that just operates on a Map

package/build/tests/unit/mocks/tools.d.ts

@@ -4,7 +4,7 @@ export declare type IsAny<T> = Equals<T extends never ? false : true, boolean>;
 export declare type MockableMethods<T, All = Required<T>, NoAny = {
     [K in keyof All]: IsAny<All[K]> extends true ? never : All[K] extends (...args: any[]) => void ? K : never;
 }> = NoAny[keyof NoAny];
-export declare type Mock<T> = Overwrite<T, {
+export declare type Mock<T extends {}> = Overwrite<T, {
     [K in MockableMethods<T>]: sinon.SinonStub;
 }>;
 export declare function doResetHistory(parent: Record<string, any>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iobroker/testing",
-  "version": "3.0.1",
+  "version": "4.1.0",
   "description": "Shared utilities for adapter and module testing in ioBroker",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -41,35 +41,35 @@
     "@alcalzone/release-script": "^3.5.9",
     "@alcalzone/release-script-plugin-license": "^3.5.9",
     "@iobroker/adapter-core": "^2.6.0",
-    "@tsconfig/node12": "^1.0.9",
-    "@types/chai": "^4.3.1",
+    "@tsconfig/node14": "^1.0.3",
+    "@types/chai": "^4.3.3",
     "@types/chai-as-promised": "^7.1.5",
     "@types/debug": "4.1.7",
     "@types/fs-extra": "^9.0.13",
-    "@types/iobroker": "^4.0.2",
+    "@types/iobroker": "^4.0.4",
     "@types/mocha": "^9.1.1",
-    "@types/node": "^12.20.50",
-    "@types/sinon": "^10.0.11",
+    "@types/node": "^14.18.26",
+    "@types/sinon": "^10.0.13",
     "@types/sinon-chai": "^3.2.8",
-    "@typescript-eslint/eslint-plugin": "^5.22.0",
-    "@typescript-eslint/parser": "^5.22.0",
-    "eslint": "^8.15.0",
+    "@typescript-eslint/eslint-plugin": "^5.35.1",
+    "@typescript-eslint/parser": "^5.35.1",
+    "eslint": "^8.23.0",
     "eslint-config-prettier": "^8.5.0",
-    "eslint-plugin-prettier": "^4.0.0",
-    "prettier": "^2.6.2",
+    "eslint-plugin-prettier": "^4.2.1",
+    "prettier": "^2.7.1",
     "rimraf": "^3.0.2",
     "source-map-support": "^0.5.21",
-    "ts-node": "^10.7.0",
-    "typescript": "~4.6.4"
+    "ts-node": "^10.9.1",
+    "typescript": "~4.8.2"
   },
   "dependencies": {
-    "alcalzone-shared": "~4.0.1",
+    "alcalzone-shared": "~4.0.3",
     "chai": "^4.3.6",
     "chai-as-promised": "^7.1.1",
     "debug": "^4.3.4",
     "fs-extra": "^10.1.0",
-    "mocha": "^9.2.2",
-    "sinon": "^13.0.1",
+    "mocha": "^10.0.0",
+    "sinon": "^14.0.0",
     "sinon-chai": "^3.7.0"
   }
 }

package/CHANGELOG.md

@@ -1,66 +0,0 @@
-## Changelog
-
-<!--
-	PLACEHOLDER for next version:
-	## __WORK IN PROGRESS__
--->
-## 3.0.1 (2022-05-09)
-* BREAKING: The function signature of `defineAdditionalTests` in integration tests has changed. All user-defined integration tests must now be grouped in one or more `suite` blocks. The adapter will now only be started at the beginning of each suite. See the documentation for details.
-* BREAKING: The function signature of `harness.startAdapterAndWait` has changed. It now accepts a boolean as the first parameter which controls whether to wait for the `alive` state (`false`) or the `info.connection` state (`true`).
-
-## 2.6.0 (2022-04-18)
-* The loglevel for the adapter and DB instances is now configurable and defaults to `"debug"` in both cases
-
-## 2.5.6 (2022-03-05)
-* Allow immediate exit with code `0` for `once` and `subscribe` adapters too
-
-## 2.5.5 (2022-03-04)
-* Allow immediate exit with code `0` for `schedule` adapters
-* Check that `npm` is not listed as a local dependency in `package.json`
-* Updated dependencies
-
-## 2.5.4 (2022-02-02)
-* Modifying ioBroker databases now uses the same methods that JS-Controller uses internally. This ensures that the testing is compatible with the `jsonl` database format.
-* Testing adapters with adapter dependencies that try to access the databases during installation now works.
-
-## 2.5.2 (2021-09-18)
-* Fix: `adminUI.config` is now respected for the config UI check and JSON config is allowed too
-* Updated dependencies
-* Modernized build process
-
-## 2.5.1 (2021-09-05)
-* We now use the nightly js-controller dev builds instead of GitHub installation
-
-## 2.4.4 (2021-03-14)
-* Fix error: `iopackContent.common.titleLang` is not iterable
-
-## 2.4.3 (2021-03-12)
-* Fix: The adapter main file now correctly gets located when it is only defined in `package.json`, not `io-package.json`
-
-## 2.4.2 (2021-01-06)
-* Fixed compatibility with the reworked database classes
-* Improved shutdown behavior of the adapter
-
-## 2.4.1 (2021-01-01)
-* Fixed a bug where the wrong `js-controller` dependency would be installed
-
-## 2.4.0 (2020-12-07)
-* Unit tests for adapter startup were removed and only log a warning that you can remove them
-* Upgrade many packages
-
-## 2.3.0 (2020-08-20)
-* Added missing async functions to adapter mock
-* Fixed: `TypeError "Cannot redefine property readyHandler"` when using `createMocks` more than once
-* Upgrade to `@types/iobroker` v3.0.12
-
-## 2.2.0 (2020-04-15)
-* Upgrade to `@types/iobroker` v3.0.2
-* Added mocks for `supportsFeature`, `getPluginInstance`, `getPluginConfig`
-
-## 2.1.0 (2020-03-01)
-* **Integration tests:** For Node.js >= 10, the `engine-strict` flag is now set to `true` to be in line with newer ioBroker installations
-
-## v2.0.2
-* **Unit tests:** added mocks for `getAbsoluteDefaultDataDir` and `getAbsoluteInstanceDataDir`
-
-Sorry, there isn't more yet.