@bonsae/nrg 0.19.1 → 0.20.0

package/README.md

@@ -9,6 +9,9 @@
   <a href="https://socket.dev/npm/package/@bonsae/nrg"><img src="https://badge.socket.dev/npm/package/@bonsae/nrg?v=1" alt="Socket Badge"></a>
 </p>
 
+> [!WARNING]
+> While **nrg** is at `v0`, breaking changes can land in any release and will **not** bump the major version. Pin an exact version and review the release notes before upgrading.
+
 # nrg
 
 Build Node-RED nodes with Vue 3, TypeScript, JSON Schema validations, Vite and Vitest.
@@ -129,7 +132,7 @@ See the [consumer template](https://github.com/AllanOricil/node-red-vue-template
 
 ## Testing
 
-NRG provides four test libraries and bundles most test infrastructure as direct dependencies. Install `vitest` plus any optional peer dependencies you need:
+NRG provides five test libraries and bundles most test infrastructure as direct dependencies. Install `vitest` plus any optional peer dependencies you need:
 
 ```bash
 pnpm add -D vitest
@@ -146,16 +149,35 @@ Optional peer dependencies:
 | `@vitest/coverage-istanbul`  | Coverage with `--coverage` (Istanbul provider)               |
 
 - `@bonsae/nrg/test/server/unit` — server-side unit tests
+- `@bonsae/nrg/test/server/integration` — server-side integration tests (real Node-RED runtime)
 - `@bonsae/nrg/test/client/unit` — client-side unit tests (TypeScript logic)
 - `@bonsae/nrg/test/client/component` — client component tests (Vue + browser)
 - `@bonsae/nrg/test/client/e2e` — browser E2E tests (Playwright)
 
 ### Server Unit Tests
 
+Instantiate your node with mocked Node-RED internals and exercise its full lifecycle in-process:
+
 ```typescript
+// vitest.server.unit.config.ts
+import { defineConfig, mergeConfig } from "vitest/config";
+import { defaultConfig } from "@bonsae/nrg/test/server/unit/config";
+
+export default mergeConfig(
+  defaultConfig,
+  defineConfig({
+    test: {
+      include: ["tests/server/unit/**/*.test.ts"],
+    },
+  }),
+);
+```
+
+```typescript
+// tests/server/unit/my-node.test.ts
 import { describe, it, expect } from "vitest";
 import { createNode } from "@bonsae/nrg/test/server/unit";
-import MyNode from "../src/server/nodes/my-node";
+import MyNode from "../../../src/server/nodes/my-node";
 
 describe("my-node", () => {
   it("should process messages", async () => {
@@ -170,6 +192,58 @@ describe("my-node", () => {
 });
 ```
 
+### Server Integration Tests
+
+Boot a real, headless Node-RED runtime, deploy your nodes, and drive them with real messages — verifying config-node resolution, credentials, wiring, and context that unit mocks can't. Integration tests live in `tests/server/integration`, separate from `tests/server/unit`. Add `node-red` as a dev dependency, then:
+
+```typescript
+// vitest.server.integration.config.ts
+import { defineConfig, mergeConfig } from "vitest/config";
+import { defaultConfig } from "@bonsae/nrg/test/server/integration/config";
+
+export default mergeConfig(
+  defaultConfig,
+  defineConfig({
+    test: {
+      include: ["tests/server/integration/**/*.test.ts"],
+    },
+  }),
+);
+```
+
+```typescript
+// tests/server/integration/my-node.test.ts
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import {
+  startRuntime,
+  type Runtime,
+} from "@bonsae/nrg/test/server/integration";
+import MyNode from "../../../src/server/nodes/my-node";
+
+describe("my-node (integration)", () => {
+  let runtime: Runtime;
+
+  beforeAll(async () => {
+    runtime = await startRuntime({ nodes: [MyNode] });
+  });
+
+  afterAll(async () => {
+    await runtime.stop();
+  });
+
+  it("processes input in a real runtime", async () => {
+    const flow = runtime.flow();
+    const node = flow.addNode(MyNode, { greeting: "hello" });
+    await flow.deploy();
+
+    await node.receive({ payload: "world" });
+
+    const out = (await node.read()) as { output: { payload: string } };
+    expect(out.output.payload).toBe("hello world");
+  });
+});
+```
+
 ### Client Unit Tests
 
 Test client-side TypeScript logic (validation, utilities) with mocked `RED` and `$` globals:
@@ -257,6 +331,77 @@ describe("MyForm", () => {
 });
 ```
 
+### Client E2E Tests
+
+Drive the real editor in a live Node-RED instance with Playwright — schema-driven forms, validation, TypedInput, config selectors, and i18n. Install `playwright`, then point a global setup at a flow and walk the editor with `NodeRedEditor`:
+
+```typescript
+// vitest.client.e2e.config.ts
+import { defineConfig } from "vitest/config";
+import { defaultConfig } from "@bonsae/nrg/test/client/e2e";
+
+export default defineConfig({
+  test: {
+    ...defaultConfig,
+    globalSetup: "tests/client/e2e/global-setup.ts",
+    include: ["tests/client/e2e/**/*.test.ts"],
+  },
+});
+```
+
+```typescript
+// tests/client/e2e/global-setup.ts
+import {
+  setup as baseSetup,
+  teardown as baseTeardown,
+} from "@bonsae/nrg/test/client/e2e";
+
+export async function setup() {
+  await baseSetup({
+    flow: [
+      { id: "tab1", type: "tab", label: "E2E Tests" },
+      { id: "n1", type: "my-node", z: "tab1", name: "", wires: [[]] },
+    ],
+  });
+}
+
+export async function teardown() {
+  await baseTeardown();
+}
+```
+
+```typescript
+// tests/client/e2e/my-node.test.ts
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { chromium, type Browser } from "playwright";
+import { NodeRedEditor } from "@bonsae/nrg/test/client/e2e";
+
+describe("my-node editor", () => {
+  let browser: Browser;
+  let editor: NodeRedEditor;
+
+  beforeAll(async () => {
+    browser = await chromium.launch();
+    const port = Number(process.env.NODE_RED_PORT);
+    editor = new NodeRedEditor(await browser.newPage(), port);
+    await editor.open();
+  });
+
+  afterAll(() => browser.close());
+
+  test("name field round-trips", async () => {
+    await editor.editNode("n1");
+    const name = editor.field("Name");
+    await name.fill("Test Node");
+    await editor.clickDone();
+
+    await editor.editNode("n1");
+    expect(await name.getValue()).toBe("Test Node");
+    await editor.clickCancel();
+  });
+});
+```
+
 See the [testing guide](https://bonsaedev.github.io/nrg/guide/testing) for full API reference.
 
 ## Development
@@ -270,6 +415,7 @@ pnpm validate:lint                # eslint
 pnpm validate:format              # prettier check
 pnpm test                         # run all tests
 pnpm test:core:server:unit        # server unit tests
+pnpm test:core:server:integration # server integration tests (real Node-RED)
 pnpm test:core:client:unit        # client unit tests
 pnpm test:core:client:component   # client component tests
 pnpm test:core:client:e2e         # client E2E tests

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonsae/nrg",
-  "version": "0.19.1",
+  "version": "0.20.0",
   "description": "NRG framework — build Node-RED nodes with Vue 3, TypeScript, and JSON Schema",
   "author": "Allan Oricil <allanoricil@duck.com>",
   "license": "MIT",
@@ -52,6 +52,11 @@
       "default": "./test/server/unit/index.js"
     },
     "./test/server/unit/config": "./test/server/unit/config.js",
+    "./test/server/integration": {
+      "types": "./types/test-server-integration.d.ts",
+      "default": "./test/server/integration/index.js"
+    },
+    "./test/server/integration/config": "./test/server/integration/config.js",
     "./test/client/component": {
       "types": "./types/test-client-component.d.ts",
       "default": "./test/client/component/index.js"
@@ -72,19 +77,20 @@
     "./tsconfig/core/server.json": "./tsconfig/core/server.json",
     "./tsconfig/core/client.json": "./tsconfig/core/client.json",
     "./tsconfig/test/server/unit.json": "./tsconfig/test/server/unit.json",
+    "./tsconfig/test/server/integration.json": "./tsconfig/test/server/integration.json",
     "./tsconfig/test/client/component.json": "./tsconfig/test/client/component.json",
     "./tsconfig/test/client/unit.json": "./tsconfig/test/client/unit.json",
     "./tsconfig/test/client/e2e.json": "./tsconfig/test/client/e2e.json"
   },
   "peerDependencies": {
-    "vite": "^6.0.0",
-    "vitest": "^4.0.0",
-    "vue": "^3.5.14",
+    "@vitest/browser-playwright": "^4.0.0",
     "@vitest/coverage-istanbul": "^4.0.0",
     "@vitest/coverage-v8": "^4.0.0",
-    "@vitest/browser-playwright": "^4.0.0",
     "playwright": "^1.50.0",
-    "vitest-browser-vue": "^2.0.0"
+    "vite": "^6.0.0",
+    "vitest": "^4.0.0",
+    "vitest-browser-vue": "^2.0.0",
+    "vue": "^3.5.14"
   },
   "peerDependenciesMeta": {
     "@vitest/coverage-istanbul": {
@@ -107,6 +113,7 @@
     "@clack/prompts": "^1.0.1",
     "@sinclair/typebox": "^0.34.33",
     "@vitejs/plugin-vue": "^5.2.3",
+    "@vitest/browser-playwright": "^4.1.5",
     "ajv": "^8.17.1",
     "ajv-errors": "^3.0.0",
     "ajv-formats": "^3.0.1",
@@ -115,16 +122,15 @@
     "es-toolkit": "^1.37.2",
     "esbuild": "^0.25.4",
     "get-port": "^7.1.0",
+    "happy-dom": "^20.10.2",
     "jsonpointer": "^5.0.1",
     "mime-types": "^3.0.1",
+    "playwright": "^1.60.0",
     "tree-kill": "^1.2.2",
     "typescript": "^5.8.3",
     "vite-plugin-dts": "^4.5.4",
     "vite-plugin-static-copy": "^3.1.0",
-    "vue": "^3.5.14",
-    "@vitest/browser-playwright": "^4.1.5",
-    "happy-dom": "^20.10.2",
-    "playwright": "^1.60.0",
-    "vitest-browser-vue": "^2.1.0"
+    "vitest-browser-vue": "^2.1.0",
+    "vue": "^3.5.14"
   }
 }

package/test/client/component/config.js

@@ -32,6 +32,7 @@ var defaultConfig = {
   test: {
     testTimeout: 3e4,
     setupFiles: ["@bonsae/nrg/test/client/component/setup"],
+    include: ["tests/client/component/**/*.test.ts"],
     browser: {
       enabled: true,
       instances: [

package/test/client/e2e/index.js

@@ -2667,7 +2667,8 @@ var NodeRedTestEnvironment = class {
 var defaultConfig = {
   testTimeout: 6e4,
   hookTimeout: 12e4,
-  globalSetup: ["@bonsae/nrg/test/client/e2e"]
+  globalSetup: ["@bonsae/nrg/test/client/e2e"],
+  include: ["tests/client/e2e/**/*.test.ts"]
 };
 var _env = null;
 async function setup(options) {

package/test/client/unit/config.js

@@ -18,7 +18,8 @@ var defaultConfig = {
   test: {
     testTimeout: 3e4,
     environment: "happy-dom",
-    setupFiles: ["@bonsae/nrg/test/client/unit/setup"]
+    setupFiles: ["@bonsae/nrg/test/client/unit/setup"],
+    include: ["tests/client/unit/**/*.test.ts"]
   }
 };
 export {

package/test/server/integration/config.js

@@ -0,0 +1,21 @@
+// src/test/server/integration/config.ts
+import path from "path";
+var defaultConfig = {
+  resolve: {
+    alias: {
+      "@": path.resolve(process.cwd(), "src")
+    }
+  },
+  test: {
+    testTimeout: 3e4,
+    hookTimeout: 3e4,
+    pool: "forks",
+    fileParallelism: false,
+    // integration tests live under tests/server/integration, separate from the
+    // unit tier (tests/server/unit) so the two never overlap
+    include: ["tests/server/integration/**/*.test.ts"]
+  }
+};
+export {
+  defaultConfig
+};

package/test/server/integration/index.js

@@ -0,0 +1,375 @@
+// src/test/server/integration/runtime.ts
+import http from "http";
+import os from "os";
+import fs from "fs";
+import path from "path";
+import { createRequire } from "module";
+import { registerTypes } from "@bonsae/nrg/server";
+
+// src/test/server/integration/recorder.ts
+var Recorder = class {
+  #sent = /* @__PURE__ */ new Map();
+  #received = /* @__PURE__ */ new Map();
+  #waiters = [];
+  recordSent(id, port, msg) {
+    this.#push("sent", id, { port, msg });
+  }
+  recordReceived(id, msg) {
+    if (!id) return;
+    this.#push("received", id, { port: 0, msg });
+  }
+  /** Snapshot of all messages on a channel for a node (optionally one port). */
+  snapshot(channel, id, port) {
+    return this.#filter(channel, id, port).map((c) => c.msg);
+  }
+  /** Resolve the message at `index` on a channel, awaiting it if not yet seen. */
+  next(channel, id, port, index, timeoutMs) {
+    const existing = this.#filter(channel, id, port);
+    if (existing.length > index) return Promise.resolve(existing[index].msg);
+    return new Promise((resolve, reject) => {
+      const waiter = {
+        channel,
+        id,
+        port,
+        index,
+        settle: (msg) => {
+          clearTimeout(timer);
+          resolve(msg);
+        }
+      };
+      const timer = setTimeout(() => {
+        this.#waiters = this.#waiters.filter((w) => w !== waiter);
+        const where = port === void 0 ? "" : ` on port ${port}`;
+        reject(
+          new Error(
+            `Timed out after ${timeoutMs}ms waiting for ${channel} message #${index} from node ${id}${where}`
+          )
+        );
+      }, timeoutMs);
+      this.#waiters.push(waiter);
+    });
+  }
+  clear() {
+    this.#sent.clear();
+    this.#received.clear();
+    this.#waiters = [];
+  }
+  #map(channel) {
+    return channel === "sent" ? this.#sent : this.#received;
+  }
+  #filter(channel, id, port) {
+    const list = this.#map(channel).get(id) ?? [];
+    return port === void 0 ? list : list.filter((c) => c.port === port);
+  }
+  #push(channel, id, captured) {
+    const map = this.#map(channel);
+    const list = map.get(id) ?? [];
+    list.push(captured);
+    map.set(id, list);
+    for (let i = this.#waiters.length - 1; i >= 0; i--) {
+      const w = this.#waiters[i];
+      if (w.channel !== channel || w.id !== id) continue;
+      const filtered = this.#filter(channel, id, w.port);
+      if (filtered.length > w.index) {
+        this.#waiters.splice(i, 1);
+        w.settle(filtered[w.index].msg);
+      }
+    }
+  }
+};
+
+// src/core/server/nodes/utils.ts
+import { Kind } from "@sinclair/typebox";
+function setupContext(context, store) {
+  return {
+    get: (key) => new Promise(
+      (resolve, reject) => context.get(
+        key,
+        store,
+        (error, value) => error ? reject(error) : resolve(value)
+      )
+    ),
+    set: (key, value) => new Promise(
+      (resolve, reject) => context.set(
+        key,
+        value,
+        store,
+        (error) => error ? reject(error) : resolve()
+      )
+    ),
+    keys: () => new Promise(
+      (resolve, reject) => context.keys(store, (error, k) => error ? reject(error) : resolve(k))
+    )
+  };
+}
+
+// src/test/server/integration/flow.ts
+var seq = 0;
+function genId(prefix) {
+  seq += 1;
+  return `${prefix}${seq.toString(36)}`;
+}
+function tick() {
+  return new Promise((resolve) => setImmediate(resolve));
+}
+var NodeRef = class {
+  id;
+  type;
+  isConfig;
+  name;
+  config;
+  credentials;
+  wires = [];
+  #flow;
+  #readCursor = /* @__PURE__ */ new Map();
+  constructor(flow, type, isConfig, config, opts) {
+    this.#flow = flow;
+    this.type = type;
+    this.isConfig = isConfig;
+    this.config = config;
+    this.credentials = opts.credentials;
+    this.id = opts.id ?? genId("n");
+    this.name = opts.name ?? "";
+  }
+  /** Wire this node's output `port` to `target`'s input. */
+  wire(target, port = 0) {
+    while (this.wires.length <= port) this.wires.push([]);
+    this.wires[port].push(target.id);
+    return this;
+  }
+  /** Deliver a message to this node's input (Node-RED's upstream path). */
+  async receive(msg) {
+    const node = this.#flow.runtimeNode(this.id);
+    if (!node) {
+      throw new Error(
+        `Node "${this.id}" (${this.type}) is not deployed \u2014 call flow.deploy() first`
+      );
+    }
+    node.receive(msg);
+    await tick();
+  }
+  /** Snapshot of everything this node has emitted (optionally one port). */
+  sent(port) {
+    return this.#flow.recorder.snapshot("sent", this.id, port);
+  }
+  /** Snapshot of everything delivered to this node's input. */
+  received(port) {
+    return this.#flow.recorder.snapshot("received", this.id, port);
+  }
+  /**
+   * Promise-based access to this node's context stores (`node` / `flow` /
+   * `global`) — preset values before `receive`, and assert them afterward.
+   */
+  get context() {
+    const rn = this.#flow.runtimeNode(this.id);
+    if (!rn) {
+      throw new Error(
+        `Node "${this.id}" (${this.type}) is not deployed \u2014 call flow.deploy() first`
+      );
+    }
+    const ctx = rn.context();
+    return {
+      node: setupContext(ctx),
+      flow: setupContext(ctx.flow),
+      global: setupContext(ctx.global)
+    };
+  }
+  /**
+   * Consume the next un-read message this node emitted (FIFO cursor), awaiting
+   * it if not yet sent. Call repeatedly to walk multiple emissions.
+   */
+  async read(port, opts = {}) {
+    const cursor = this.#readCursor.get(port) ?? 0;
+    const msg = await this.#flow.recorder.next(
+      "sent",
+      this.id,
+      port,
+      cursor,
+      opts.timeout ?? 5e3
+    );
+    this.#readCursor.set(port, cursor + 1);
+    return msg;
+  }
+};
+var Flow = class {
+  recorder;
+  #RED;
+  #flowId = genId("flow");
+  #nodes = [];
+  constructor(RED, recorder) {
+    this.#RED = RED;
+    this.recorder = recorder;
+  }
+  /** Add any node — regular or config (detected via `category === "config"`). */
+  addNode(Cls, config = {}, opts = {}) {
+    const isConfig = Cls.category === "config";
+    const ref = new NodeRef(this, Cls.type, isConfig, config, opts);
+    this.#nodes.push(ref);
+    return ref;
+  }
+  /** Build the flow JSON and deploy it; resolves once the flow has started. */
+  async deploy() {
+    this.recorder.clear();
+    const flows = this.#buildFlows();
+    await this.#RED.runtime.flows.setFlows({
+      flows: { flows },
+      deploymentType: "full"
+    });
+    await this.#waitForDeploy();
+  }
+  /** Drop the built nodes and clear captured messages (reset between tests). */
+  async clear() {
+    this.#nodes = [];
+    this.recorder.clear();
+    await this.#RED.runtime.flows.setFlows({
+      flows: { flows: [] },
+      deploymentType: "full"
+    });
+  }
+  runtimeNode(id) {
+    return this.#RED.nodes.getNode(id);
+  }
+  #buildFlows() {
+    const flows = [
+      { id: this.#flowId, type: "tab", label: "nrg-integration" }
+    ];
+    for (const ref of this.#nodes) {
+      const base = {
+        id: ref.id,
+        type: ref.type,
+        name: ref.name,
+        ...this.#serializeConfig(ref.config),
+        ...ref.credentials ? { credentials: ref.credentials } : {}
+      };
+      flows.push(
+        ref.isConfig ? base : {
+          ...base,
+          z: this.#flowId,
+          wires: ref.wires.length ? ref.wires : [[]]
+        }
+      );
+    }
+    return flows;
+  }
+  /** NodeRef config values serialize to the referenced node's id (a real NodeRef). */
+  #serializeConfig(config) {
+    const out = {};
+    for (const [key, value] of Object.entries(config)) {
+      out[key] = value instanceof NodeRef ? value.id : value;
+    }
+    return out;
+  }
+  async #waitForDeploy() {
+    const target = this.#nodes.find((n) => !n.isConfig);
+    if (!target) return;
+    const deadline = Date.now() + 5e3;
+    while (Date.now() < deadline && !this.#RED.nodes.getNode(target.id)) {
+      await new Promise((resolve) => setTimeout(resolve, 15));
+    }
+    if (!this.#RED.nodes.getNode(target.id)) {
+      throw new Error("Flow deploy did not complete within 5s");
+    }
+    for (const ref of this.#nodes) {
+      if (ref.isConfig) continue;
+      const rn = this.#RED.nodes.getNode(ref.id);
+      if (rn) this.#wrapSend(rn, ref.id);
+    }
+    await tick();
+  }
+  #wrapSend(rn, id) {
+    const recorder = this.recorder;
+    const original = rn.send.bind(rn);
+    rn.send = (arg) => {
+      if (Array.isArray(arg)) {
+        arg.forEach((m, port) => {
+          if (m != null) recorder.recordSent(id, port, m);
+        });
+      } else if (arg != null) {
+        recorder.recordSent(id, 0, arg);
+      }
+      return original(arg);
+    };
+  }
+};
+
+// src/test/server/integration/runtime.ts
+function requireNodeRed() {
+  const req = createRequire(path.join(process.cwd(), "package.json"));
+  let entry;
+  try {
+    entry = req.resolve("node-red");
+  } catch {
+    throw new Error(
+      "Integration tests need Node-RED installed. Add `node-red` as a devDependency."
+    );
+  }
+  return req(entry);
+}
+function headlessSettings(userDir, overrides) {
+  return {
+    // keep RED.httpAdmin a valid router (so node registration's route setup is
+    // safe) but never serve the editor UI
+    disableEditor: true,
+    httpNodeRoot: false,
+    userDir,
+    flowFile: path.join(userDir, "flows.json"),
+    credentialSecret: "nrg-integration-test",
+    logging: { console: { level: "fatal", metrics: false, audit: false } },
+    functionGlobalContext: {},
+    ...overrides
+  };
+}
+async function startRuntime(options) {
+  const RED = requireNodeRed();
+  const userDir = fs.mkdtempSync(path.join(os.tmpdir(), "nrg-integration-"));
+  const server = http.createServer();
+  await new Promise(
+    (resolve) => server.listen(0, "127.0.0.1", () => resolve())
+  );
+  RED.init(server, headlessSettings(userDir, options.settings));
+  const recorder = new Recorder();
+  RED.hooks.add(
+    "onReceive",
+    (event) => recorder.recordReceived(event.destination?.id, event.msg)
+  );
+  await registerTypes(options.nodes)(
+    RED
+  );
+  await RED.start();
+  await new Flow(RED, recorder).deploy();
+  return new Runtime(RED, server, userDir, recorder);
+}
+var Runtime = class {
+  #RED;
+  #server;
+  #userDir;
+  #recorder;
+  constructor(RED, server, userDir, recorder) {
+    this.#RED = RED;
+    this.#server = server;
+    this.#userDir = userDir;
+    this.#recorder = recorder;
+  }
+  /** Start a fresh flow to build, deploy, drive and inspect. */
+  flow() {
+    return new Flow(this.#RED, this.#recorder);
+  }
+  /** Stop Node-RED, close the server and remove the temp user dir. */
+  async stop() {
+    try {
+      await this.#RED.stop();
+    } catch {
+    }
+    await new Promise((resolve) => this.#server.close(() => resolve()));
+    try {
+      fs.rmSync(this.#userDir, { recursive: true, force: true });
+    } catch {
+    }
+  }
+};
+export {
+  Flow,
+  NodeRef,
+  Runtime,
+  startRuntime
+};

package/test/server/unit/config.js

@@ -7,7 +7,11 @@ var defaultConfig = {
     }
   },
   test: {
-    testTimeout: 3e4
+    testTimeout: 3e4,
+    // unit tests live under tests/server/unit; integration tests live under
+    // tests/server/integration and run via their own config — the two tiers are
+    // separated by folder, so no exclude is needed
+    include: ["tests/server/unit/**/*.test.ts"]
   }
 };
 export {

package/test/server/unit/index.js

@@ -504,7 +504,10 @@ function attachHelpers(node, nodeRedNode, NodeClass) {
     },
     errored() {
       return nodeRedNode.error.mock.calls.map((c) => c[0]);
-    }
+    },
+    // expose the node's own (already promise-wrapped) context stores; the
+    // node keeps using the same object internally, callable form included
+    context: node.context
   };
   return Object.assign(node, helpers);
 }

package/tsconfig/test/server/integration.json

@@ -0,0 +1,6 @@
+{
+  "extends": "../../base.json",
+  "compilerOptions": {
+    "lib": ["ESNext"]
+  }
+}

package/types/test-client-e2e.d.ts

@@ -89,6 +89,7 @@ export declare const defaultConfig: {
 	testTimeout: number;
 	hookTimeout: number;
 	globalSetup: string[];
+	include: string[];
 };
 export declare function setup(options?: SetupOptions): Promise<void>;
 export declare function teardown(): Promise<void>;

package/types/test-server-integration.d.ts

@@ -0,0 +1,523 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { SchemaOptions, Static, TObject, TOptional, TProperties, TSchema, TString } from '@sinclair/typebox';
+import { EventEmitter } from 'events';
+import { Express as Express$1 } from 'express';
+import { Http2ServerRequest } from 'http2';
+
+interface NodeRedRuntimeSettings {
+	userDir?: string;
+	nodesDir?: string | string[];
+	flowFile?: string;
+	flowFilePretty?: boolean;
+	credentialSecret?: string | false;
+	requireHttps?: boolean;
+	https?: {
+		key: string;
+		cert: string;
+	} | (() => Promise<{
+		key: string;
+		cert: string;
+	}> | {
+		key: string;
+		cert: string;
+	});
+	httpsRefreshInterval?: number;
+	httpAdminRoot?: string;
+	httpNodeRoot?: string;
+	httpNodeCors?: {
+		origin: string;
+		methods: string;
+	};
+	httpStatic?: string | {
+		path: string;
+		root: string;
+	}[];
+	httpStaticRoot?: string;
+	httpAdminMiddleware?: (req: unknown, res: unknown, next: () => void) => void;
+	httpNodeMiddleware?: (req: unknown, res: unknown, next: () => void) => void;
+	httpServerOptions?: Record<string, unknown>;
+	adminAuth?: {
+		type?: "credentials" | "strategy";
+		users?: {
+			username: string;
+			password: string;
+			permissions?: string | string[];
+		}[];
+		default?: {
+			permissions?: string | string[];
+		};
+		tokens?: (token: string) => Promise<{
+			user: string;
+			permissions: string | string[];
+		} | null>;
+		tokenHeader: "string";
+		sessionExpiryTime?: number;
+		[key: string]: unknown;
+	};
+	httpNodeAuth?: {
+		user?: string;
+		pass?: string;
+	};
+	httpStaticAuth?: {
+		user?: string;
+		pass?: string;
+	};
+	lang?: "en-US" | "de" | "es-ES" | "fr" | "ko" | "pt-BR" | "ru" | "ja" | "zh-CN" | "zh-TW";
+	diagnostics?: {
+		enabled?: boolean;
+		ui?: boolean;
+	};
+	runtimeState?: {
+		enabled?: boolean;
+		ui?: boolean;
+	};
+	disableEditor?: boolean;
+	editorTheme?: {
+		page?: {
+			title?: string;
+			favicon?: string;
+			css?: string | string[];
+			scripts?: string | string[];
+		};
+		header?: {
+			title?: string;
+			image?: string;
+			url?: string;
+		};
+		deployButton?: {
+			type?: "simple" | "default";
+			label?: string;
+			icon?: string;
+		};
+		menu?: {
+			"menu-item-import-library"?: boolean;
+			"menu-item-export-library"?: boolean;
+			"menu-item-keyboard-shortcuts"?: boolean;
+			"menu-item-help"?: {
+				label?: string;
+				url?: string;
+			};
+			[menuItem: string]: boolean | {
+				label?: string;
+				url?: string;
+			} | undefined;
+		};
+		userMenu?: boolean;
+		login?: {
+			image?: string;
+		};
+		logout?: {
+			redirect?: string;
+		};
+		palette?: {
+			catalogues?: string[];
+			categories?: string[];
+			theme?: {
+				category: string;
+				type: string;
+				color: string;
+			}[];
+		};
+		projects?: {
+			enabled?: boolean;
+			workflow?: {
+				mode: "manual" | "auto";
+			};
+		};
+		codeEditor?: {
+			lib?: "monaco" | "ace";
+			options?: Record<string, unknown>;
+		};
+		mermaid?: {
+			theme?: string;
+		};
+		tours?: boolean;
+		theme?: string;
+		[key: string]: unknown;
+	};
+	contextStorage?: {
+		default?: {
+			module?: "memory" | "localfilesystem" | object;
+			config?: Record<string, unknown>;
+		};
+		[store: string]: {
+			module?: "memory" | "localfilesystem" | object;
+			config?: Record<string, unknown>;
+		} | undefined;
+	};
+	exportGlobalContextKeys?: boolean;
+	logging?: {
+		console?: {
+			level?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "off";
+			metrics?: boolean;
+			audit?: boolean;
+		};
+	};
+	fileWorkingDirectory?: string;
+	functionExternalModules?: boolean;
+	functionGlobalContext?: Record<string, unknown>;
+	nodeMessageBufferMaxLength?: number;
+	functionTimeout?: number;
+	externalModules?: {
+		autoInstall?: boolean;
+		autoInstallRetry?: number;
+		palette?: {
+			allowInstall?: boolean;
+			allowUpdate?: boolean;
+			allowUpload?: boolean;
+			allowList?: string[];
+			denyList?: string[];
+			allowUpdateList?: string[];
+			denyUpdateList?: string[];
+		};
+		modules?: {
+			allowInstall?: boolean;
+			allowList?: string[];
+			denyList?: string[];
+		};
+	};
+	execMaxBufferSize?: number;
+	debugMaxLength?: number;
+	debugUseColors?: boolean;
+	httpRequestTimeout?: number;
+	mqttReconnectTime?: number;
+	serialReconnectTime?: number;
+	socketReconnectTime?: number;
+	socketTimeout?: number;
+	tcpMsgQueueSize?: number;
+	inboundWebSocketTimeout?: number;
+	tlsConfigDisableLocalFiles?: boolean;
+	webSocketNodeVerifyClient?: (info: {
+		origin: string;
+		req: Http2ServerRequest;
+		secure: boolean;
+	}) => boolean;
+	apiMaxLength?: string;
+	[key: string]: unknown;
+}
+declare const NodeConfigSchema: import("@sinclair/typebox").TObject<{
+	id: import("@sinclair/typebox").TString;
+	type: import("@sinclair/typebox").TString;
+	name: import("@sinclair/typebox").TString;
+	z: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+interface NodeRedLog {
+	info(msg: any): void;
+	warn(msg: any): void;
+	error(msg: any, error?: any): void;
+	debug(msg: any): void;
+	trace(msg: any): void;
+	log(msg: {
+		level: number;
+		msg: string;
+	}): void;
+	metric(): boolean;
+	audit(msg: Record<string, any>, req?: any): void;
+	addHandler(handler: (msg: any) => void): void;
+	removeHandler(handler: (msg: any) => void): void;
+	FATAL: 10;
+	ERROR: 20;
+	WARN: 30;
+	INFO: 40;
+	DEBUG: 50;
+	TRACE: 60;
+	AUDIT: 98;
+	METRIC: 99;
+}
+interface NodeRedNode {
+	id: string;
+	type: string;
+	name?: string;
+	z?: string;
+	x: number;
+	y: number;
+	g?: string;
+	wires: string[][];
+	credentials: any;
+	_node?: INode;
+	send(msg: any): void;
+	receive(msg: any): void;
+	status(status: string | {
+		fill?: string;
+		shape?: string;
+		text?: string;
+	}): void;
+	updateWires(wires: string[][]): void;
+	on(event: string, callback: (...args: any[]) => void): void;
+	log(msg: any): void;
+	warn(msg: any): void;
+	error(msg: any, errorMsg?: any): void;
+	context(): NodeRedNodeContext;
+	[key: string]: any;
+}
+interface NodeRedNodeContext extends NodeRedContextStore {
+	flow: NodeRedContextStore;
+	global: NodeRedContextStore;
+}
+interface NodeRedNodes {
+	registerType(type: string, constructor: any, opts?: any): void;
+	getNode(id: string): (NodeRedNode & {
+		_node?: INode;
+	}) | undefined;
+	createNode(node: NodeRedNode, config: Record<string, any>): void;
+	getCredentials(id: string): Record<string, any> | undefined;
+	/** Merge credentials into a node's stored credential set (runtime API). */
+	addCredentials(id: string, credentials: Record<string, any>): void;
+	eachNode(callback: (node: any) => void): void;
+	getType(type: string): any;
+	getNodeInfo(type: string): any;
+	getNodeList(filter?: any): any[];
+	getModuleInfo(module: string): any;
+	installModule(module: string, version?: string): Promise<any>;
+	uninstallModule(module: string): Promise<any>;
+	enableNode(id: string): Promise<any>;
+	disableNode(id: string): Promise<any>;
+}
+interface NodeRedUtil {
+	evaluateNodeProperty(value: any, type: string, node: any, msg: Record<string, any> | undefined, callback: (err: Error | null, result: any) => void): void;
+	generateId(): string;
+	cloneMessage<T = any>(msg: T): T;
+	ensureString(o: any): string;
+	ensureBuffer(o: any): Buffer;
+	compareObjects(obj1: any, obj2: any): boolean;
+	getMessageProperty(msg: any, expr: string): any;
+	setMessageProperty(msg: any, prop: string, value: any, createMissing?: boolean): void;
+	getObjectProperty(obj: any, expr: string): any;
+	setObjectProperty(obj: any, prop: string, value: any, createMissing?: boolean): void;
+	normalisePropertyExpression(str: string, msg?: any, toString?: boolean): string[];
+	normaliseNodeTypeName(name: string): string;
+	prepareJSONataExpression(value: string, node: any): any;
+	evaluateJSONataExpression(expr: any, msg: any, callback: (err: Error | null, result: any) => void): void;
+	parseContextStore(key: string): {
+		store: string | undefined;
+		key: string;
+	};
+	getSetting(node: any, name: string, flow?: any): any;
+	encodeObject(obj: any): any;
+}
+interface NodeRedHooks {
+	add(hookId: string, callback: (event: any) => void | Promise<void>): void;
+	remove(hookId: string): void;
+	trigger(hookId: string, event: any, callback?: (err?: Error) => void): void | Promise<void>;
+	has(hookId: string): boolean;
+	clear(): void;
+}
+type NodeRedExpressApp = Express;
+interface RED {
+	/** Internationalization function */
+	_(key: string, substitutions?: Record<string, string>): string;
+	/** Logging API */
+	log: NodeRedLog;
+	/** Node registry and management */
+	nodes: NodeRedNodes;
+	/** Utility functions */
+	util: NodeRedUtil;
+	/** Hook system for message lifecycle and module events */
+	hooks: NodeRedHooks;
+	/** Runtime event emitter */
+	events: EventEmitter;
+	/** Express app for admin HTTP endpoints */
+	httpAdmin: NodeRedExpressApp;
+	/** Express app for node HTTP endpoints */
+	httpNode: NodeRedExpressApp;
+	/** Runtime settings (user-provided settings plus node-registered settings) */
+	settings: NodeRedRuntimeSettings & Record<string, any>;
+	/** Node-RED version string */
+	version(): string;
+}
+interface NodeRedContextStore {
+	get(key: string, store: string | undefined, callback: (err: Error | null, value: any) => void): void;
+	set(key: string, value: any, store: string | undefined, callback: (err: Error | null) => void): void;
+	keys(store: string | undefined, callback: (err: Error | null, keys: string[]) => void): void;
+}
+type Schema<T extends TProperties = TProperties> = TObject<T>;
+interface NodeContextStore {
+	get<T = any>(key: string): Promise<T>;
+	set<T = any>(key: string, value: T): Promise<void>;
+	keys(): Promise<string[]>;
+}
+interface NodeConstructor<T = any, TConfig = any, TCredentials = any> {
+	readonly type: string;
+	readonly category: string;
+	readonly color?: string;
+	readonly align?: "left" | "right";
+	readonly inputs?: number;
+	readonly outputs?: number;
+	readonly configSchema?: Schema;
+	readonly credentialsSchema?: Schema;
+	readonly settingsSchema?: Schema;
+	readonly inputSchema?: Schema;
+	readonly outputsSchema?: TSchema | TSchema[] | Record<string, TSchema>;
+	readonly validateInput?: boolean;
+	readonly validateOutput?: boolean;
+	readonly name: string;
+	registered?(RED: RED): void | Promise<void>;
+	register(RED: RED): void | Promise<void>;
+	validateSettings(RED: RED): void;
+	new (RED: RED, node: NodeRedNode, config: NodeConfig<TConfig>, credentials: NodeCredentials<TCredentials>): T;
+}
+type NodeConfig<TConfig = any> = TConfig & Static<typeof NodeConfigSchema>;
+type NodeCredentials<TCredentials = any> = TCredentials;
+interface INode<TConfig = any, TCredentials = any, TSettings = any> {
+	readonly config: NodeConfig<TConfig>;
+	readonly id: string;
+	readonly name: string | undefined;
+	readonly z: string | undefined;
+	readonly credentials: NodeCredentials<TCredentials> | undefined;
+	readonly settings: TSettings;
+	i18n(key: string, substitutions?: Record<string, string>): string;
+	setTimeout(fn: () => void, ms: number): NodeJS.Timeout;
+	setInterval(fn: () => void, ms: number): NodeJS.Timeout;
+	clearTimeout(timer: NodeJS.Timeout): void;
+	clearInterval(interval: NodeJS.Timeout): void;
+	on(event: string, callback: (...args: any[]) => void): void;
+	log(msg: any): void;
+	warn(message: string): void;
+	error(message: string, msg?: any): void;
+	created?(): void | Promise<void>;
+	closed?(removed?: boolean): void | Promise<void>;
+}
+type Channel = "sent" | "received";
+declare class Recorder {
+	#private;
+	recordSent(id: string, port: number, msg: unknown): void;
+	recordReceived(id: string | undefined, msg: unknown): void;
+	/** Snapshot of all messages on a channel for a node (optionally one port). */
+	snapshot(channel: Channel, id: string, port?: number): unknown[];
+	/** Resolve the message at `index` on a channel, awaiting it if not yet seen. */
+	next(channel: Channel, id: string, port: number | undefined, index: number, timeoutMs: number): Promise<unknown>;
+	clear(): void;
+}
+interface NodeContext {
+	node: NodeContextStore;
+	flow: NodeContextStore;
+	global: NodeContextStore;
+}
+export interface AddNodeOptions {
+	/** Override the generated node id. */
+	id?: string;
+	/** Node name (the `name` field). */
+	name?: string;
+	/** Credentials for the node (stored by the runtime, exposed as `this.credentials`). */
+	credentials?: Record<string, unknown>;
+}
+export interface ReadOptions {
+	/** Reject if no message arrives within this many ms. @default 5000 */
+	timeout?: number;
+}
+/**
+ * A handle to one node in a deployed flow. Wraps a generated id; the live
+ * instance lives inside the runtime, so harness methods (`receive`/`read`/…)
+ * never collide with the node's own methods.
+ */
+export declare class NodeRef {
+	#private;
+	readonly id: string;
+	readonly type: string;
+	readonly isConfig: boolean;
+	readonly name: string;
+	readonly config: Record<string, unknown>;
+	readonly credentials?: Record<string, unknown>;
+	readonly wires: string[][];
+	constructor(flow: Flow, type: string, isConfig: boolean, config: Record<string, unknown>, opts: AddNodeOptions);
+	/** Wire this node's output `port` to `target`'s input. */
+	wire(target: NodeRef, port?: number): this;
+	/** Deliver a message to this node's input (Node-RED's upstream path). */
+	receive(msg: unknown): Promise<void>;
+	/** Snapshot of everything this node has emitted (optionally one port). */
+	sent(port?: number): unknown[];
+	/** Snapshot of everything delivered to this node's input. */
+	received(port?: number): unknown[];
+	/**
+	 * Promise-based access to this node's context stores (`node` / `flow` /
+	 * `global`) — preset values before `receive`, and assert them afterward.
+	 */
+	get context(): NodeContext;
+	/**
+	 * Consume the next un-read message this node emitted (FIFO cursor), awaiting
+	 * it if not yet sent. Call repeatedly to walk multiple emissions.
+	 */
+	read(port?: number, opts?: ReadOptions): Promise<unknown>;
+}
+/**
+ * Builds a flow from nrg node classes and deploys it into a running runtime.
+ * Use `addNode` for every node — config nodes included.
+ */
+export declare class Flow {
+	#private;
+	readonly recorder: Recorder;
+	constructor(RED: NodeRedApi, recorder: Recorder);
+	/** Add any node — regular or config (detected via `category === "config"`). */
+	addNode(Cls: NodeConstructor, config?: Record<string, unknown>, opts?: AddNodeOptions): NodeRef;
+	/** Build the flow JSON and deploy it; resolves once the flow has started. */
+	deploy(): Promise<void>;
+	/** Drop the built nodes and clear captured messages (reset between tests). */
+	clear(): Promise<void>;
+	runtimeNode(id: string): RuntimeNode | null;
+}
+export interface StartRuntimeOptions {
+	/** Node classes (IONode / ConfigNode subclasses) to register in the runtime. */
+	nodes: NodeConstructor[];
+	/** Extra Node-RED settings merged over the headless defaults. */
+	settings?: Record<string, unknown>;
+}
+/**
+ * Boot a real, in-process Node-RED runtime with the given node types
+ * registered. One runtime per test file (the runtime is a process-wide
+ * singleton); each test deploys a flow into it and `flow.clear()`s between.
+ */
+export declare function startRuntime(options: StartRuntimeOptions): Promise<Runtime>;
+export declare class Runtime {
+	#private;
+	constructor(RED: NodeRedApi, server: http.Server, userDir: string, recorder: Recorder);
+	/** Start a fresh flow to build, deploy, drive and inspect. */
+	flow(): Flow;
+	/** Stop Node-RED, close the server and remove the temp user dir. */
+	stop(): Promise<void>;
+}
+interface NodeRedApi {
+	init(server: http.Server, settings: Record<string, unknown>): void;
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	hooks: {
+		add(name: "onReceive", fn: (event: {
+			destination?: {
+				id?: string;
+			};
+			msg: unknown;
+		}) => void): void;
+	};
+	nodes: {
+		getNode(id: string): RuntimeNode | null;
+	};
+	events: {
+		on(event: string, fn: (...args: unknown[]) => void): void;
+		removeListener(event: string, fn: (...args: unknown[]) => void): void;
+	};
+	runtime: {
+		flows: {
+			setFlows(opts: {
+				flows: {
+					flows: unknown[];
+				};
+				deploymentType?: string;
+			}): Promise<{
+				rev: string;
+			}>;
+		};
+	};
+}
+interface RuntimeNodeContext extends NodeRedContextStore {
+	flow: NodeRedContextStore;
+	global: NodeRedContextStore;
+}
+interface RuntimeNode {
+	id: string;
+	type: string;
+	receive(msg: unknown): void;
+	send(msg: unknown): void;
+	context(): RuntimeNodeContext;
+}
+
+export {};

package/types/test-server-unit.d.ts

@@ -203,6 +203,11 @@ declare const NodeConfigSchema: import("@sinclair/typebox").TObject<{
 	z: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 type Schema<T extends TProperties = TProperties> = TObject<T>;
+interface NodeContextStore {
+	get<T = any>(key: string): Promise<T>;
+	set<T = any>(key: string, value: T): Promise<void>;
+	keys(): Promise<string[]>;
+}
 interface NodeConstructor<T = any, TConfig = any, TCredentials = any> {
 	readonly type: string;
 	readonly category: string;
@@ -409,6 +414,13 @@ interface TestNodeHelpers<TInput = any, TOutput = any> {
 	logged(level?: "info" | "warn" | "error" | "debug"): string[];
 	warned(): string[];
 	errored(): string[];
+	/** Promise-based access to the node's context stores (node / flow / global). */
+	context: TestNodeContext;
+}
+interface TestNodeContext {
+	node: NodeContextStore;
+	flow?: NodeContextStore;
+	global: NodeContextStore;
 }
 interface CreateNodeResult<T> {
 	node: T & TestNodeHelpers<ExtractInput<T>, ExtractOutput<T>>;