@bonsae/nrg 0.19.0 → 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.
@@ -36,10 +39,10 @@ Installing `node-red` as a dev dependency is recommended for fast, reliable dev
 
 ```typescript
 import { defineConfig } from "vite";
-import { nodeRed } from "@bonsae/nrg/vite";
+import { nrg } from "@bonsae/nrg/vite";
 
 export default defineConfig({
-  plugins: [nodeRed()],
+  plugins: [nrg()],
 });
 ```
 
@@ -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.0",
+  "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

@@ -2191,7 +2191,7 @@ async function compileRuntimeSettingsFile(runtimeSettingsFilepath, port) {
   return compiledRuntimeSettingsFilepath;
 }
 async function generateRuntimeSettings(options) {
-  const { outDir, port, settingsFilepath, httpAdminRoot, logger: logger2 } = options;
+  const { outDir, port, settingsFilepath, logger: logger2 } = options;
   const tempFiles = [];
   const userRuntimeSettingsFilepath = findUserRuntimeSettingsFilepath(
     settingsFilepath,
@@ -2210,17 +2210,13 @@ async function generateRuntimeSettings(options) {
   const userDir = path11.resolve(cwd, ".node-red").split(path11.sep).join("/");
   const userDirLiteral = JSON.stringify(userDir);
   const outDirLiteral = JSON.stringify(normalizedOutDir);
-  const httpAdminRootAssignment = httpAdminRoot ? `settings.httpAdminRoot = ${JSON.stringify(httpAdminRoot)};
-` : "";
-  const httpAdminRootEntry = httpAdminRoot ? `
-  httpAdminRoot: ${JSON.stringify(httpAdminRoot)},` : "";
   const finalRuntimeSettingsFile = compiledRuntimeSettingsFilepath ? `
 const compiledRuntimeSettings = require(${JSON.stringify(
     compiledRuntimeSettingsFilepath.split(path11.sep).join("/")
   )});
 const settings = compiledRuntimeSettings.default || compiledRuntimeSettings;
 settings.uiPort = ${port};
-${httpAdminRootAssignment}if(!settings.userDir){
+if(!settings.userDir){
     settings.userDir = ${userDirLiteral};
 }
 settings.nodesDir = settings.nodesDir || [];
@@ -2242,7 +2238,7 @@ const settings = {
   uiPort: ${port},
   userDir: ${userDirLiteral},
   flowFile: "flows.json",
-  nodesDir: [${outDirLiteral}],${httpAdminRootEntry}
+  nodesDir: [${outDirLiteral}],
   // the welcome tour overlay intercepts pointer events \u2014 fatal for e2e
   editorTheme: { tours: false },
 };
@@ -2396,12 +2392,10 @@ var NodeRedLauncher = class {
   port = null;
   outDir;
   options;
-  _slug;
   logger;
-  constructor(outDir, options, slug = "") {
+  constructor(outDir, options) {
     this.outDir = outDir;
     this.options = options;
-    this._slug = slug;
     this.logger = new Logger({
       name: "vite-plugin-node-red",
       prefix: "node-red"
@@ -2410,12 +2404,6 @@ var NodeRedLauncher = class {
   get preferredPort() {
     return this.options.runtime?.port ?? 1880;
   }
-  get slug() {
-    return this._slug;
-  }
-  get basePath() {
-    return this._slug ? `/${this._slug}/` : "/";
-  }
   get restartDelay() {
     return this.options.restartDelay ?? 1e3;
   }
@@ -2496,7 +2484,6 @@ var NodeRedLauncher = class {
         outDir: this.outDir,
         port: this.port,
         settingsFilepath: this.options.runtime?.settingsFilepath,
-        httpAdminRoot: this._slug ? this.basePath : void 0,
         logger: this.logger
       });
       for (const file of settings.tempFiles) {
@@ -2680,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
+};