@matterbridge/test-utils 3.10.7-dev-20260823-f911eb8

package/dist/jest/matterTest.js

@@ -0,0 +1,722 @@
+/**
+ * @file packages/jest-utils/src/jestMatterTest.ts
+ * @description This file contains the Jest Matter Test Environment.
+ * @author Luca Liguori
+ * @created 2026-04-19
+ * @version 1.0.0
+ * @license Apache-2.0
+ *
+ * Copyright 2025, 2026, 2027 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// oxlint-disable-next-line import/no-unassigned-import
+import '@matter/nodejs'; // Set up Node.js environment for matter.js
+import path from 'node:path';
+// @matter
+import { Environment, Lifecycle, LogFormat as MatterLogFormat, LogLevel as MatterLogLevel } from '@matter/general';
+import { Endpoint, ServerNode, ServerNodeStore } from '@matter/node';
+import { BridgedDeviceBasicInformationServer } from '@matter/node/behaviors/bridged-device-basic-information';
+import { DescriptorServer } from '@matter/node/behaviors/descriptor';
+import { OnOffServer } from '@matter/node/behaviors/on-off';
+import { MountedOnOffControlDevice } from '@matter/node/devices/mounted-on-off-control';
+import { AggregatorEndpoint } from '@matter/node/endpoints';
+import { DeviceTypeId, VendorId } from '@matter/types/datatype';
+// @matterbridge
+import { MATTER_STORAGE_DIR } from '@matterbridge/types';
+import { inspectError } from '@matterbridge/utils/error';
+// node-ansi-logger module
+import { er, rs } from 'node-ansi-logger';
+// local modules
+import { flushAsync } from '../flushAsync.js';
+import { HOMEDIR, log, NAME } from './setupTest.js';
+export let environment;
+export let server;
+export let aggregator;
+const noop = () => undefined;
+/**
+ * Create a matter test environment for testing:
+ * - it will remove any existing home directory
+ * - setup the matter environment with name, debug logging and ANSI format
+ *
+ * @returns {Environment} - The default matter environment.
+ * @example
+ * ```typescript
+ * const NAME = 'BaseTest';
+ * const MATTER_PORT = 8000;
+ * const MATTER_CREATE_ONLY = true;
+ *
+ * // Setup the test environment
+ * await setupTest(NAME, false);
+ *
+ * // Setup the Matter test environment
+ * await createTestEnvironment();
+ *
+ * // Create the server node and aggregator
+ * await createServerNode(MATTER_PORT);
+ *
+ * // Start the server node if not in create-only mode
+ * if (!MATTER_CREATE_ONLY) await startServerNode();
+ *
+ * // Stop or flush the server node depending on the create-only mode
+ * if (MATTER_CREATE_ONLY) await flushServerNode();
+ * else await stopServerNode();
+ *
+ * // Destroy the Matter test environment
+ * await destroyTestEnvironment();
+ * ```
+ */
+// oxlint-disable-next-line typescript/require-await
+export async function createTestEnvironment() {
+    expect(NAME).toBeDefined();
+    expect(typeof NAME).toBe('string');
+    expect(NAME.length).toBeGreaterThanOrEqual(4); // avoid accidental deletion of short paths like "/" or "C:\"
+    // Setup the matter environment
+    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;
+}
+/**
+ * Destroy the matter test environment
+ *
+ * @returns {Promise<void>} A promise that resolves when the test environment is destroyed.
+ * @example
+ * ```typescript
+ * const NAME = 'BaseTest';
+ * const MATTER_PORT = 8000;
+ * const MATTER_CREATE_ONLY = true;
+ *
+ * // Setup the test environment
+ * await setupTest(NAME, false);
+ *
+ * // Setup the Matter test environment
+ * await createTestEnvironment();
+ *
+ * // Create the server node and aggregator
+ * await createServerNode(MATTER_PORT);
+ *
+ * // Start the server node if not in create-only mode
+ * if (!MATTER_CREATE_ONLY) await startServerNode();
+ *
+ * // Stop or flush the server node depending on the create-only mode
+ * if (MATTER_CREATE_ONLY) await flushServerNode();
+ * else await stopServerNode();
+ *
+ * // Destroy the Matter test environment
+ * await destroyTestEnvironment();
+ * ```
+ */
+export async function destroyTestEnvironment() {
+    // Nothing to clean up right now
+}
+/**
+ * Get a mocked PlatformMatterbridge.
+ *
+ * @returns {PlatformMatterbridge} An object representing the mocked PlatformMatterbridge.
+ */
+export function getMatterbridge() {
+    const matterbridge = {
+        systemInformation: {
+            interfaceName: 'eth0',
+            macAddress: 'aa:bb:cc:dd:ee:ff',
+            ipv4Address: '192.168.68.100',
+            ipv6Address: 'fd78:cbf8:4939:46e2:51b2:2163:7f88:c33d',
+            nodeVersion: '24.16.0',
+            hostname: 'matterbridge',
+            user: 'jest',
+            osType: 'Linux',
+            osRelease: '6.8.0-xxxx',
+            osPlatform: 'linux',
+            osArch: 'arm64',
+            totalMemory: '0 B',
+            freeMemory: '0 B',
+            systemUptime: '0s',
+            processUptime: '0s',
+            cpuUsage: '0%',
+            processCpuUsage: '0%',
+            rss: '0 B',
+            heapTotal: '0 B',
+            heapUsed: '0 B',
+        },
+        uuid: '00000000-0000-0000-0000-000000000000',
+        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.10.7',
+        matterbridgeLatestVersion: '3.10.7',
+        matterbridgeDevVersion: '3.10.7',
+        frontendVersion: '3.5.9',
+        bridgeMode: 'none',
+        restartMode: 'none',
+        virtualMode: 'mounted_switch',
+        aggregatorVendorId: VendorId(0xfff1),
+        aggregatorVendorName: 'Matterbridge',
+        aggregatorProductId: 0x8000,
+        aggregatorProductName: 'Matterbridge Jest',
+    };
+    return matterbridge;
+}
+/**
+ * Add a bridged endpoint
+ *
+ * @param {string} pluginName The name of the plugin.
+ * @param {Endpoint} device The device to add.
+ * @returns {Promise<boolean>} A promise that resolves to true if the endpoint was added successfully, or rejects with an error if the operation failed.
+ */
+export const addBridgedEndpoint = async (pluginName, device) => {
+    try {
+        await aggregator.add(device);
+        return Promise.resolve(true);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+};
+/**
+ * Remove a bridged endpoint
+ *
+ * @param {string} pluginName The name of the plugin.
+ * @param {Endpoint} device The device to remove.
+ * @returns {Promise<boolean>} A promise that resolves to true if the endpoint was removed successfully, or rejects with an error if the operation failed.
+ */
+export const removeBridgedEndpoint = async (pluginName, device) => {
+    try {
+        await device.delete();
+        return Promise.resolve(true);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+};
+/**
+ * Remove all bridged endpoints
+ *
+ * @param {string} _pluginName The name of the plugin.
+ * @param {number} _delay The delay before removing all endpoints.
+ * @returns {Promise<boolean>} A promise that resolves to true if all endpoints were removed successfully, or rejects with an error if the operation failed.
+ */
+export const removeAllBridgedEndpoints = async (_pluginName, _delay = 0) => {
+    try {
+        for (const device of aggregator.parts) {
+            await device.delete();
+        }
+        return Promise.resolve(true);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+};
+/**
+ * Add a virtual endpoint
+ *
+ * @param {string} pluginName The name of the plugin.
+ * @param {string} name The name of the virtual endpoint.
+ * @param {'light' | 'outlet' | 'switch' | 'mounted_switch'} type The type of the virtual endpoint.
+ * @param {() => Promise<void>} callback The callback to execute when the virtual endpoint is triggered.
+ * @returns {Promise<boolean>} A promise that resolves to true if the virtual endpoint was added successfully, or rejects with an error if the operation failed.
+ */
+export const addVirtualEndpoint = async (pluginName, name, type, callback) => {
+    try {
+        const device = new Endpoint(MountedOnOffControlDevice.with(BridgedDeviceBasicInformationServer), {
+            id: name.replaceAll(' ', '') + ':' + type,
+            bridgedDeviceBasicInformation: {
+                vendorId: VendorId(0xfff1),
+                vendorName: 'Matterbridge',
+                productName: 'Matterbridge Virtual Device',
+                nodeLabel: name.slice(0, 32),
+                softwareVersion: 20000,
+                softwareVersionString: '2.0.0',
+            },
+            onOff: { onOff: false },
+        });
+        // Set up an event listener for when the `onOff` state changes.
+        device.events.onOff.onOff$Changed.on((value) => {
+            // If the `onOff` state becomes true, turn off the virtual device and execute the callback.
+            if (value) {
+                void callback().catch(/* v8 ignore next */ noop);
+                void device.setStateOf(OnOffServer, { onOff: false }).catch(/* v8 ignore next */ noop);
+            }
+        });
+        // Add the created device to the aggregator.
+        await aggregator.add(device);
+        // Add the OnOffPlugInUnit to MountedOnOffControlDevice (Matter 1.4.2 specs added this (new case of superset) for legacy controllers to recognize the mounted switch).
+        await device.act(async (agent) => {
+            const descriptor = await agent.load(DescriptorServer);
+            descriptor.addDeviceTypes('OnOffPlugInUnit');
+        });
+        // Initially set the state of the virtual device's `OnOffServer` to false (off).
+        await device.setStateOf(OnOffServer, { onOff: false });
+        return Promise.resolve(true);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+};
+/**
+ * Inject matterbridge platform for testing.
+ *
+ * @param {object} platform The platform to inject.
+ *
+ * @example
+ * ```typescript
+ * platform = new MatterbridgePlatform(matterbridge, log, config);
+ * // Inject in the platform the Matterbridge environment
+ * addMatterbridge(platform);
+ * ```
+ */
+export function addMatterbridge(platform) {
+    expect(platform).toBeDefined();
+    // Setup the platform MatterNode helpers
+    // @ts-expect-error - setMatterNode is intentionally private
+    platform.setMatterNode(addBridgedEndpoint, removeBridgedEndpoint, removeAllBridgedEndpoints, addVirtualEndpoint);
+}
+/**
+ * Flush (await) the lazy endpoint number persistence mechanism used by matter.js.
+ *
+ * Background:
+ *  assignNumber() batches persistence (store.saveNumber + updating __nextNumber__) via an internal promise (#numbersPersisted).
+ *  Calling endpointStores.close() waits for the current batch only. If new endpoints were added in the same macrotask
+ *  cycle additional micro/macro turns might be needed to ensure the batch started. We defensively yield macrotasks
+ *  (setImmediate) and then await close() multiple rounds.
+ *
+ * @param {ServerNode} targetServer  The server whose endpoint numbering persistence should be flushed.
+ * @param {number} rounds Number of macrotask + close cycles to run (3 is usually sufficient).
+ * @param {number} ticks Number of macrotask (setImmediate) turns to yield after stopping the server to allow asynchronous work to complete before returning (default 1).
+ * @param {number} microTurns Number of microtask drains (Promise.resolve chains) to perform after macrotask yielding to allow asynchronous work to complete before returning (default 1).
+ * @param {number} pause Duration in ms to wait between cycles (default 10ms) to allow any follow-up work scheduled by close() to run.
+ * @returns {Promise<void>} Resolves when pending number persistence batches have completed.
+ */
+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();
+    }
+}
+/**
+ * Get the root ServerNode for a given Endpoint by traversing up the owner chain until the root endpoint is reached.
+ *
+ * @param {Endpoint} endpoint The endpoint to find the root server for.
+ * @returns {ServerNode<ServerNode.RootEndpoint>} The root ServerNode of the given endpoint.
+ */
+function getRootServerNode(endpoint) {
+    let current = endpoint;
+    while (current.owner) {
+        current = current.owner;
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return current;
+}
+/**
+ * Collect all endpoints in the server endpoint tree (root -> descendants).
+ *
+ * @param {Endpoint} root  Root endpoint (typically the ServerNode root endpoint cast as Endpoint).
+ * @returns {Endpoint[]}   Flat array including the root and every descendant once.
+ */
+function collectAllEndpoints(root) {
+    const list = [];
+    const walk = (ep) => {
+        list.push(ep);
+        for (const child of ep.parts) {
+            walk(child);
+        }
+    };
+    walk(root);
+    return list;
+}
+/**
+ * Assert that every endpoint attached to the server has an assigned and (batch-)persisted endpoint number.
+ *
+ * This waits for any outstanding number persistence batch (endpointStores.close()), then traverses the endpoint
+ * graph and asserts:
+ *  - Root endpoint: number is 0 (allowing undefined to coerce to 0 via nullish coalescing check).
+ *  - All other endpoints: number > 0.
+ *
+ * @param {ServerNode} targetServer The server whose endpoint numbers are verified.
+ * @returns {Promise<void>}         Resolves when assertions complete.
+ */
+export async function assertAllEndpointNumbersPersisted(targetServer) {
+    const nodeStore = targetServer.env.get(ServerNodeStore);
+    // Ensure any pending persistence finished (flush any in-flight batch promise)
+    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); // root
+        }
+        else {
+            expect(store.number).toBeGreaterThan(0);
+        }
+    }
+    return all.length;
+}
+/**
+ * Close the server node stores to flush any pending endpoint number persistence.
+ *
+ * @param {ServerNode} targetServer The server whose endpoint stores should be closed.
+ * @returns {Promise<void>} Resolves when the stores have been closed.
+ */
+export async function closeServerNodeStores(targetServer) {
+    const resolvedTargetServer = targetServer ?? server;
+    await resolvedTargetServer?.env.get(ServerNodeStore)?.endpointStores.close();
+}
+/**
+ * Create a matter server node for testing.
+ *
+ * @param {number} port TCP port to listen on.
+ * @param {DeviceTypeId} deviceType Device type identifier for the server node. Defaults to the bridge device type.
+ * @param {number} ticks Number of macrotask (setImmediate) turns to yield after starting the server to allow asynchronous work to complete before returning (default 1).
+ * @param {number} microTurns Number of microtask drains (Promise.resolve chains) to perform after macrotask yielding to allow asynchronous work to complete before returning (default 1).
+ * @param {number} pause Final timer delay in ms to wait after microtask draining to allow any follow-up work scheduled by the server start process to run before returning (default 10ms).
+ * @returns {Promise<[ServerNode<ServerNode.RootEndpoint>, Endpoint<AggregatorEndpoint>]>} Resolves to an array containing the created ServerNode and its AggregatorNode.
+ * @example
+ * ```typescript
+ * const NAME = 'BaseTest';
+ * const MATTER_PORT = 8000;
+ * const MATTER_CREATE_ONLY = true;
+ *
+ * // Setup the test environment
+ * await setupTest(NAME, false);
+ *
+ * // Setup the Matter test environment
+ * await createTestEnvironment();
+ *
+ * // Create the server node and aggregator
+ * await createServerNode(MATTER_PORT);
+ *
+ * // Start the server node if not in create-only mode
+ * if (!MATTER_CREATE_ONLY) await startServerNode();
+ *
+ * // Stop or flush the server node depending on the create-only mode
+ * if (MATTER_CREATE_ONLY) await flushServerNode();
+ * else await stopServerNode();
+ *
+ * // Destroy the Matter test environment
+ * await destroyTestEnvironment();
+ * ```
+ */
+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');
+    // Create the server node
+    server = await ServerNode.create({
+        id: NAME + 'ServerNode',
+        // Provide the environment
+        environment,
+        // Provide Node announcement settings
+        productDescription: {
+            name: NAME + 'ServerNode',
+            deviceType: DeviceTypeId(deviceType),
+            vendorId: VendorId(0xfff1),
+            productId: 0x8000,
+        },
+        // Provide defaults for the BasicInformation cluster on the Root endpoint
+        basicInformation: {
+            vendorId: VendorId(0xfff1),
+            vendorName: 'Matterbridge',
+            productId: 0x8000,
+            productName: ('Matterbridge ' + NAME).slice(0, 32), // truncate to 32 chars to satisfy BasicInformation cluster constraints
+            productLabel: ('Label ' + NAME).slice(0, 64), // truncate to 64 chars to satisfy BasicInformation cluster constraints
+            nodeLabel: (NAME + 'ServerNode').slice(0, 32), // truncate to 32 chars to satisfy BasicInformation cluster constraints
+            hardwareVersion: 1,
+            softwareVersion: 1,
+            productUrl: 'https://matterbridge.io',
+            configurationVersion: 1,
+            reachable: true,
+            serialNumber: 'SN' + random,
+            uniqueId: 'UI' + random,
+        },
+        // Provide Network relevant configuration like the port
+        network: {
+            listeningAddressIpv4: undefined,
+            listeningAddressIpv6: undefined,
+            port,
+            tcp: true,
+            transportPreference: 'udp',
+        },
+        // Provide the certificate for the device
+        operationalCredentials: {
+            certification: undefined,
+        },
+    });
+    expect(server).toBeDefined();
+    expect(server.lifecycle.isReady).toBeTruthy();
+    // Create the aggregator node
+    aggregator = new Endpoint(AggregatorEndpoint, {
+        id: NAME + 'AggregatorNode',
+    });
+    expect(aggregator).toBeDefined();
+    // Add the aggregator to the server
+    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();
+    // Ensure the queue is empty and pause 100ms to allow any pending work to complete before returning the server and aggregator
+    await flushAsync(ticks, microTurns, pause);
+    return [server, aggregator];
+}
+/**
+ * Start a matter server node for testing.
+ *
+ * @param {number} ticks Number of macrotask (setImmediate) turns to yield after starting the server to allow asynchronous work to complete before returning (default 1).
+ * @param {number} microTurns Number of microtask drains (Promise.resolve chains) to perform after macrotask yielding to allow asynchronous work to complete before returning (default 1).
+ * @param {number} pause Final timer delay in ms to wait after microtask draining to allow any follow-up work scheduled by the server start process to run before returning (default 10ms).
+ * @returns {Promise<[ServerNode<ServerNode.RootEndpoint>, Endpoint<AggregatorEndpoint>]>} Resolves to an array containing the created ServerNode and its AggregatorNode.
+ * @example
+ * ```typescript
+ * const NAME = 'BaseTest';
+ * const MATTER_PORT = 8000;
+ * const MATTER_CREATE_ONLY = true;
+ *
+ * // Setup the test environment
+ * await setupTest(NAME, false);
+ *
+ * // Setup the Matter test environment
+ * await createTestEnvironment();
+ *
+ * // Create the server node and aggregator
+ * await createServerNode(MATTER_PORT);
+ *
+ * // Start the server node if not in create-only mode
+ * if (!MATTER_CREATE_ONLY) await startServerNode();
+ *
+ * // Stop or flush the server node depending on the create-only mode
+ * if (MATTER_CREATE_ONLY) await flushServerNode();
+ * else await stopServerNode();
+ *
+ * // Destroy the Matter test environment
+ * await destroyTestEnvironment();
+ * ```
+ */
+export async function startServerNode(ticks = 1, microTurns = 1, pause = 10) {
+    // Create the server node
+    if (!server || !aggregator) {
+        /* v8 ignore next */
+        throw new Error('Server node and aggregator must be created before starting the server. Call createServerNode() first.');
+    }
+    // Wait for the server to be online
+    await new Promise((resolve, reject) => {
+        server.lifecycle.online.on(() => {
+            resolve();
+        });
+        server.start().catch((err) => reject(err));
+    });
+    // Check if the server is online
+    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();
+    // Ensure the queue is empty
+    await flushAsync(ticks, microTurns, pause);
+    return [server, aggregator];
+}
+/**
+ * Stop a matter server node.
+ *
+ * @param {number} ticks Number of macrotask (setImmediate) turns to yield after stopping the server to allow asynchronous work to complete before returning (default 1).
+ * @param {number} microTurns Number of microtask drains (Promise.resolve chains) to perform after macrotask yielding to allow asynchronous work to complete before returning (default 1).
+ * @param {number} pause Final timer delay in ms to wait after microtask draining to allow any follow-up work scheduled by the server stop process to run before returning (default 10ms).
+ * @returns {Promise<void>} Resolves when the server has stopped.
+ * @example
+ * ```typescript
+ * const NAME = 'BaseTest';
+ * const MATTER_PORT = 8000;
+ * const MATTER_CREATE_ONLY = true;
+ *
+ * // Setup the test environment
+ * await setupTest(NAME, false);
+ *
+ * // Setup the Matter test environment
+ * await createTestEnvironment();
+ *
+ * // Create the server node and aggregator
+ * await createServerNode(MATTER_PORT);
+ *
+ * // Start the server node if not in create-only mode
+ * if (!MATTER_CREATE_ONLY) await startServerNode();
+ *
+ * // Stop or flush the server node depending on the create-only mode
+ * if (MATTER_CREATE_ONLY) await flushServerNode();
+ * else await stopServerNode();
+ *
+ * // Destroy the Matter test environment
+ * await destroyTestEnvironment();
+ * ```
+ */
+export async function stopServerNode(ticks = 1, microTurns = 1, pause = 10) {
+    // Flush any pending endpoint number persistence
+    await flushAllEndpointNumberPersistence(server);
+    // Ensure all endpoint numbers are persisted
+    await assertAllEndpointNumbersPersisted(server);
+    // Stop the server
+    expect(server).toBeDefined();
+    expect(server.lifecycle.isReady).toBeTruthy();
+    expect(server.lifecycle.isOnline).toBeTruthy();
+    // Close the server to release UDP sockets and other network resources created
+    // by ServerNode.create() (mDNS udp4/udp6 sockets), which would otherwise keep
+    // the Jest process alive indefinitely after all tests finish.
+    await server.close();
+    expect(server.lifecycle.isReady).toBeFalsy();
+    expect(server.lifecycle.isOnline).toBeFalsy();
+    // Ensure the queue is empty
+    await flushAsync(ticks, microTurns, pause);
+}
+/**
+ * Flush any pending endpoint number persistence.
+ *
+ * @param {number} ticks Number of macrotask (setImmediate) turns to yield after stopping the server to allow asynchronous work to complete before returning (default 1).
+ * @param {number} microTurns Number of microtask drains (Promise.resolve chains) to perform after macrotask yielding to allow asynchronous work to complete before returning (default 1).
+ * @param {number} pause Final timer delay in ms to wait after microtask draining to allow any follow-up work scheduled by the server stop process to run before returning (default 10ms).
+ * @returns {Promise<void>} Resolves when the server has stopped.
+ * @example
+ * ```typescript
+ * const NAME = 'BaseTest';
+ * const MATTER_PORT = 8000;
+ * const MATTER_CREATE_ONLY = true;
+ *
+ * // Setup the test environment
+ * await setupTest(NAME, false);
+ *
+ * // Setup the Matter test environment
+ * await createTestEnvironment();
+ *
+ * // Create the server node and aggregator
+ * await createServerNode(MATTER_PORT);
+ *
+ * // Start the server node if not in create-only mode
+ * if (!MATTER_CREATE_ONLY) await startServerNode();
+ *
+ * // Stop or flush the server node depending on the create-only mode
+ * if (MATTER_CREATE_ONLY) await flushServerNode();
+ * else await stopServerNode();
+ *
+ * // Destroy the Matter test environment
+ * await destroyTestEnvironment();
+ * ```
+ */
+export async function flushServerNode(ticks = 1, microTurns = 1, pause = 10) {
+    // Flush any pending endpoint number persistence
+    await flushAllEndpointNumberPersistence(server);
+    // Ensure all endpoint numbers are persisted
+    await assertAllEndpointNumbersPersisted(server);
+    // Stop the server
+    expect(server).toBeDefined();
+    expect(server.lifecycle.isReady).toBeTruthy();
+    expect(server.lifecycle.isOnline).toBeFalsy();
+    // Close the server to release UDP sockets and other network resources created
+    // by ServerNode.create() (mDNS udp4/udp6 sockets), which would otherwise keep
+    // the Jest process alive indefinitely after all tests finish.
+    await server.close();
+    expect(server.lifecycle.isReady).toBeFalsy();
+    expect(server.lifecycle.isOnline).toBeFalsy();
+    // Ensure the queue is empty
+    await flushAsync(ticks, microTurns, pause);
+}
+/**
+ * Add a device (endpoint) to a matter server node or an aggregator.
+ *
+ * @param {ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>} owner The server or aggregator to add the device to.
+ * @param {Endpoint} device The device to add.
+ * @param {number} rounds The number of rounds to perform after addition (default 3).
+ * @param {number} pause The pause time in milliseconds after addition (default 10ms).
+ * @returns {Promise<void>} Resolves when the device has been added and is ready.
+ * @example
+ * ```typescript
+ * expect(await addDevice(aggregator, device)).toBeTruthy();
+ * ```
+ */
+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);
+    /* v8 ignore next */
+    try {
+        await owner.add(device);
+    }
+    catch (error) {
+        inspectError(log, `Error adding device ${device.maybeId}.${device.maybeNumber}`, error);
+        process.stderr.write(`${er}Error adding device ${device.maybeId}.${device.maybeNumber}${rs}\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;
+}
+/**
+ * Delete a device (endpoint) from a matter server node or an aggregator.
+ *
+ * @param {ServerNode<ServerNode.RootEndpoint> | Endpoint<AggregatorEndpoint>} owner The server or aggregator to remove the device from.
+ * @param {Endpoint} device The device to remove.
+ * @param {number} rounds The number of rounds to perform after deletion (default 3).
+ * @param {number} pause The pause time in milliseconds after deletion (default 10ms).
+ * @returns {Promise<void>} Resolves when the device has been removed and is no longer ready.
+ * @example
+ * ```typescript
+ * expect(await deleteDevice(aggregator, device)).toBeTruthy();
+ * ```
+ */
+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);
+    /* v8 ignore next */
+    try {
+        await device.delete();
+    }
+    catch (error) {
+        inspectError(log, `Error deleting device ${device.maybeId}.${device.maybeNumber}`, error);
+        process.stderr.write(`${er}Error deleting device ${device.maybeId}.${device.maybeNumber}${rs}\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;
+}
+//# sourceMappingURL=matterTest.js.map