@iobroker/testing 6.0.0 → 6.1.0

package/README.md

@@ -75,6 +75,20 @@ tests.integration(path.join(__dirname, ".."), {
 			});
 		});
 
+		// Checking the adapter log
+		suite("Check the log", (getHarness) => {
+			let harness;
+			before(() => {
+				harness = getHarness();
+			});
+
+			it("Should not log the follow-up error", async () => {
+				await harness.startAdapterAndWait();
+
+				expect(harness.hasLog(/follow-up-bug detected/, "error")).to.be.false;
+			});
+		});
+
 		// While developing the tests, you can run only a single suite using `suite.only`...
 		suite.only("Only this will run", (getHarness) => {
 			// ...
@@ -87,6 +101,43 @@ tests.integration(path.join(__dirname, ".."), {
 });
 ```
 
+### Checking the adapter log (Integration test)
+
+The test harness captures everything the adapter under test prints while it is running, so tests can check
+that a specific message was (or was not) logged:
+
+-   `getLogs(level?)` returns the captured log messages, optionally filtered by log level. Each entry looks like this:
+
+```ts
+interface AdapterLog {
+	/** The log level the message was logged with */
+	level: "silly" | "debug" | "info" | "warn" | "error";
+	/** The time the message was logged at */
+	timestamp: Date;
+	/** The source of the message, e.g. `my-adapter.0`. Undefined if it could not be determined */
+	from: string | undefined;
+	/** The logged message without timestamp, level and source */
+	message: string;
+	/** The unparsed log line as it was printed by the adapter */
+	raw: string;
+}
+```
+
+-   `hasLog(pattern, level?)` returns whether a message matching `pattern` was logged. `pattern` is either a `RegExp`
+    or a string that must be contained in the message. If `level` is given, only messages with that log level are checked.
+-   `clearLogs()` forgets all messages that were captured so far, e.g. to check only the messages of the next step.
+
+```ts
+await harness.startAdapterAndWait();
+
+expect(harness.hasLog(/connection failed/, "error")).to.be.false;
+expect(harness.getLogs("error")).to.be.empty;
+
+harness.clearLogs();
+```
+
+Lines that are not in the ioBroker log format - e.g. output of a plain `console.log()` - are captured as `info` messages.
+
 ### Adapter startup (Unit test)
 
 **Unit tests for adapter startup were removed and are essentially a no-op now.**  

package/build/tests/index.d.ts

@@ -3,7 +3,7 @@ import { validatePackageFiles } from './packageFiles';
 import { testAdapterWithMocks } from './unit';
 import { createMocks } from './unit/harness/createMocks';
 import { createAsserts } from './unit/mocks/mockDatabase';
-export { TestHarness as IntegrationTestHarness } from './integration/lib/harness';
+export { TestHarness as IntegrationTestHarness, type AdapterLog } from './integration/lib/harness';
 export type { MockAdapter } from './unit/mocks/mockAdapter';
 export { MockDatabase } from './unit/mocks/mockDatabase';
 /** Predefined test sets */

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

@@ -8,6 +8,24 @@ export declare class ControllerSetup {
     private testAdapterDir;
     private testControllerDir;
     private testDataDir;
+    /**
+     * Returns the path of the file that stores which JS-Controller version is installed in the test directory
+     */
+    private getControllerVersionFilePath;
+    /**
+     * Reads which JS-Controller version was installed in the test directory during the previous run.
+     * Returns `null` if this is unknown.
+     */
+    private getInstalledControllerVersion;
+    /**
+     * Remembers which JS-Controller version is installed in the test directory
+     */
+    private saveInstalledControllerVersion;
+    /**
+     * Removes the installed dependencies and the data directory from the test directory.
+     * This is necessary when switching JS-Controller versions, so no stale files and states are left behind.
+     */
+    private clearTestDir;
     prepareTestDir(controllerVersion?: string): Promise<void>;
     /**
      * Tests if JS-Controller is already installed

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

@@ -70,6 +70,52 @@ class ControllerSetup {
     testAdapterDir;
     testControllerDir;
     testDataDir;
+    /**
+     * Returns the path of the file that stores which JS-Controller version is installed in the test directory
+     */
+    getControllerVersionFilePath() {
+        return path.join(this.testDir, '.controller-version');
+    }
+    /**
+     * Reads which JS-Controller version was installed in the test directory during the previous run.
+     * Returns `null` if this is unknown.
+     */
+    async getInstalledControllerVersion() {
+        const versionFilePath = this.getControllerVersionFilePath();
+        try {
+            if (!(await (0, fs_extra_1.pathExists)(versionFilePath))) {
+                return null;
+            }
+            const version = await (0, fs_extra_1.readFile)(versionFilePath, 'utf8');
+            return version.trim() || null;
+        }
+        catch (e) {
+            debug(`Could not read the installed JS-Controller version: ${e}`);
+            return null;
+        }
+    }
+    /**
+     * Remembers which JS-Controller version is installed in the test directory
+     */
+    async saveInstalledControllerVersion(controllerVersion) {
+        try {
+            await (0, fs_extra_1.writeFile)(this.getControllerVersionFilePath(), controllerVersion, 'utf8');
+        }
+        catch (e) {
+            debug(`Could not save the installed JS-Controller version: ${e}`);
+        }
+    }
+    /**
+     * Removes the installed dependencies and the data directory from the test directory.
+     * This is necessary when switching JS-Controller versions, so no stale files and states are left behind.
+     */
+    async clearTestDir() {
+        debug('Clearing the test directory...');
+        await (0, fs_extra_1.emptyDir)(path.join(this.testDir, 'node_modules'));
+        await (0, fs_extra_1.emptyDir)(this.testDataDir);
+        await this.clearLogDir();
+        debug('  => done!');
+    }
     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
@@ -81,6 +127,13 @@ class ControllerSetup {
         debug(`Preparing the test directory. JS-Controller version: "${controllerVersion}"...`);
         // Make sure the test dir exists
         await (0, fs_extra_1.ensureDir)(this.testDir);
+        // If the test directory was previously used with a different JS-Controller version,
+        // remove the installed files and the data directory, so no stale state is left behind
+        const installedControllerVersion = await this.getInstalledControllerVersion();
+        if (installedControllerVersion && installedControllerVersion !== controllerVersion) {
+            debug(`JS-Controller version changed from "${installedControllerVersion}" to "${controllerVersion}", cleaning up...`);
+            await this.clearTestDir();
+        }
         // Write the package.json
         const packageJson = {
             name: path.basename(this.testDir),
@@ -123,6 +176,8 @@ class ControllerSetup {
         if (wasJsControllerInstalled) {
             await this.setupJsController();
         }
+        // Remember which version is installed now, so we can detect a version change on the next run
+        await this.saveInstalledControllerVersion(controllerVersion);
         debug('  => done!');
     }
     /**

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

@@ -1,6 +1,27 @@
 import { type ChildProcess } from 'node:child_process';
 import { EventEmitter } from 'node:events';
 import type { DBConnection } from './dbConnection';
+/** A single log message of the adapter under test */
+export interface AdapterLog {
+    /** The log level the message was logged with */
+    level: ioBroker.LogLevel;
+    /** The time the message was logged at */
+    timestamp: Date;
+    /** The source of the message, e.g. `my-adapter.0`. Undefined if it could not be determined */
+    from: string | undefined;
+    /** The logged message without timestamp, level and source */
+    message: string;
+    /** The unparsed log line as it was printed by the adapter */
+    raw: string;
+}
+/**
+ * Parses a line of the adapter output into a structured log message.
+ * Lines that are not in the ioBroker log format (e.g. plain `console.log` output)
+ * are returned as `info` messages.
+ *
+ * @param line A single line of the adapter's stdout/stderr
+ */
+export declare function parseAdapterLogLine(line: string): AdapterLog;
 export interface TestHarness {
     on(event: 'objectChange', handler: ioBroker.ObjectChangeHandler): this;
     on(event: 'stateChange', handler: ioBroker.StateChangeHandler): this;
@@ -59,13 +80,75 @@ export declare class TestHarness extends EventEmitter {
     /** Stops the adapter process */
     stopAdapter(): Promise<void> | undefined;
     /**
-     * Updates the adapter config. The changes can be a subset of the target object
+     * Updates the adapter config. The changes can be a subset of the target object.
+     * The `native` properties that are listed in the instance object's `encryptedNative`
+     * are encrypted automatically, so they can be passed in plain text.
      */
     changeAdapterConfig(adapterName: string, changes: Record<string, any>): Promise<void>;
+    /**
+     * Reads the config of an adapter instance. The `native` properties that are listed in the
+     * instance object's `encryptedNative` are decrypted automatically, so they are returned in plain text.
+     *
+     * @param adapterName The name of the adapter. Defaults to the adapter under test.
+     */
+    getAdapterConfig(adapterName?: string): Promise<ioBroker.InstanceObject | null>;
+    /**
+     * Returns the names of all `native` properties in the given config that must be en-/decrypted
+     */
+    private getEncryptedFields;
+    /**
+     * Encrypts all `native` properties of the given changes that are listed in the instance
+     * object's `encryptedNative`. Returns the changes to apply - the passed object is not modified.
+     */
+    private encryptNativeChanges;
+    private _systemSecret;
+    /**
+     * Reads the secret from the `system.config` object. The secret is cached after the first read.
+     */
+    private getSystemSecret;
+    /**
+     * Encrypts a value the same way the JS-Controller does for `encryptedNative` properties
+     */
+    encryptValue(value: string): Promise<string>;
+    /**
+     * Decrypts a value that was encrypted for an `encryptedNative` property
+     */
+    decryptValue(value: string): Promise<string>;
     getAdapterExecutionMode(): ioBroker.AdapterCommon['mode'];
     /** Enables the sendTo method */
     enableSendTo(): Promise<void>;
     private sendToID;
     /** Sends a message to an adapter instance */
     sendTo(target: string, command: string, message: any, callback: ioBroker.MessageCallback): void;
+    /** The log messages of the adapter under test */
+    private _logs;
+    /** The incomplete last line of each output stream, waiting for the rest to arrive */
+    private _outputBuffer;
+    /**
+     * Handles a chunk of the adapter's output. Because a chunk may end in the middle of a line,
+     * the incomplete rest is buffered until the remainder arrives.
+     *
+     * @param chunk The received chunk
+     * @param stream Which of the adapter's output streams the chunk was received on
+     */
+    private handleAdapterOutput;
+    /** Prints a line of the adapter's output and remembers it as a log message */
+    private handleAdapterOutputLine;
+    /** Handles the incomplete lines that were left over when the adapter exited */
+    private flushAdapterOutput;
+    /**
+     * Returns the log messages the adapter has printed so far
+     *
+     * @param level If given, only the messages with this log level are returned
+     */
+    getLogs(level?: ioBroker.LogLevel): AdapterLog[];
+    /** Forgets all log messages that were captured so far */
+    clearLogs(): void;
+    /**
+     * Tests if the adapter has logged a message matching the given pattern
+     *
+     * @param pattern A RegExp or a string that must be contained in the message
+     * @param level If given, only the messages with this log level are checked
+     */
+    hasLog(pattern: string | RegExp, level?: ioBroker.LogLevel): boolean;
 }

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

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TestHarness = void 0;
+exports.parseAdapterLogLine = parseAdapterLogLine;
 const async_1 = require("alcalzone-shared/async");
 const objects_1 = require("alcalzone-shared/objects");
 const node_child_process_1 = require("node:child_process");
@@ -47,7 +48,54 @@ const adapterTools_1 = require("../../../lib/adapterTools");
 const tools_1 = require("./tools");
 const debug = (0, debug_1.default)('testing:integration:TestHarness');
 const isWindows = /^win/.test(process.platform);
+const logLevels = ['silly', 'debug', 'info', 'warn', 'error'];
+/** Matches the color codes the adapter logger adds to the console output */
+// eslint-disable-next-line no-control-regex
+const ansiRegex = /\x1B\[\d+m/g;
+/** Matches `2023-11-08 13:31:57.123  - info: my-adapter.0 (1234) The message` */
+const logLineRegex = /^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3})\s+-\s+(\w+):\s+([\s\S]*)$/;
+/** Matches the `my-adapter.0 (1234) ` prefix the adapter logger prepends to each message */
+const logSourceRegex = /^(\S+\.\d+)(?: \(\d+\))? (.*)$/;
+/**
+ * Parses a line of the adapter output into a structured log message.
+ * Lines that are not in the ioBroker log format (e.g. plain `console.log` output)
+ * are returned as `info` messages.
+ *
+ * @param line A single line of the adapter's stdout/stderr
+ */
+function parseAdapterLogLine(line) {
+    const raw = line.replace(ansiRegex, '').trimEnd();
+    const match = logLineRegex.exec(raw);
+    const level = match?.[2].toLowerCase();
+    if (!match || !level || !logLevels.includes(level)) {
+        // Not an ioBroker log line, e.g. plain console output or a stack trace
+        return { level: 'info', timestamp: new Date(), from: undefined, message: raw, raw };
+    }
+    const sourceMatch = logSourceRegex.exec(match[3]);
+    return {
+        level,
+        timestamp: new Date(match[1]),
+        from: sourceMatch?.[1],
+        message: sourceMatch ? sourceMatch[2] : match[3],
+        raw,
+    };
+}
 const fromAdapterID = 'system.adapter.test.0';
+/**
+ * Encrypts or decrypts a value with the given secret. This is the same symmetric algorithm
+ * the JS-Controller uses for the `native` properties listed in `encryptedNative`,
+ * so applying it twice returns the original value.
+ *
+ * @param secret The secret from the `system.config` object
+ * @param value The value to encrypt or decrypt
+ */
+function encryptDecrypt(secret, value) {
+    let result = '';
+    for (let i = 0; i < value.length; ++i) {
+        result += String.fromCharCode(secret[i % secret.length].charCodeAt(0) ^ value.charCodeAt(i));
+    }
+    return result;
+}
 /**
  * The test harness capsules the execution of the JS-Controller and the adapter instance and monitors their status.
  * Use it in every test to start a fresh adapter instance
@@ -169,6 +217,7 @@ class TestHarness extends node_events_1.EventEmitter {
         const mainFileRelative = path.relative(this.testAdapterDir, mainFileAbsolute);
         const onClose = (code, signal) => {
             this._adapterProcess.removeAllListeners();
+            this.flushAdapterOutput();
             this._adapterExit = code != undefined ? code : signal;
             this.emit('failed', this._adapterExit);
         };
@@ -180,11 +229,14 @@ class TestHarness extends node_events_1.EventEmitter {
             : [mainFileRelative, '--console'];
         this._adapterProcess = (0, node_child_process_1.spawn)(command, args, {
             cwd: this.testAdapterDir,
-            stdio: ['inherit', 'inherit', 'inherit'],
+            // stdout and stderr are piped, so the log messages can be captured
+            stdio: ['inherit', 'pipe', 'pipe'],
             env: { ...process.env, ...env },
         })
             .on('close', onClose)
             .on('exit', onClose);
+        this._adapterProcess.stdout?.on('data', (chunk) => this.handleAdapterOutput(chunk, 'stdout'));
+        this._adapterProcess.stderr?.on('data', (chunk) => this.handleAdapterOutput(chunk, 'stderr'));
     }
     /**
      * Starts the adapter in a separate process and resolves after it has started
@@ -228,6 +280,7 @@ class TestHarness extends node_events_1.EventEmitter {
                     return;
                 }
                 this._adapterProcess.removeAllListeners();
+                this.flushAdapterOutput();
                 this._adapterExit = code != undefined ? code : signal;
                 this._adapterProcess = undefined;
                 debug('Adapter process terminated:');
@@ -250,16 +303,95 @@ class TestHarness extends node_events_1.EventEmitter {
         });
     }
     /**
-     * Updates the adapter config. The changes can be a subset of the target object
+     * Updates the adapter config. The changes can be a subset of the target object.
+     * The `native` properties that are listed in the instance object's `encryptedNative`
+     * are encrypted automatically, so they can be passed in plain text.
      */
     async changeAdapterConfig(adapterName, changes) {
         const adapterInstanceId = `system.adapter.${adapterName}.0`;
         const obj = await this.dbConnection.getObject(adapterInstanceId);
         if (obj) {
-            (0, objects_1.extend)(obj, changes);
+            (0, objects_1.extend)(obj, await this.encryptNativeChanges(obj, changes));
             await this.dbConnection.setObject(adapterInstanceId, obj);
         }
     }
+    /**
+     * Reads the config of an adapter instance. The `native` properties that are listed in the
+     * instance object's `encryptedNative` are decrypted automatically, so they are returned in plain text.
+     *
+     * @param adapterName The name of the adapter. Defaults to the adapter under test.
+     */
+    async getAdapterConfig(adapterName = this.adapterName) {
+        const obj = await this.dbConnection.getObject(`system.adapter.${adapterName}.0`);
+        if (!obj) {
+            return null;
+        }
+        const fields = this.getEncryptedFields(obj, obj.native);
+        if (fields.length) {
+            const secret = await this.getSystemSecret();
+            const native = { ...obj.native };
+            for (const field of fields) {
+                native[field] = encryptDecrypt(secret, native[field]);
+            }
+            debug(`Decrypted the following config fields: ${fields.join(', ')}`);
+            return { ...obj, native };
+        }
+        return obj;
+    }
+    /**
+     * Returns the names of all `native` properties in the given config that must be en-/decrypted
+     */
+    getEncryptedFields(obj, native) {
+        if (!native || !obj.encryptedNative?.length) {
+            return [];
+        }
+        // Only strings can be en-/decrypted, everything else is left untouched
+        return obj.encryptedNative.filter(field => typeof native[field] === 'string');
+    }
+    /**
+     * Encrypts all `native` properties of the given changes that are listed in the instance
+     * object's `encryptedNative`. Returns the changes to apply - the passed object is not modified.
+     */
+    async encryptNativeChanges(obj, changes) {
+        const fields = this.getEncryptedFields(obj, changes.native);
+        if (!fields.length) {
+            return changes;
+        }
+        const secret = await this.getSystemSecret();
+        const native = { ...changes.native };
+        for (const field of fields) {
+            native[field] = encryptDecrypt(secret, native[field]);
+        }
+        debug(`Encrypted the following config fields: ${fields.join(', ')}`);
+        return { ...changes, native };
+    }
+    _systemSecret;
+    /**
+     * Reads the secret from the `system.config` object. The secret is cached after the first read.
+     */
+    async getSystemSecret() {
+        if (this._systemSecret === undefined) {
+            const systemConfig = await this.dbConnection.getObject('system.config');
+            const secret = systemConfig?.native?.secret;
+            if (typeof secret !== 'string' || !secret) {
+                throw new Error('Could not read the secret from the object "system.config"!');
+            }
+            this._systemSecret = secret;
+        }
+        return this._systemSecret;
+    }
+    /**
+     * Encrypts a value the same way the JS-Controller does for `encryptedNative` properties
+     */
+    async encryptValue(value) {
+        return encryptDecrypt(await this.getSystemSecret(), value);
+    }
+    /**
+     * Decrypts a value that was encrypted for an `encryptedNative` property
+     */
+    async decryptValue(value) {
+        return encryptDecrypt(await this.getSystemSecret(), value);
+    }
     getAdapterExecutionMode() {
         return (0, adapterTools_1.getAdapterExecutionMode)(this.testAdapterDir);
     }
@@ -296,5 +428,63 @@ class TestHarness extends node_events_1.EventEmitter {
             },
         }, (err, id) => console.log(`published message ${id}`));
     }
+    /** The log messages of the adapter under test */
+    _logs = [];
+    /** The incomplete last line of each output stream, waiting for the rest to arrive */
+    _outputBuffer = { stdout: '', stderr: '' };
+    /**
+     * Handles a chunk of the adapter's output. Because a chunk may end in the middle of a line,
+     * the incomplete rest is buffered until the remainder arrives.
+     *
+     * @param chunk The received chunk
+     * @param stream Which of the adapter's output streams the chunk was received on
+     */
+    handleAdapterOutput(chunk, stream) {
+        const lines = (this._outputBuffer[stream] + chunk.toString()).split('\n');
+        // The last entry is either an incomplete line or empty - keep it for the next chunk
+        this._outputBuffer[stream] = lines.pop() ?? '';
+        for (const line of lines) {
+            this.handleAdapterOutputLine(line, stream);
+        }
+    }
+    /** Prints a line of the adapter's output and remembers it as a log message */
+    handleAdapterOutputLine(line, stream) {
+        // Forward the output, so it stays visible while the tests are running
+        process[stream].write(`${line}\n`);
+        if (line.trim()) {
+            this._logs.push(parseAdapterLogLine(line));
+        }
+    }
+    /** Handles the incomplete lines that were left over when the adapter exited */
+    flushAdapterOutput() {
+        for (const stream of ['stdout', 'stderr']) {
+            const rest = this._outputBuffer[stream];
+            this._outputBuffer[stream] = '';
+            if (rest) {
+                this.handleAdapterOutputLine(rest, stream);
+            }
+        }
+    }
+    /**
+     * Returns the log messages the adapter has printed so far
+     *
+     * @param level If given, only the messages with this log level are returned
+     */
+    getLogs(level) {
+        return level ? this._logs.filter(log => log.level === level) : [...this._logs];
+    }
+    /** Forgets all log messages that were captured so far */
+    clearLogs() {
+        this._logs = [];
+    }
+    /**
+     * Tests if the adapter has logged a message matching the given pattern
+     *
+     * @param pattern A RegExp or a string that must be contained in the message
+     * @param level If given, only the messages with this log level are checked
+     */
+    hasLog(pattern, level) {
+        return this.getLogs(level).some(log => typeof pattern === 'string' ? log.message.includes(pattern) : pattern.test(log.message));
+    }
 }
 exports.TestHarness = TestHarness;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iobroker/testing",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "Shared utilities for adapter and module testing in ioBroker",
   "main": "build/index.js",
   "types": "build/index.d.ts",