{"id":15355,"library":"matterbridge-test","title":"Matterbridge Test Plugin","description":"The `matterbridge-test` package serves as a development and demonstration plugin within the `Matterbridge` ecosystem, a platform designed to bridge various smart home protocols like Matter and Homebridge for unified IoT device control. As of April 2026, its current stable version is 2.0.15. The package exhibits an active release cadence, with frequent patch updates primarily focused on dependency management, internal tooling improvements, and developer experience enhancements. It is not intended for direct end-user functionality but rather provides a reference implementation or testing ground for plugin development within the Matterbridge framework, ensuring compatibility and illustrating integration patterns. A key differentiator is its role in validating the Matterbridge plugin API and its strong adherence to modern TypeScript practices, as evidenced by its included type definitions and strict Node.js engine requirements, facilitating type-safe development for other Matterbridge plugin authors.","status":"active","version":"2.0.15","language":"javascript","source_language":"en","source_url":"https://github.com/Luligu/matterbridge-test","tags":["javascript","matterbridge","homebridge","matter","matter.js","matterprotocol","iot","smarthome","connectedthings","typescript"],"install":[{"cmd":"npm install matterbridge-test","lang":"bash","label":"npm"},{"cmd":"yarn add matterbridge-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add matterbridge-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency likely for automation tasks or part of the build/release process within the Matterbridge ecosystem.","package":"automator","optional":false},{"reason":"Used for persistent storage of plugin-specific data or configuration.","package":"node-persist-manager","optional":false},{"reason":"Provides structured and colored console logging capabilities.","package":"node-ansi-logger","optional":false}],"imports":[{"note":"The package ships with TypeScript types and is primarily used with ESM imports.","wrong":"const TestPlugin = require('matterbridge-test').TestPlugin;","symbol":"TestPlugin","correct":"import { TestPlugin } from 'matterbridge-test';"},{"note":"Imports the TypeScript interface for plugin configuration options.","wrong":"import { type TestPluginOptions } from 'matterbridge-test/dist/plugin';","symbol":"TestPluginOptions","correct":"import { TestPluginOptions } from 'matterbridge-test';"}],"quickstart":{"code":"import { Matterbridge } from 'matterbridge'; // Assuming 'matterbridge' is the core framework\nimport { TestPlugin, TestPluginOptions } from 'matterbridge-test';\n\nasync function main() {\n  // Initialize Matterbridge core (hypothetical instance)\n  // In a real scenario, configuration might be loaded from a file or environment.\n  const matterbridge = new Matterbridge({\n    logLevel: 'debug' // Example Matterbridge core configuration\n  });\n\n  // Define configuration for the TestPlugin. This structure is defined by TestPluginOptions.\n  const pluginConfig: TestPluginOptions = {\n    name: \"MyTestPluginInstance\",\n    testSetting: \"exampleValue\", // Placeholder for a setting specific to TestPlugin\n    // Add other settings as required by TestPluginOptions\n  };\n\n  // Register the TestPlugin with the Matterbridge instance.\n  // The exact registration API might vary based on the 'matterbridge' framework version.\n  console.log(`Registering TestPlugin with config:`, pluginConfig);\n  matterbridge.registerPlugin(TestPlugin, pluginConfig);\n\n  // Start the Matterbridge instance, which will initialize and run the registered plugin(s).\n  await matterbridge.start();\n  console.log(\"Matterbridge started successfully with Matterbridge Test Plugin.\");\n\n  // For a test or demonstration plugin, you might set up a timeout to gracefully shut down\n  // or perform specific test actions.\n  setTimeout(async () => {\n    console.log(\"Simulating graceful shutdown after 30 seconds...\");\n    await matterbridge.stop();\n    console.log(\"Matterbridge stopped.\");\n    process.exit(0);\n  }, 30000); // Stop after 30 seconds for demonstration\n}\n\nmain().catch(err => {\n  console.error(\"An error occurred during Matterbridge operation:\", err);\n  process.exit(1);\n});","lang":"typescript","description":"Demonstrates how to register and initialize the `Matterbridge Test Plugin` within a hypothetical `Matterbridge` instance, including basic configuration, and simulates a graceful shutdown."},"warnings":[{"fix":"Ensure your Node.js environment strictly matches one of the specified versions: `>=20.19.0 <21.0.0`, `>=22.13.0 <23.0.0`, or `>=24.0.0 <25.0.0`. Use a version manager like `nvm` or `fnm` to easily switch versions.","message":"The package has very strict Node.js engine compatibility requirements, specifying narrow ranges for versions 20, 22, and 24. Running with an unsupported Node.js version will prevent the package from loading or functioning correctly.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Regularly review the `matterbridge` and `matterbridge-test` changelogs when upgrading to detect any subtle behavioral changes. Test your plugin integrations thoroughly after updates.","message":"While the changelog primarily details internal dependency updates and developer environment enhancements, there are no explicit breaking change notices for consumers of the `matterbridge-test` plugin's API in recent versions. Users should monitor for potential indirect breaking changes if Matterbridge's core plugin API evolves rapidly, especially considering the frequent major version bumps in underlying dependencies like `eslint` and `typescript`.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Upgrade or downgrade your Node.js environment to a compatible version (e.g., `>=20.19.0 <21.0.0`) using a Node.js version manager like `nvm` (`nvm install X.X.X && nvm use X.X.X`).","cause":"The installed Node.js version does not satisfy the `engines` requirement specified in `package.json`.","error":"Error: The package 'matterbridge-test' requires Node.js version X.X.X. Your current Node.js version is Y.Y.Y."},{"fix":"Refer to the official `Matterbridge` documentation for the correct way to instantiate the `Matterbridge` core and register plugins. Ensure all necessary setup steps are completed before attempting to register your plugin.","cause":"The `registerPlugin` method or the `matterbridge` instance itself is not correctly initialized or configured according to the `Matterbridge` framework's API.","error":"TypeError: matterbridge.registerPlugin is not a function"},{"fix":"Ensure your project is configured for ECMAScript Modules (ESM) by adding `\"type\": \"module\"` to your `package.json` and use `import` statements (e.g., `import { TestPlugin } from 'matterbridge-test';`).","cause":"Attempting to use CommonJS `require()` syntax with `matterbridge-test`, which is likely an ESM-only module, or trying to access an unexported subpath.","error":"ERR_PACKAGE_PATH_NOT_EXPORTED (or similar CommonJS `require()` error)"}],"ecosystem":"npm"}