Add test-utils package

Author: Luligu

README-DEV.md

@@ -191,6 +191,26 @@ Matterbridge exports from:
 
 - Vitest Matter test helpers.
 
+**"matterbridge/test-utils"**
+
+- Common test utilities shared by all test runners.
+
+**"matterbridge/test-utils/matter"**
+
+- Common Matter test helpers shared by all test runners.
+
+**"matterbridge/test-utils/jest"**
+
+- Jest-specific test utilities and Matter test helpers.
+
+**"matterbridge/test-utils/vitest"**
+
+- Vitest-specific test utilities and Matter test helpers.
+
+**"matterbridge/test-utils/buntest"**
+
+- Bun test-specific utilities and Matter test helpers.
+
 **"matterbridge/matter"**
 
 - All relevant matter.js exports.

README.md

@@ -784,6 +784,7 @@ Matterbridge is published as an npm **monorepo**. The package you install, `matt
 | `packages/types`        | `@matterbridge/types`        | Shared TypeScript types and constants.                                                                                        |
 | `packages/jest-utils`   | `@matterbridge/jest-utils`   | Jest test-environment setup helpers.                                                                                          |
 | `packages/vitest-utils` | `@matterbridge/vitest-utils` | Vitest test-environment setup helpers.                                                                                        |
+| `packages/test-utils`   | `@matterbridge/test-utils`   | Common test helpers with Matter, Jest, Vitest and Bun test-specific exports.                                                  |
 
 ## Imports graph
 
@@ -798,9 +799,11 @@ graph TD
   utils["@matterbridge/utils"]
   types["@matterbridge/types"]
   vitestutils["@matterbridge/vitest-utils"]
+  testutils["@matterbridge/test-utils"]
 
   matterbridge --> core
   matterbridge --> vitestutils
+  matterbridge --> testutils
 
   core --> thread
   core --> dgram
@@ -812,13 +815,15 @@ graph TD
   dgram --> utils
   vitestutils --> utils
   vitestutils --> types
+  testutils --> utils
+  testutils --> types
 ```
 
 The graph is acyclic and layered:
 
 - **Foundation (no internal dependencies):** `@matterbridge/types`, `@matterbridge/utils`.
 - **Networking & workers:** `@matterbridge/dgram` (→ `utils`), `@matterbridge/thread` (→ `utils`, `types`).
-- **Test helpers:** `@matterbridge/jest-utils` and `@matterbridge/vitest-utils` (→ `utils`, `types`).
+- **Test helpers:** `@matterbridge/jest-utils`, `@matterbridge/vitest-utils` and `@matterbridge/test-utils` (→ `utils`, `types`).
 - **Core:** `@matterbridge/core` (→ `dgram`, `thread`, `utils`, `types`).
 - **Top level:** `matterbridge` declares all scoped packages as direct dependencies; `core` pulls in the rest transitively.
 

docs/README-DEV.html

@@ -353,6 +353,26 @@ <h2 id="guidelines-on-importsexports">Guidelines on imports/exports</h2>
 <ul>
 <li>Vitest Matter test helpers.</li>
 </ul>
+<p><strong>&quot;matterbridge/test-utils&quot;</strong></p>
+<ul>
+<li>Common test utilities shared by all test runners.</li>
+</ul>
+<p><strong>&quot;matterbridge/test-utils/matter&quot;</strong></p>
+<ul>
+<li>Common Matter test helpers shared by all test runners.</li>
+</ul>
+<p><strong>&quot;matterbridge/test-utils/jest&quot;</strong></p>
+<ul>
+<li>Jest-specific test utilities and Matter test helpers.</li>
+</ul>
+<p><strong>&quot;matterbridge/test-utils/vitest&quot;</strong></p>
+<ul>
+<li>Vitest-specific test utilities and Matter test helpers.</li>
+</ul>
+<p><strong>&quot;matterbridge/test-utils/buntest&quot;</strong></p>
+<ul>
+<li>Bun test-specific utilities and Matter test helpers.</li>
+</ul>
 <p><strong>&quot;matterbridge/matter&quot;</strong></p>
 <ul>
 <li>All relevant matter.js exports.</li>

docs/README.html

@@ -628,6 +628,11 @@ <h1 id="package-structure">Package structure</h1>
 <td><code>@matterbridge/vitest-utils</code></td>
 <td>Vitest test-environment setup helpers.</td>
 </tr>
+<tr>
+<td><code>packages/test-utils</code></td>
+<td><code>@matterbridge/test-utils</code></td>
+<td>Common test helpers with Matter, Jest, Vitest and Bun test-specific exports.</td>
+</tr>
 </tbody></table>
 <h2 id="imports-graph">Imports graph</h2>
 <p>Runtime dependencies between the published packages.</p>
@@ -639,9 +644,11 @@ <h2 id="imports-graph">Imports graph</h2>
   utils[&quot;@matterbridge/utils&quot;]
   types[&quot;@matterbridge/types&quot;]
   vitestutils[&quot;@matterbridge/vitest-utils&quot;]
+  testutils[&quot;@matterbridge/test-utils&quot;]
 
   matterbridge --&gt; core
   matterbridge --&gt; vitestutils
+  matterbridge --&gt; testutils
 
   core --&gt; thread
   core --&gt; dgram
@@ -653,12 +660,14 @@ <h2 id="imports-graph">Imports graph</h2>
   dgram --&gt; utils
   vitestutils --&gt; utils
   vitestutils --&gt; types
+  testutils --&gt; utils
+  testutils --&gt; types
 </code></pre>
 <p>The graph is acyclic and layered:</p>
 <ul>
 <li><strong>Foundation (no internal dependencies):</strong> <code>@matterbridge/types</code>, <code>@matterbridge/utils</code>.</li>
 <li><strong>Networking &amp; workers:</strong> <code>@matterbridge/dgram</code> (→ <code>utils</code>), <code>@matterbridge/thread</code> (→ <code>utils</code>, <code>types</code>).</li>
-<li><strong>Test helpers:</strong> <code>@matterbridge/jest-utils</code> and <code>@matterbridge/vitest-utils</code> (→ <code>utils</code>, <code>types</code>).</li>
+<li><strong>Test helpers:</strong> <code>@matterbridge/jest-utils</code>, <code>@matterbridge/vitest-utils</code> and <code>@matterbridge/test-utils</code> (→ <code>utils</code>, <code>types</code>).</li>
 <li><strong>Core:</strong> <code>@matterbridge/core</code> (→ <code>dgram</code>, <code>thread</code>, <code>utils</code>, <code>types</code>).</li>
 <li><strong>Top level:</strong> <code>matterbridge</code> declares all scoped packages as direct dependencies; <code>core</code> pulls in the rest transitively.</li>
 </ul>

package-lock.json

@@ -60,6 +60,7 @@
     "packages/types",
     "packages/jest-utils",
     "packages/vitest-utils",
+    "packages/test-utils",
     "packages/utils",
     "packages/dgram",
     "packages/thread",
@@ -106,6 +107,26 @@
       "import": "./dist/vitest-utils/matter.js",
       "types": "./dist/vitest-utils/matter.d.ts"
     },
+    "./test-utils": {
+      "import": "./dist/test-utils/export.js",
+      "types": "./dist/test-utils/export.d.ts"
+    },
+    "./test-utils/matter": {
+      "import": "./dist/test-utils/matter/export.js",
+      "types": "./dist/test-utils/matter/export.d.ts"
+    },
+    "./test-utils/jest": {
+      "import": "./dist/test-utils/jest/export.js",
+      "types": "./dist/test-utils/jest/export.d.ts"
+    },
+    "./test-utils/vitest": {
+      "import": "./dist/test-utils/vitest/export.js",
+      "types": "./dist/test-utils/vitest/export.d.ts"
+    },
+    "./test-utils/buntest": {
+      "import": "./dist/test-utils/buntest/export.js",
+      "types": "./dist/test-utils/buntest/export.d.ts"
+    },
     "./logger": {
       "import": "./dist/logger/export.js",
       "types": "./dist/logger/export.d.ts"
@@ -401,6 +422,7 @@
     "@matterbridge/core": "3.10.7",
     "@matterbridge/dgram": "3.10.7",
     "@matterbridge/jest-utils": "3.10.7",
+    "@matterbridge/test-utils": "3.10.7",
     "@matterbridge/thread": "3.10.7",
     "@matterbridge/types": "3.10.7",
     "@matterbridge/utils": "3.10.7",
@@ -409,6 +431,7 @@
     "node-persist-manager": "2.1.0"
   },
   "devDependencies": {
+    "@matter/main": "0.17.9",
     "@types/bun": "1.4.0",
     "@types/node": "26.2.0",
     "@vitest/coverage-v8": "4.1.11",

package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@matterbridge/test-utils",
+  "version": "3.10.7",
+  "description": "Matterbridge common and framework-specific test utilities",
+  "author": "https://github.com/Luligu",
+  "homepage": "https://matterbridge.io/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Luligu/matterbridge.git",
+    "directory": "packages/test-utils"
+  },
+  "bugs": {
+    "url": "https://github.com/Luligu/matterbridge/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "matterbridge",
+    "homebridge",
+    "bridge",
+    "plugin",
+    "frontend",
+    "matter.js",
+    "matter-node.js",
+    "matter",
+    "matterprotocol",
+    "iot",
+    "smarthome",
+    "connectedthings",
+    "hap",
+    "homekit",
+    "siri",
+    "google-home",
+    "alexa",
+    "homeassistant",
+    "smartthings",
+    "ewelink"
+  ],
+  "license": "Apache-2.0",
+  "funding": {
+    "type": "buymeacoffee",
+    "url": "https://www.buymeacoffee.com/luligugithub"
+  },
+  "type": "module",
+  "main": "./dist/export.js",
+  "types": "./dist/export.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/export.d.ts",
+      "import": "./dist/export.js"
+    },
+    "./matter": {
+      "types": "./dist/matter/export.d.ts",
+      "import": "./dist/matter/export.js"
+    },
+    "./jest": {
+      "types": "./dist/jest/export.d.ts",
+      "import": "./dist/jest/export.js"
+    },
+    "./vitest": {
+      "types": "./dist/vitest/export.d.ts",
+      "import": "./dist/vitest/export.js"
+    },
+    "./buntest": {
+      "types": "./dist/buntest/export.d.ts",
+      "import": "./dist/buntest/export.js"
+    }
+  },
+  "engines": {
+    "node": ">=20.19.0 <21.0.0 || >=22.13.0 <23.0.0 || >=24.0.0 <25.0.0 || >=26.0.0 <27.0.0"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "npm-shrinkwrap.json",
+    "CHANGELOG.md"
+  ],
+  "automator": {
+    "node": true,
+    "vitestTypes": true,
+    "skipPackageJson": true,
+    "skipTsconfig": true
+  },
+  "dependencies": {
+    "@matter/main": "0.17.9",
+    "@matterbridge/types": "3.10.7",
+    "@matterbridge/utils": "3.10.7",
+    "node-ansi-logger": "3.3.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "@types/jest": "30.0.0",
+    "@types/node": "26.2.0",
+    "vitest": "4.1.11"
+  }
+}

packages/test-utils/package.json

@@ -0,0 +1,27 @@
+/**
+ * @file packages/test-utils/src/buntest.ts
+ * @description Re-export the Bun test utility API used in the repo's buntest directory.
+ * @author Luca Liguori
+ * @created 2026-08-23
+ * @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 oxc/no-barrel-file */
+
+export * from './matterTest.js';
+export * from './setupTest.js';