@bsb/tests 0.0.1

package/README.md

@@ -0,0 +1,7 @@
+# BSB Node.js Tests
+
+Shared test suites for BSB core and Node.js plugins.
+
+## Docs
+
+See `tests/nodejs/docs/index.md` for configuration, custom tests, and runner behavior.

package/bin/bsb-tests.cjs

@@ -0,0 +1,376 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const argv = process.argv.slice(2);
+
+const getArg = (name) => {
+  const idx = argv.indexOf(name);
+  if (idx === -1) return null;
+  return argv[idx + 1] || null;
+};
+
+const hasFlag = (name) => argv.includes(name);
+
+const cwd = path.resolve(getArg("--cwd") || process.cwd());
+const pluginFilter = getArg("--plugin");
+const forceTs = hasFlag("--ts");
+const forceJs = hasFlag("--js");
+const enableCoverage = !hasFlag("--no-coverage");
+
+const ignoreDirs = new Set([
+  "node_modules",
+  ".git",
+  "lib",
+  "dist",
+  ".bsb",
+  ".npm-cache",
+  ".claude",
+]);
+
+const findFiles = (dir, filename, results = []) => {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (ignoreDirs.has(entry.name)) continue;
+      findFiles(path.join(dir, entry.name), filename, results);
+      continue;
+    }
+    if (entry.isFile() && entry.name === filename) {
+      results.push(path.join(dir, entry.name));
+    }
+  }
+  return results;
+};
+
+const readJson = (filePath) => JSON.parse(fs.readFileSync(filePath, "utf8"));
+
+const resolvePluginModule = (pluginRoot, pluginPath, useTs) => {
+  const base = path.resolve(pluginRoot, pluginPath || "");
+  if (useTs) {
+    return path.join(base, "index.ts");
+  }
+  const directJs = path.join(base, "index.js");
+  if (fs.existsSync(directJs)) return directJs;
+  const swapped = base.includes(`${path.sep}src${path.sep}`)
+    ? base.replace(`${path.sep}src${path.sep}`, `${path.sep}lib${path.sep}`)
+    : base.replace(`${path.sep}src`, `${path.sep}lib`);
+  return path.join(swapped, "index.js");
+};
+
+const resolveLocalBaseEntry = (repoRoot, useTs) => {
+  const baseRoot = path.join(repoRoot, "nodejs");
+  const entryTs = path.join(baseRoot, "src", "index.ts");
+  const entryJs = path.join(baseRoot, "lib", "index.js");
+  if (useTs && fs.existsSync(entryTs)) return entryTs;
+  if (!useTs && fs.existsSync(entryJs)) return entryJs;
+  return fs.existsSync(entryTs) ? entryTs : entryJs;
+};
+
+const loadTestsManifest = (manifestDir) => {
+  const configPath = path.join(manifestDir, "bsb-tests.json");
+  if (!fs.existsSync(configPath)) return null;
+  return readJson(configPath);
+};
+
+const mergeConfig = (baseConfig, overrideConfig) => {
+  return {
+    ...(baseConfig || {}),
+    ...(overrideConfig || {}),
+  };
+};
+
+const normalizeSetup = (setupValue) => {
+  if (!setupValue) return null;
+  if (typeof setupValue === "string") {
+    return { beforeAll: setupValue, afterAll: null };
+  }
+  if (typeof setupValue === "object") {
+    return {
+      beforeAll: setupValue.beforeAll || null,
+      afterAll: setupValue.afterAll || null,
+    };
+  }
+  return null;
+};
+
+const normalizeDispose = (disposeValue) => {
+  if (!disposeValue) return null;
+  if (typeof disposeValue === "string") {
+    return { afterAll: disposeValue };
+  }
+  if (typeof disposeValue === "object") {
+    return {
+      afterAll: disposeValue.afterAll || null,
+    };
+  }
+  return null;
+};
+
+const manifests = findFiles(cwd, "bsb-plugin.json");
+
+if (manifests.length === 0) {
+  console.error("No bsb-plugin.json files found in", cwd);
+  process.exit(2);
+}
+
+const plugins = [];
+for (const manifestPath of manifests) {
+  const manifestDir = path.dirname(manifestPath);
+  const manifest = readJson(manifestPath);
+  const testsManifest = loadTestsManifest(manifestDir);
+  const testsById = new Map();
+  if (testsManifest && Array.isArray(testsManifest.nodejs)) {
+    for (const entry of testsManifest.nodejs) {
+      if (entry && entry.id) {
+        testsById.set(entry.id, entry);
+      }
+    }
+  }
+  for (const platform of Object.keys(manifest)) {
+    const items = Array.isArray(manifest[platform]) ? manifest[platform] : [];
+    for (const plugin of items) {
+      if (!plugin || !plugin.id) continue;
+      const pluginRoot = path.resolve(manifestDir, plugin.basePath || ".");
+      const testsEntry = testsById.get(plugin.id) || null;
+      plugins.push({
+        platform,
+        id: plugin.id,
+        name: plugin.name || plugin.id,
+        pluginPath: plugin.pluginPath,
+        pluginRoot,
+        testsEntry,
+      });
+    }
+  }
+}
+
+const filtered = pluginFilter
+  ? plugins.filter((p) => p.id === pluginFilter || p.name === pluginFilter || p.pluginRoot.endsWith(pluginFilter))
+  : plugins;
+
+if (filtered.length === 0) {
+  console.error("No plugins matched filter:", pluginFilter);
+  process.exit(2);
+}
+
+const repoRoot = cwd;
+const mochaBin = require.resolve("mocha/bin/mocha.mjs");
+const nycBin = require.resolve("nyc/bin/nyc.js");
+const tsNodeRegister = require.resolve("ts-node/register");
+const setupHook = path.join(__dirname, "..", "src", "runner", "setup.ts");
+const pluginEventsRunner = path.join(__dirname, "..", "src", "runner", "plugin-events.ts");
+const pluginObservableRunner = path.join(__dirname, "..", "src", "runner", "plugin-observable.ts");
+const pluginCustomRunner = path.join(__dirname, "..", "src", "runner", "plugin-custom.ts");
+const eventsDefaultSpec = path.join(__dirname, "..", "src", "plugins", "events-default", "index.ts");
+const loggingDefaultSpec = path.join(__dirname, "..", "src", "plugins", "logging-default", "index.ts");
+const configDefaultSpec = path.join(__dirname, "..", "src", "plugins", "config-default", "index.ts");
+const observableDefaultSpec = path.join(__dirname, "..", "src", "plugins", "observable-default", "index.ts");
+
+const runMocha = (env, spec, useTs, coverage, coverageInclude) => {
+  const mochaArgs = [];
+  if (useTs) {
+    mochaArgs.push("--require", tsNodeRegister);
+  }
+  mochaArgs.push("--require", setupHook, spec);
+
+  if (!coverage) {
+    const result = spawnSync(process.execPath, [mochaBin, ...mochaArgs], {
+      stdio: "inherit",
+      env,
+    });
+    return result.status || 0;
+  }
+
+  const nycArgs = [
+    "--all",
+    "--check-coverage",
+    "--lines",
+    "100",
+    "--functions",
+    "100",
+    "--branches",
+    "100",
+    "--statements",
+    "100",
+    "--extension",
+    useTs ? ".ts" : ".js",
+    "--reporter",
+    "text",
+    "--reporter",
+    "lcov",
+  ];
+
+  if (coverageInclude && coverageInclude.length) {
+    for (const inc of coverageInclude) {
+      nycArgs.push("--include", inc);
+    }
+  }
+
+  nycArgs.push(mochaBin, ...mochaArgs);
+
+  const result = spawnSync(process.execPath, [nycBin, ...nycArgs], {
+    stdio: "inherit",
+    env,
+  });
+  return result.status || 0;
+};
+
+let exitCode = 0;
+
+for (const plugin of filtered) {
+  if (plugin.testsEntry && plugin.testsEntry.skip === true) {
+    console.warn("Skipping tests for plugin (skipped):", plugin.name);
+    continue;
+  }
+
+  const useTs = forceTs || (!forceJs && fs.existsSync(path.join(plugin.pluginRoot, "src")));
+  const pluginModule = resolvePluginModule(plugin.pluginRoot, plugin.pluginPath, useTs);
+  if (!fs.existsSync(pluginModule)) {
+    console.error("Plugin module not found:", pluginModule);
+    exitCode = 2;
+    continue;
+  }
+
+  const localBaseEntry = resolveLocalBaseEntry(repoRoot, useTs);
+  const testsEntry = plugin.testsEntry || {};
+  const defaultConfig = testsEntry.default?.config || null;
+  const defaultSetup = normalizeSetup(testsEntry.default?.setup || null);
+  const defaultDispose = normalizeDispose(testsEntry.default?.dispose || null);
+  const testCases = Array.isArray(testsEntry.tests) && testsEntry.tests.length > 0
+    ? testsEntry.tests
+    : [ { name: "default", config: null, setup: null, dispose: null } ];
+
+  const coverageInclude = useTs
+    ? [path.join(plugin.pluginRoot, "src", "**", "*.ts")]
+    : [path.join(plugin.pluginRoot, "lib", "**", "*.js")];
+
+  const runSetupScript = (scriptPath, phase) => {
+    if (!scriptPath) return 0;
+    const resolved = path.resolve(plugin.pluginRoot, scriptPath);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Setup script not found (${phase}):`, resolved);
+      return 2;
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    let result;
+    if (ext === ".ts") {
+      result = spawnSync(process.execPath, ["-r", tsNodeRegister, resolved], {
+        stdio: "inherit",
+        env: {
+          ...process.env,
+          BSB_TEST_PLUGIN_NAME: plugin.name,
+          BSB_TEST_PLUGIN_ID: plugin.id,
+        },
+      });
+    } else if (ext === ".js" || ext === ".cjs" || ext === ".mjs") {
+      result = spawnSync(process.execPath, [resolved], {
+        stdio: "inherit",
+        env: {
+          ...process.env,
+          BSB_TEST_PLUGIN_NAME: plugin.name,
+          BSB_TEST_PLUGIN_ID: plugin.id,
+        },
+      });
+    } else {
+      result = spawnSync(resolved, {
+        stdio: "inherit",
+        shell: true,
+        env: {
+          ...process.env,
+          BSB_TEST_PLUGIN_NAME: plugin.name,
+          BSB_TEST_PLUGIN_ID: plugin.id,
+        },
+      });
+    }
+    return result.status || 0;
+  };
+
+  for (const testCase of testCases) {
+    if (testCase && testCase.skip === true) {
+      console.warn("Skipping test case (skipped):", testCase.name || "unnamed");
+      continue;
+    }
+
+    const mergedConfig = mergeConfig(defaultConfig, testCase?.config);
+    const setup = normalizeSetup(testCase?.setup) || defaultSetup;
+    const dispose = normalizeDispose(testCase?.dispose) || defaultDispose;
+    const beforeAll = setup?.beforeAll || null;
+    const afterAll = setup?.afterAll || null;
+
+    const env = {
+      ...process.env,
+      BSB_TEST_PLUGIN_MODULE: pluginModule,
+      BSB_TEST_PLUGIN_NAME: plugin.name,
+      BSB_TEST_PLUGIN_CONFIG: JSON.stringify(mergedConfig || null),
+      BSB_TEST_LOCAL_BASE_ENTRY: localBaseEntry || "",
+      TS_NODE_PROJECT: path.join(__dirname, "..", "tsconfig.json"),
+    };
+
+    if (beforeAll) {
+      const code = runSetupScript(beforeAll, "beforeAll");
+      if (code !== 0) {
+        exitCode = code;
+        continue;
+      }
+    }
+
+    const isEvents = plugin.id.startsWith("events-") || plugin.name.startsWith("events-");
+    if (isEvents) {
+      const code = runMocha(env, pluginEventsRunner, useTs, enableCoverage, coverageInclude);
+      if (code !== 0) exitCode = code;
+    }
+
+    const isObservable = plugin.id.startsWith("observable-") || plugin.name.startsWith("observable-");
+    if (isObservable) {
+      const code = runMocha(env, pluginObservableRunner, useTs, enableCoverage, coverageInclude);
+      if (code !== 0) exitCode = code;
+    }
+
+    if (plugin.id === "events-default") {
+      const code = runMocha(env, eventsDefaultSpec, useTs, enableCoverage, coverageInclude);
+      if (code !== 0) exitCode = code;
+    }
+
+    if (plugin.id === "logging-default") {
+      const code = runMocha(env, loggingDefaultSpec, useTs, enableCoverage, coverageInclude);
+      if (code !== 0) exitCode = code;
+    }
+
+    if (plugin.id === "config-default") {
+      const code = runMocha(env, configDefaultSpec, useTs, enableCoverage, coverageInclude);
+      if (code !== 0) exitCode = code;
+    }
+
+    if (plugin.id === "observable-default") {
+      const code = runMocha(env, observableDefaultSpec, useTs, enableCoverage, coverageInclude);
+      if (code !== 0) exitCode = code;
+    }
+
+    const customEnv = {
+      ...env,
+      BSB_TEST_PLUGIN_ID: plugin.id,
+      BSB_TEST_PLUGIN_ROOT: plugin.pluginRoot,
+    };
+    const customCode = runMocha(customEnv, pluginCustomRunner, useTs, enableCoverage, coverageInclude);
+    if (customCode !== 0) exitCode = customCode;
+
+    if (afterAll) {
+      const code = runSetupScript(afterAll, "afterAll");
+      if (code !== 0) {
+        exitCode = code;
+      }
+    }
+
+    if (dispose?.afterAll) {
+      const code = runSetupScript(dispose.afterAll, "dispose");
+      if (code !== 0) {
+        exitCode = code;
+      }
+    }
+  }
+}
+
+process.exit(exitCode);

package/docs/index.md

@@ -0,0 +1,101 @@
+# @bsb/tests
+
+Shared test runner for BSB plugins.
+
+## Usage
+
+```bash
+npx @bsb/tests
+npx @bsb/tests --plugin events-rabbitmq
+npx @bsb/tests --no-coverage
+```
+
+## bsb-tests.json
+
+Place `bsb-tests.json` next to `bsb-plugin.json`.
+
+Format:
+
+```json
+{
+  "nodejs": [
+    {
+      "id": "events-rabbitmq",
+      "skip": false,
+      "default": {
+        "config": {
+          "endpoints": ["amqp://127.0.0.1:5670"]
+        },
+        "setup": "scripts/test-setup.sh",
+        "dispose": "scripts/test-dispose.sh"
+      },
+      "tests": [
+        {
+          "name": "primary",
+          "skip": false,
+          "config": {
+            "prefetch": 10
+          },
+          "setup": {
+            "beforeAll": "scripts/test-setup.js",
+            "afterAll": "scripts/test-teardown.js"
+          },
+          "dispose": {
+            "afterAll": "scripts/test-dispose.js"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Notes:
+
+- `skip: true` skips plugin tests or specific test cases.
+- `setup` can be a single script path or `{ "beforeAll": "...", "afterAll": "..." }`.
+- `dispose` is an optional cleanup hook (run after tests).
+- If `tests` is empty, the `default` config is used once.
+- Script paths are relative to the plugin root.
+
+## Custom Tests
+
+Add custom tests under `tests/{plugin-id}` in the repo root.
+
+Layout:
+
+```
+tests/
+  events-rabbitmq/
+    _before.ts
+    _after.ts
+    connection.ts
+    streaming/
+      _before.ts
+      _after.ts
+      roundtrip.ts
+```
+
+Rules:
+
+- Each `*.ts/js` file (not starting with `_`) exports a single test function.
+- Files starting with `_` are ignored as tests and can be used for helpers.
+- `_before` and `_after` run before/after all tests in the same folder.
+- If `_before` returns a value, it is passed to each test in that folder.
+
+Test function signature:
+
+```ts
+export default async function test(ctx: any, data?: any) {
+  // ctx: { pluginId, pluginName, pluginRoot, config, group }
+  // data: value returned by _before (optional)
+}
+```
+
+## Built-in Suites
+
+- `events-*` plugins
+- `observable-*` plugins
+- `events-default` additional suite
+- `observable-default` additional suite
+- `config-default`

package/lib/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./trace";
+export * from "./mocks";
+export * from "./sb/plugins/events/broadcast";
+export * from "./sb/plugins/events/emit";
+export * from "./sb/plugins/events/emitAndReturn";
+export * from "./sb/plugins/events/emitStreamAndReceiveStream";
+export * from "./sb/plugins/observable/index";

package/lib/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./trace"), exports);
+__exportStar(require("./mocks"), exports);
+__exportStar(require("./sb/plugins/events/broadcast"), exports);
+__exportStar(require("./sb/plugins/events/emit"), exports);
+__exportStar(require("./sb/plugins/events/emitAndReturn"), exports);
+__exportStar(require("./sb/plugins/events/emitStreamAndReceiveStream"), exports);
+__exportStar(require("./sb/plugins/observable/index"), exports);
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,0CAAwB;AACxB,gEAA8C;AAC9C,2DAAyC;AACzC,oEAAkD;AAClD,iFAA+D;AAC/D,gEAA8C"}

package/lib/mocks.d.ts

@@ -0,0 +1,39 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { DEBUG_MODE, SBConfig, SBEvents, SBPlugins, BSBEventsConstructor, ObservableBackend, BSBObservableConstructor, BSBConfigConstructor } from "@bsb/base";
+import { SBObservable } from "@bsb/base";
+export declare const MockSBObservable: () => SBObservable;
+export declare const MockSBConfig: () => SBConfig;
+export declare const MockSBEvents: () => SBEvents;
+export declare const MockSBPlugins: () => SBPlugins;
+export declare const newSBObservable: () => Promise<SBObservable>;
+export declare const newMetrics: () => Promise<ObservableBackend>;
+export declare const getObservableConstructorConfig: (mode?: DEBUG_MODE) => BSBObservableConstructor;
+export declare const getLoggingConstructorConfig: (mode?: DEBUG_MODE) => BSBObservableConstructor;
+export declare const getConfigConstructorConfig: (config: any) => BSBConfigConstructor;
+export declare const getEventsConstructorConfig: (config: any) => Promise<BSBEventsConstructor>;
+export declare const generateNullLogging: () => ObservableBackend;