@bonsae/nrg 0.9.1 → 0.10.1

package/README.md

@@ -155,6 +155,9 @@ src/
 │   │   └── index.ts             # registerTypes, exports
 │   ├── constants.ts
 │   └── validator.ts             # AJV-based validation
+├── test/                        # Test utilities for consumers
+│   ├── index.ts                 # createNode, receive, close, reset
+│   └── mocks.ts                 # RED and Node-RED node mocks
 ├── vite/                        # Build tooling
 │   ├── plugin.ts                # Vite plugin factory
 │   ├── plugins/                 # Dev server, build orchestration
@@ -167,6 +170,37 @@ src/
     └── server.json
 ```
 
+## Testing
+
+Test your nodes' server-side logic with `@bonsae/nrg/test`:
+
+```bash
+pnpm add -D vitest
+```
+
+```typescript
+// tests/my-node.test.ts
+import { describe, it, expect } from "vitest";
+import { createNode } from "@bonsae/nrg/test";
+import MyNode from "../src/server/nodes/my-node";
+
+describe("my-node", () => {
+  it("should process messages", async () => {
+    const { node } = await createNode(MyNode, {
+      config: { greeting: "hello" },
+    });
+
+    await node.receive({ payload: "world" });
+
+    expect(node.sent(0)).toEqual([{ payload: "hello world" }]);
+  });
+});
+```
+
+```bash
+npx vitest run
+```
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonsae/nrg",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "NRG framework — build Node-RED nodes with Vue 3, TypeScript, and JSON Schema",
   "author": "Allan Oricil <allanoricil@duck.com>",
   "license": "MIT",
@@ -33,6 +33,10 @@
       "types": "./types/vite.d.ts",
       "default": "./vite/index.js"
     },
+    "./test": {
+      "types": "./types/test.d.ts",
+      "default": "./test/index.js"
+    },
     "./tsconfig/base.json": "./tsconfig/base.json",
     "./tsconfig/client.json": "./tsconfig/client.json",
     "./tsconfig/server.json": "./tsconfig/server.json"

package/server/index.cjs

@@ -39,6 +39,7 @@ __export(index_exports, {
   defineIONode: () => defineIONode,
   defineModule: () => defineModule,
   defineSchema: () => defineSchema,
+  initValidator: () => initValidator,
   registerType: () => registerType,
   registerTypes: () => registerTypes
 });
@@ -1043,6 +1044,7 @@ function defineModule(definition) {
   defineIONode,
   defineModule,
   defineSchema,
+  initValidator,
   registerType,
   registerTypes
 });

package/test/index.js

@@ -0,0 +1,273 @@
+// src/test/index.ts
+import { vi as vi2 } from "vitest";
+
+// src/test/mocks.ts
+import { vi } from "vitest";
+function createMockRED(options = {}) {
+  const { nodes = {}, settings = {} } = options;
+  return {
+    log: {
+      info: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      debug: vi.fn()
+    },
+    nodes: {
+      getNode: vi.fn((id) => nodes[id]),
+      registerType: vi.fn(),
+      createNode: vi.fn()
+    },
+    httpAdmin: {
+      get: vi.fn(),
+      post: vi.fn(),
+      put: vi.fn(),
+      delete: vi.fn(),
+      use: vi.fn()
+    },
+    settings: { ...settings },
+    _: vi.fn((key, subs) => {
+      if (!subs) return key;
+      return Object.entries(subs).reduce(
+        (str, [k, v]) => str.replace(`__${k}__`, v),
+        key
+      );
+    }),
+    util: {
+      evaluateNodeProperty: vi.fn(
+        (value, type, _node, msg, callback) => {
+          try {
+            let result;
+            switch (type) {
+              case "str":
+                result = String(value);
+                break;
+              case "num":
+                result = Number(value);
+                break;
+              case "bool":
+                result = value === "true" || value === true;
+                break;
+              case "json":
+                result = typeof value === "string" ? JSON.parse(value) : value;
+                break;
+              case "msg":
+                result = msg ? getProperty(msg, value) : void 0;
+                break;
+              case "date":
+                result = Date.now();
+                break;
+              case "bin":
+                result = Buffer.from(value ?? "");
+                break;
+              case "re":
+                result = new RegExp(value);
+                break;
+              case "jsonata":
+              case "flow":
+              case "global":
+              case "env":
+              case "cred":
+                result = void 0;
+                break;
+              case "node":
+                result = value;
+                break;
+              default:
+                result = value;
+            }
+            callback(null, result);
+          } catch (err) {
+            callback(err, void 0);
+          }
+        }
+      )
+    },
+    events: {
+      on: vi.fn(),
+      emit: vi.fn()
+    },
+    hooks: {
+      add: vi.fn(),
+      remove: vi.fn()
+    },
+    version: vi.fn(() => "0.0.0-test")
+  };
+}
+function getProperty(obj, path) {
+  return path.split(".").reduce((acc, key) => acc?.[key], obj);
+}
+function createContextStore() {
+  const store = {};
+  return {
+    get: vi.fn(
+      (key, _store, cb) => cb(null, store[key])
+    ),
+    set: vi.fn(
+      (key, value, _store, cb) => {
+        store[key] = value;
+        cb(null);
+      }
+    ),
+    keys: vi.fn(
+      (_store, cb) => cb(null, Object.keys(store))
+    )
+  };
+}
+function createMockNodeRedNode(options = {}) {
+  const nodeCtx = createContextStore();
+  const flowCtx = createContextStore();
+  const globalCtx = createContextStore();
+  const context = {
+    ...nodeCtx,
+    flow: flowCtx,
+    global: globalCtx
+  };
+  return {
+    id: options.id ?? `test-${Math.random().toString(36).slice(2, 10)}`,
+    type: options.type ?? "test-node",
+    name: options.name ?? "",
+    z: options.z ?? "flow-1",
+    x: 100,
+    y: 200,
+    g: void 0,
+    wires: options.wires ?? [[]],
+    credentials: options.credentials ?? {},
+    log: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    on: vi.fn(),
+    send: vi.fn(),
+    status: vi.fn(),
+    updateWires: vi.fn(),
+    receive: vi.fn(),
+    context: vi.fn(() => context),
+    ...options
+  };
+}
+
+// src/test/index.ts
+import { initValidator } from "@bonsae/nrg/server";
+function buildConfig(NodeClass, userConfig = {}) {
+  const defaults = {};
+  if (NodeClass.configSchema?.properties) {
+    for (const [key, prop] of Object.entries(
+      NodeClass.configSchema.properties
+    )) {
+      if (prop.default !== void 0) {
+        defaults[key] = prop.default;
+      }
+    }
+  }
+  return { ...defaults, ...userConfig };
+}
+function buildNodeRedNodes(configNodes) {
+  const nodes = {};
+  for (const [id, value] of Object.entries(configNodes)) {
+    if (value && typeof value === "object" && "id" in value) {
+      nodes[id] = { _node: value };
+    } else {
+      nodes[id] = value;
+    }
+  }
+  return nodes;
+}
+function attachHelpers(node, nodeRedNode) {
+  const sentMessages = [];
+  const statusCalls = [];
+  nodeRedNode.send.mockImplementation((msg) => {
+    sentMessages.push(msg);
+  });
+  nodeRedNode.status.mockImplementation((status) => {
+    statusCalls.push(status);
+  });
+  const nodeRef = node;
+  const helpers = {
+    async receive(msg) {
+      const sendFn = vi2.fn((outMsg) => {
+        nodeRedNode.send(outMsg);
+      });
+      await nodeRef._input(msg, sendFn);
+    },
+    async close(removed = false) {
+      await nodeRef._closed(removed);
+    },
+    reset() {
+      sentMessages.length = 0;
+      statusCalls.length = 0;
+      nodeRedNode.log.mockClear();
+      nodeRedNode.warn.mockClear();
+      nodeRedNode.error.mockClear();
+    },
+    sent(port) {
+      if (port === void 0) return [...sentMessages];
+      return sentMessages.map(
+        (msg) => Array.isArray(msg) ? msg[port] : port === 0 ? msg : void 0
+      ).filter((msg) => msg != null);
+    },
+    statuses() {
+      return [...statusCalls];
+    },
+    logged(level) {
+      if (level) {
+        return nodeRedNode[level === "info" ? "log" : level].mock.calls.map(
+          (c) => c[0]
+        );
+      }
+      return [
+        ...nodeRedNode.log.mock.calls.map((c) => c[0]),
+        ...nodeRedNode.warn.mock.calls.map((c) => c[0]),
+        ...nodeRedNode.error.mock.calls.map((c) => c[0])
+      ];
+    },
+    warned() {
+      return nodeRedNode.warn.mock.calls.map((c) => c[0]);
+    },
+    errored() {
+      return nodeRedNode.error.mock.calls.map((c) => c[0]);
+    }
+  };
+  return Object.assign(node, helpers);
+}
+function isConfigNode(NodeClass) {
+  return NodeClass.category === "config";
+}
+async function createNode(NodeClass, options = {}) {
+  const {
+    config: userConfig = {},
+    credentials = {},
+    configNodes = {},
+    settings = {},
+    overrides: overrideOpts = {}
+  } = options;
+  const redNodes = buildNodeRedNodes(configNodes);
+  const RED = createMockRED({ nodes: redNodes, settings });
+  initValidator(RED);
+  const configDefaults = {
+    id: overrideOpts.id ?? `test-${Math.random().toString(36).slice(2, 10)}`,
+    type: NodeClass.type
+  };
+  if (isConfigNode(NodeClass)) {
+    configDefaults._users = [];
+  }
+  const config = buildConfig(NodeClass, {
+    ...configDefaults,
+    ...userConfig
+  });
+  const nodeRedNode = createMockNodeRedNode({
+    id: config.id,
+    type: NodeClass.type,
+    name: config.name ?? "",
+    credentials,
+    ...overrideOpts
+  });
+  await Promise.resolve(
+    NodeClass._registered?.(RED) ?? NodeClass.registered?.(RED)
+  );
+  const node = new NodeClass(RED, nodeRedNode, config, credentials);
+  const augmented = attachHelpers(node, nodeRedNode);
+  await Promise.resolve(augmented.created?.());
+  return { node: augmented, RED };
+}
+export {
+  createNode
+};

package/types/test.d.ts

@@ -0,0 +1,39 @@
+
+export interface CreateNodeOptions {
+  config?: Record<string, any>;
+  credentials?: Record<string, any>;
+  configNodes?: Record<string, any>;
+  settings?: Record<string, any>;
+  overrides?: Record<string, any>;
+}
+
+type ExtractInput<T> = T extends { input(msg: infer I): any } ? I : any;
+type ExtractOutput<T> = T extends { send(msg: infer O): any } ? O : any;
+
+export interface TestNodeHelpers<TInput = any, TOutput = any> {
+  receive(msg: TInput): Promise<void>;
+  close(removed?: boolean): Promise<void>;
+  reset(): void;
+  sent(): TOutput[];
+  sent(port: number): any[];
+  statuses(): any[];
+  logged(level?: "info" | "warn" | "error" | "debug"): string[];
+  warned(): string[];
+  errored(): string[];
+}
+
+export interface CreateNodeResult<T> {
+  node: T & TestNodeHelpers<ExtractInput<T>, ExtractOutput<T>>;
+  RED: any;
+}
+
+interface NodeClass {
+  readonly type: string;
+  readonly category?: string;
+  readonly configSchema?: any;
+  registered?(RED: any): void | Promise<void>;
+  _registered?(RED: any): void | Promise<void>;
+  new (...args: any[]): any;
+}
+
+export declare function createNode<T extends NodeClass>(NodeClass: T, options?: CreateNodeOptions): Promise<CreateNodeResult<InstanceType<T>>>;