@matterbridge/vitest-utils 3.8.0-dev-20260526-20ee3dc → 3.8.0-dev-20260527-b4148f4

package/dist/export.d.ts

@@ -1 +1,5 @@
-export * from './vitestHelpers.js';
+export * from './flushAsync.js';
+export * from './logKeepAlives.js';
+export * from './matterRequest.js';
+export * from './vitestMatterTest.js';
+export * from './vitestSetupTest.js';

package/dist/export.js

@@ -1 +1,5 @@
-export * from './vitestHelpers.js';
+export * from './flushAsync.js';
+export * from './logKeepAlives.js';
+export * from './matterRequest.js';
+export * from './vitestMatterTest.js';
+export * from './vitestSetupTest.js';

package/dist/flushAsync.d.ts

@@ -0,0 +1 @@
+export declare function flushAsync(ticks?: number, microTurns?: number, pause?: number): Promise<void>;

package/dist/flushAsync.js

@@ -0,0 +1,8 @@
+export async function flushAsync(ticks = 3, microTurns = 10, pause = 250) {
+    for (let i = 0; i < ticks; i++)
+        await new Promise((resolve) => setImmediate(resolve));
+    for (let i = 0; i < microTurns; i++)
+        await Promise.resolve();
+    if (pause)
+        await new Promise((resolve) => setTimeout(resolve, pause));
+}

package/dist/logKeepAlives.d.ts

@@ -0,0 +1,2 @@
+import { AnsiLogger } from 'node-ansi-logger';
+export declare function logKeepAlives(log?: AnsiLogger): number;

package/dist/logKeepAlives.js

@@ -0,0 +1,31 @@
+import { inspect } from 'node:util';
+import { rs } from 'node-ansi-logger';
+export function logKeepAlives(log) {
+    const handles = process._getActiveHandles?.() ?? [];
+    const requests = process._getActiveRequests?.() ?? [];
+    const fmtHandle = (h, i) => {
+        const ctor = h?.constructor?.name ?? 'Unknown';
+        const hasRef = typeof h?.hasRef === 'function' ? h.hasRef() : undefined;
+        const isPort = h?.constructor?.name?.includes('MessagePort');
+        const fd = h?.fd ?? h?._handle?.fd;
+        return { i, type: ctor, hasRef, isPort, fd };
+    };
+    const fmtReq = (r, i) => {
+        const ctor = r?.constructor?.name ?? 'Unknown';
+        return { i, type: ctor };
+    };
+    const summary = {
+        handles: handles.map(fmtHandle),
+        requests: requests.map(fmtReq),
+    };
+    if (summary.handles.length === 0 && summary.requests.length === 0) {
+        log?.debug('KeepAlive: no active handles or requests.');
+    }
+    else {
+        log?.debug(`KeepAlive:${rs}\n${inspect(summary, { depth: 5, colors: true })}`);
+        if (!log) {
+            process.stdout.write(`KeepAlive:\n${inspect(summary, { depth: 5, colors: true })}\n`);
+        }
+    }
+    return summary.handles.length + summary.requests.length;
+}

package/dist/matterRequest.d.ts

@@ -0,0 +1,10 @@
+import { ColorControl } from '@matter/types/clusters/color-control';
+import { LevelControl } from '@matter/types/clusters/level-control';
+export declare function getMoveToLevelRequest(level: number, transitionTime: number, executeIfOff: boolean): LevelControl.MoveToLevelRequest;
+export declare function getMoveToColorTemperatureRequest(colorTemperatureMireds: number, transitionTime: number, executeIfOff: boolean): ColorControl.MoveToColorTemperatureRequest;
+export declare function getMoveToHueRequest(hue: number, transitionTime: number, executeIfOff: boolean): ColorControl.MoveToHueRequest;
+export declare function getEnhancedMoveToHueRequest(enhancedHue: number, transitionTime: number, executeIfOff: boolean): ColorControl.EnhancedMoveToHueRequest;
+export declare function getMoveToSaturationRequest(saturation: number, transitionTime: number, executeIfOff: boolean): ColorControl.MoveToSaturationRequest;
+export declare function getMoveToHueAndSaturationRequest(hue: number, saturation: number, transitionTime: number, executeIfOff: boolean): ColorControl.MoveToHueAndSaturationRequest;
+export declare function getEnhancedMoveToHueAndSaturationRequest(enhancedHue: number, saturation: number, transitionTime: number, executeIfOff: boolean): ColorControl.EnhancedMoveToHueAndSaturationRequest;
+export declare function getMoveToColorRequest(colorX: number, colorY: number, transitionTime: number, executeIfOff: boolean): ColorControl.MoveToColorRequest;

package/dist/matterRequest.js

@@ -0,0 +1,78 @@
+import { ColorControl } from '@matter/types/clusters/color-control';
+export function getMoveToLevelRequest(level, transitionTime, executeIfOff) {
+    const request = {
+        level,
+        transitionTime,
+        optionsMask: { executeIfOff, coupleColorTempToLevel: false },
+        optionsOverride: { executeIfOff, coupleColorTempToLevel: false },
+    };
+    return request;
+}
+export function getMoveToColorTemperatureRequest(colorTemperatureMireds, transitionTime, executeIfOff) {
+    const request = {
+        colorTemperatureMireds,
+        transitionTime,
+        optionsMask: { executeIfOff },
+        optionsOverride: { executeIfOff },
+    };
+    return request;
+}
+export function getMoveToHueRequest(hue, transitionTime, executeIfOff) {
+    const request = {
+        hue,
+        transitionTime,
+        direction: ColorControl.Direction.Shortest,
+        optionsMask: { executeIfOff },
+        optionsOverride: { executeIfOff },
+    };
+    return request;
+}
+export function getEnhancedMoveToHueRequest(enhancedHue, transitionTime, executeIfOff) {
+    const request = {
+        enhancedHue,
+        transitionTime,
+        direction: ColorControl.Direction.Shortest,
+        optionsMask: { executeIfOff },
+        optionsOverride: { executeIfOff },
+    };
+    return request;
+}
+export function getMoveToSaturationRequest(saturation, transitionTime, executeIfOff) {
+    const request = {
+        saturation,
+        transitionTime,
+        optionsMask: { executeIfOff },
+        optionsOverride: { executeIfOff },
+    };
+    return request;
+}
+export function getMoveToHueAndSaturationRequest(hue, saturation, transitionTime, executeIfOff) {
+    const request = {
+        hue,
+        saturation,
+        transitionTime,
+        optionsMask: { executeIfOff },
+        optionsOverride: { executeIfOff },
+    };
+    return request;
+}
+export function getEnhancedMoveToHueAndSaturationRequest(enhancedHue, saturation, transitionTime, executeIfOff) {
+    const request = {
+        enhancedHue,
+        saturation,
+        transitionTime,
+        optionsMask: { executeIfOff },
+        optionsOverride: { executeIfOff },
+    };
+    return request;
+}
+export function getMoveToColorRequest(colorX, colorY, transitionTime, executeIfOff) {
+    const request = {
+        colorX,
+        colorY,
+        transitionTime,
+        optionsMask: { executeIfOff },
+        optionsOverride: { executeIfOff },
+    };
+    return request;
+}

package/dist/vitestMatterTest.d.ts

@@ -0,0 +1,21 @@
+import '@matter/nodejs';
+import { Environment } from '@matter/general';
+import { Endpoint, ServerNode } from '@matter/node';
+import { AggregatorEndpoint } from '@matter/node/endpoints';
+import { DeviceTypeId } from '@matter/types/datatype';
+import { type PlatformMatterbridge } from '@matterbridge/types';
+export declare let environment: Environment;
+export declare let server: ServerNode<ServerNode.RootEndpoint>;
+export declare let aggregator: Endpoint<AggregatorEndpoint>;
+export declare function createTestEnvironment(): Promise<Environment>;
+export declare function destroyTestEnvironment(): Promise<void>;
+export declare function getPlatformMatterbridge(): PlatformMatterbridge;
+export declare function flushAllEndpointNumberPersistence(targetServer: ServerNode, rounds?: number, ticks?: number, microTurns?: number, pause?: number): Promise<void>;
+export declare function assertAllEndpointNumbersPersisted(targetServer: ServerNode): Promise<number>;
+export declare function closeServerNodeStores(targetServer?: ServerNode): Promise<void>;
+export declare function createServerNode(port: number, deviceType?: DeviceTypeId, ticks?: number, microTurns?: number, pause?: number): Promise<[ServerNode<ServerNode.RootEndpoint>, Endpoint<AggregatorEndpoint>]>;
+export declare function startServerNode(ticks?: number, microTurns?: number, pause?: number): Promise<[ServerNode<ServerNode.RootEndpoint>, Endpoint<AggregatorEndpoint>]>;
+export declare function stopServerNode(ticks?: number, microTurns?: number, pause?: number): Promise<void>;
+export declare function flushServerNode(ticks?: number, microTurns?: number, pause?: number): Promise<void>;
+export declare function addDevice(owner: ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>, device: Endpoint, rounds?: number, pause?: number): Promise<boolean>;
+export declare function deleteDevice(owner: ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>, device: Endpoint, rounds?: number, pause?: number): Promise<boolean>;

package/dist/vitestMatterTest.js

@@ -0,0 +1,280 @@
+import '@matter/nodejs';
+import path from 'node:path';
+import { inspect } from 'node:util';
+import { Environment, Lifecycle, LogFormat as MatterLogFormat, LogLevel as MatterLogLevel } from '@matter/general';
+import { Endpoint, ServerNode, ServerNodeStore } from '@matter/node';
+import { AggregatorEndpoint } from '@matter/node/endpoints';
+import { DeviceTypeId, VendorId } from '@matter/types/datatype';
+import { MATTER_STORAGE_DIR } from '@matterbridge/types';
+import { er, rs } from 'node-ansi-logger';
+import { flushAsync } from './flushAsync.js';
+import { HOMEDIR, NAME } from './vitestSetupTest.js';
+export let environment;
+export let server;
+export let aggregator;
+export async function createTestEnvironment() {
+    expect(NAME).toBeDefined();
+    expect(typeof NAME).toBe('string');
+    expect(NAME.length).toBeGreaterThanOrEqual(4);
+    environment = Environment.default;
+    environment.vars.set('log.level', MatterLogLevel.DEBUG);
+    environment.vars.set('log.format', MatterLogFormat.ANSI);
+    environment.vars.set('path.root', path.join(HOMEDIR, '.matterbridge', MATTER_STORAGE_DIR));
+    environment.vars.set('runtime.signals', false);
+    environment.vars.set('runtime.exitcode', false);
+    return environment;
+}
+export async function destroyTestEnvironment() {
+}
+export function getPlatformMatterbridge() {
+    return {
+        systemInformation: {
+            interfaceName: 'eth0',
+            macAddress: 'aa:bb:cc:dd:ee:ff',
+            ipv4Address: '',
+            ipv6Address: '',
+            osRelease: 'xx.xx.xx.xx.xx.xx',
+            nodeVersion: '22.1.10',
+            hostname: 'jest',
+            user: 'matterbridge',
+            osType: 'Linux',
+            osPlatform: 'linux',
+            osArch: 'x64',
+            totalMemory: '0 B',
+            freeMemory: '0 B',
+            systemUptime: '0s',
+            processUptime: '0s',
+            cpuUsage: '0%',
+            processCpuUsage: '0%',
+            rss: '0 B',
+            heapTotal: '0 B',
+            heapUsed: '0 B',
+        },
+        rootDirectory: HOMEDIR,
+        homeDirectory: HOMEDIR,
+        matterbridgeDirectory: path.join(HOMEDIR, '.matterbridge'),
+        matterbridgePluginDirectory: path.join(HOMEDIR, 'Matterbridge'),
+        matterbridgeCertDirectory: path.join(HOMEDIR, '.mattercert'),
+        globalModulesDirectory: path.join(HOMEDIR, 'node_modules'),
+        matterbridgeVersion: '3.8.0',
+        matterbridgeLatestVersion: '3.8.0',
+        matterbridgeDevVersion: '3.8.0',
+        frontendVersion: '3.8.0',
+        bridgeMode: '',
+        restartMode: '',
+        virtualMode: 'mounted_switch',
+        aggregatorVendorId: 0xfff1,
+        aggregatorVendorName: 'Matterbridge',
+        aggregatorProductId: 0x8000,
+        aggregatorProductName: 'Matterbridge Jest',
+        addBridgedEndpoint: jest.fn(async () => {
+            return Promise.resolve(true);
+        }),
+        removeBridgedEndpoint: jest.fn(async () => {
+            return Promise.resolve(true);
+        }),
+        removeAllBridgedEndpoints: jest.fn(async () => {
+            return Promise.resolve(true);
+        }),
+        addVirtualEndpoint: jest.fn(async () => {
+            return Promise.resolve();
+        }),
+    };
+}
+export async function flushAllEndpointNumberPersistence(targetServer, rounds = 3, ticks = 1, microTurns = 1, pause = 10) {
+    const nodeStore = targetServer.env.get(ServerNodeStore);
+    for (let i = 0; i < rounds; i++) {
+        await flushAsync(ticks, microTurns, pause);
+        await nodeStore.endpointStores.close();
+    }
+}
+function getRootServerNode(endpoint) {
+    let current = endpoint;
+    while (current.owner) {
+        current = current.owner;
+    }
+    return current;
+}
+function collectAllEndpoints(root) {
+    const list = [];
+    const walk = (ep) => {
+        list.push(ep);
+        if (ep.parts) {
+            for (const child of ep.parts) {
+                walk(child);
+            }
+        }
+    };
+    walk(root);
+    return list;
+}
+export async function assertAllEndpointNumbersPersisted(targetServer) {
+    const nodeStore = targetServer.env.get(ServerNodeStore);
+    await nodeStore.endpointStores.close();
+    const all = collectAllEndpoints(targetServer);
+    for (const ep of all) {
+        const store = nodeStore.storeForEndpoint(ep);
+        if (ep.maybeNumber === 0) {
+            expect(store.number ?? 0).toBe(0);
+        }
+        else {
+            expect(store.number).toBeGreaterThan(0);
+        }
+    }
+    return all.length;
+}
+export async function closeServerNodeStores(targetServer) {
+    if (!targetServer)
+        targetServer = server;
+    await targetServer?.env.get(ServerNodeStore)?.endpointStores.close();
+}
+export async function createServerNode(port, deviceType = DeviceTypeId(0x000e), ticks = 1, microTurns = 1, pause = 10) {
+    const { randomBytes } = await import('node:crypto');
+    const random = randomBytes(8).toString('hex');
+    server = await ServerNode.create({
+        id: NAME + 'ServerNode',
+        environment,
+        productDescription: {
+            name: NAME + 'ServerNode',
+            deviceType: DeviceTypeId(deviceType),
+            vendorId: VendorId(0xfff1),
+            productId: 0x8000,
+        },
+        basicInformation: {
+            vendorId: VendorId(0xfff1),
+            vendorName: 'Matterbridge',
+            productId: 0x8000,
+            productName: 'Matterbridge ' + NAME,
+            nodeLabel: NAME + 'ServerNode',
+            hardwareVersion: 1,
+            softwareVersion: 1,
+            reachable: true,
+            serialNumber: 'SN' + random,
+            uniqueId: 'UI' + random,
+        },
+        network: {
+            listeningAddressIpv4: undefined,
+            listeningAddressIpv6: undefined,
+            port,
+            tcp: true,
+            transportPreference: 'udp',
+        },
+        operationalCredentials: {
+            certification: undefined,
+        },
+    });
+    expect(server).toBeDefined();
+    expect(server.lifecycle.isReady).toBeTruthy();
+    aggregator = new Endpoint(AggregatorEndpoint, {
+        id: NAME + 'AggregatorNode',
+    });
+    expect(aggregator).toBeDefined();
+    await server.add(aggregator);
+    expect(server.parts.has(aggregator.id)).toBeTruthy();
+    expect(server.parts.has(aggregator)).toBeTruthy();
+    expect(aggregator.lifecycle.isReady).toBeTruthy();
+    expect(server.lifecycle.isOnline).toBeFalsy();
+    await flushAsync(ticks, microTurns, pause);
+    return [server, aggregator];
+}
+export async function startServerNode(ticks = 1, microTurns = 1, pause = 10) {
+    if (!server || !aggregator) {
+        throw new Error('Server node and aggregator must be created before starting the server. Call createServerNode() first.');
+    }
+    await new Promise((resolve, reject) => {
+        server.lifecycle.online.on(async () => {
+            resolve();
+        });
+        server.start().catch((err) => reject(err));
+    });
+    expect(server.lifecycle.isReady).toBeTruthy();
+    expect(server.lifecycle.isOnline).toBeTruthy();
+    expect(server.lifecycle.isCommissioned).toBeFalsy();
+    expect(server.lifecycle.isPartsReady).toBeTruthy();
+    expect(server.lifecycle.hasId).toBeTruthy();
+    expect(server.lifecycle.hasNumber).toBeTruthy();
+    expect(aggregator.lifecycle.isReady).toBeTruthy();
+    expect(aggregator.lifecycle.isInstalled).toBeTruthy();
+    expect(aggregator.lifecycle.isPartsReady).toBeTruthy();
+    expect(aggregator.lifecycle.hasId).toBeTruthy();
+    expect(aggregator.lifecycle.hasNumber).toBeTruthy();
+    await flushAsync(ticks, microTurns, pause);
+    return [server, aggregator];
+}
+export async function stopServerNode(ticks = 1, microTurns = 1, pause = 10) {
+    await flushAllEndpointNumberPersistence(server);
+    await assertAllEndpointNumbersPersisted(server);
+    expect(server).toBeDefined();
+    expect(server.lifecycle.isReady).toBeTruthy();
+    expect(server.lifecycle.isOnline).toBeTruthy();
+    await server.close();
+    expect(server.lifecycle.isReady).toBeFalsy();
+    expect(server.lifecycle.isOnline).toBeFalsy();
+    await flushAsync(ticks, microTurns, pause);
+}
+export async function flushServerNode(ticks = 1, microTurns = 1, pause = 10) {
+    await flushAllEndpointNumberPersistence(server);
+    await assertAllEndpointNumbersPersisted(server);
+    expect(server).toBeDefined();
+    expect(server.lifecycle.isReady).toBeTruthy();
+    expect(server.lifecycle.isOnline).toBeFalsy();
+    await server.close();
+    expect(server.lifecycle.isReady).toBeFalsy();
+    expect(server.lifecycle.isOnline).toBeFalsy();
+    await flushAsync(ticks, microTurns, pause);
+}
+export async function addDevice(owner, device, rounds = 3, pause = 10) {
+    expect(owner).toBeDefined();
+    expect(device).toBeDefined();
+    expect(owner.lifecycle.isReady).toBeTruthy();
+    expect(owner.construction.status).toBe(Lifecycle.Status.Active);
+    expect(owner.lifecycle.isPartsReady).toBeTruthy();
+    const rootServerNode = getRootServerNode(owner);
+    await flushAllEndpointNumberPersistence(rootServerNode, rounds, pause);
+    try {
+        await owner.add(device);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : error;
+        const errorInspect = inspect(error, { depth: 10 });
+        process.stderr.write(`${er}Error adding device ${device.maybeId}.${device.maybeNumber}: ${errorMessage}${rs}\nStack: ${errorInspect}\n`);
+        return false;
+    }
+    await device.construction.ready;
+    expect(owner.parts.has(device)).toBeTruthy();
+    expect(owner.lifecycle.isPartsReady).toBeTruthy();
+    expect(device.lifecycle.isReady).toBeTruthy();
+    expect(device.lifecycle.isInstalled).toBeTruthy();
+    expect(device.lifecycle.hasId).toBeTruthy();
+    expect(device.lifecycle.hasNumber).toBeTruthy();
+    expect(device.construction.status).toBe(Lifecycle.Status.Active);
+    await flushAllEndpointNumberPersistence(rootServerNode, rounds, pause);
+    return true;
+}
+export async function deleteDevice(owner, device, rounds = 3, pause = 10) {
+    expect(owner).toBeDefined();
+    expect(device).toBeDefined();
+    expect(owner.lifecycle.isReady).toBeTruthy();
+    expect(owner.construction.status).toBe(Lifecycle.Status.Active);
+    expect(owner.lifecycle.isPartsReady).toBeTruthy();
+    const rootServerNode = getRootServerNode(owner);
+    await flushAllEndpointNumberPersistence(rootServerNode, rounds, pause);
+    try {
+        await device.delete();
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : error;
+        const errorInspect = inspect(error, { depth: 10 });
+        process.stderr.write(`${er}Error deleting device ${device.maybeId}.${device.maybeNumber}: ${errorMessage}${rs}\nStack: ${errorInspect}\n`);
+        return false;
+    }
+    expect(owner.parts.has(device)).toBeFalsy();
+    expect(owner.lifecycle.isPartsReady).toBeTruthy();
+    expect(device.lifecycle.isReady).toBeFalsy();
+    expect(device.lifecycle.isInstalled).toBeFalsy();
+    expect(device.lifecycle.hasId).toBeTruthy();
+    expect(device.lifecycle.hasNumber).toBeTruthy();
+    expect(device.construction.status).toBe(Lifecycle.Status.Destroyed);
+    await flushAllEndpointNumberPersistence(rootServerNode, rounds, pause);
+    return true;
+}

package/dist/{vitestHelpers.js → vitestSetupTest.js}

@@ -1,4 +1,4 @@
-import { rmSync } from 'node:fs';
+import { mkdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { AnsiLogger } from 'node-ansi-logger';
 export const originalProcessArgv = Object.freeze([...process.argv]);
@@ -27,6 +27,7 @@ export async function setupTest(name, debug = false) {
     process.argv = ['vitest', name];
     log = new AnsiLogger({ logName: 'Vitest', logTimestampFormat: 4, logLevel: "info" });
     rmSync(HOMEDIR, { recursive: true, force: true });
+    mkdirSync(HOMEDIR, { recursive: true });
     const { vi } = await import('vitest');
     loggerDebugSpy = vi.spyOn(AnsiLogger.prototype, 'debug');
     loggerInfoSpy = vi.spyOn(AnsiLogger.prototype, 'info');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matterbridge/vitest-utils",
-  "version": "3.8.0-dev-20260526-20ee3dc",
+  "version": "3.8.0-dev-20260527-b4148f4",
   "description": "Matterbridge vitest utility library",
   "author": "https://github.com/Luligu",
   "homepage": "https://matterbridge.io/",
@@ -61,6 +61,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
+    "@matterbridge/types": "3.8.0-dev-20260527-b4148f4",
     "node-ansi-logger": "3.3.0-dev-20260524-cac9dd5"
   }
 }