{"id":11447,"library":"node-red-node-test-helper","title":"Node-RED Node Test Helper","description":"The Node-RED Node Test Helper is a comprehensive framework designed for unit testing Node-RED nodes and flows. It enables developers to start a dedicated Node-RED runtime instance within their test environment, load specific test flows, and simulate message injection and reception to verify node behavior. The current stable version is 0.3.6, with regular maintenance updates including dependency bumps and minor feature enhancements. This helper differentiates itself by integrating directly with the Node-RED runtime, providing a realistic testing environment that goes beyond simple JavaScript unit tests, ensuring nodes function correctly within the flow-based programming paradigm. It is an essential tool for maintaining the quality and reliability of custom Node-RED nodes.","status":"active","version":"0.3.6","language":"javascript","source_language":"en","source_url":"https://github.com/node-red/node-red-node-test-helper","tags":["javascript","test","iot","node-red"],"install":[{"cmd":"npm install node-red-node-test-helper","lang":"bash","label":"npm"},{"cmd":"yarn add node-red-node-test-helper","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-red-node-test-helper","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for the test helper to start and interact with the Node-RED runtime.","package":"node-red","optional":false}],"imports":[{"note":"The module exports a default object containing all helper functions. While primarily CommonJS, it can be imported as a default ESM module.","wrong":"import { helper } from 'node-red-node-test-helper';","symbol":"helper","correct":"import helper from 'node-red-node-test-helper';"},{"note":"CommonJS import style, widely used in existing Node-RED node projects and examples.","symbol":"require ('node-red-node-test-helper')","correct":"const helper = require('node-red-node-test-helper');"},{"note":"The `init` function must be called with the path to the Node-RED runtime, typically found via `require.resolve('node-red')`.","wrong":"helper.init();","symbol":"init","correct":"helper.init(require.resolve('node-red'));"}],"quickstart":{"code":"import helper from 'node-red-node-test-helper';\nimport should from 'should';\nimport path from 'path';\n\n// Assuming your node is in ../my-awesome-node.js relative to the test file\nconst myAwesomeNode = require(path.resolve(__dirname, '../my-awesome-node.js'));\n\n// Initialize the helper to locate the Node-RED runtime\nhelper.init(require.resolve('node-red'));\n\ndescribe('My Awesome Node', function () {\n\n  beforeEach(async function () {\n      await helper.startServer();\n  });\n\n  afterEach(async function () {\n      await helper.unload();\n      await helper.stopServer();\n  });\n\n  it('should be loaded correctly', async function () {\n    const flow = [{ id: 'n1', type: 'my-awesome-node', name: 'test node' }];\n    await helper.load(myAwesomeNode, flow);\n    const n1 = helper.getNode('n1');\n    n1.should.have.property('name', 'test node');\n  });\n\n  it('should process input and send expected output', async function () {\n    const flow = [\n      { id: 'n1', type: 'my-awesome-node', name: 'test node', wires:[['n2']] },\n      { id: 'n2', type: 'helper' }\n    ];\n    await helper.load(myAwesomeNode, flow);\n    const n2 = helper.getNode('n2');\n    const n1 = helper.getNode('n1');\n\n    const promise = new Promise((resolve, reject) => {\n      n2.on('input', function (msg) {\n        try {\n          msg.should.have.property('payload', 'processed value');\n          resolve();\n        } catch(err) {\n          reject(err);\n        }\n      });\n    });\n\n    n1.receive({ payload: 'initial value' });\n    await promise;\n  });\n});","lang":"javascript","description":"This quickstart demonstrates how to set up a basic unit test for a custom Node-RED node, loading a flow, injecting messages, and asserting the output, including proper asynchronous handling."},"warnings":[{"fix":"Upgrade your Node.js environment to version 14 or later. For example, use `nvm install 18 && nvm use 18`.","message":"Version 0.3.0 and above of `node-red-node-test-helper` requires Node.js version 14 or higher. Running tests with older Node.js versions will result in runtime errors.","severity":"breaking","affected_versions":">=0.3.0"},{"fix":"Wrap assertions in `try...catch` blocks and call `done(err)` or `reject(err)` on failure. When using async/await, ensure the promise rejects on error as shown in the quickstart example.","message":"Node-RED runtime inherently swallows exceptions that occur within a flow. When writing unit tests, assertion failures inside `n2.on('input', ...)` callbacks will not automatically fail the test; they will simply cause a timeout. You must explicitly catch errors and pass them to your test runner's `done` callback or reject a Promise.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install both packages together as dev dependencies: `npm install node-red-node-test-helper node-red --save-dev`.","message":"The `node-red` package is a peer dependency and must be installed alongside `node-red-node-test-helper`. Failure to do so will result in `Cannot find module 'node-red'` errors during helper initialization.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refactor test setup and teardown hooks (e.g., `beforeEach`, `afterEach`) and test cases to use `async/await` with helper methods where appropriate, as demonstrated in the quickstart.","message":"Asynchronous methods like `startServer`, `stopServer`, `load`, and `setFlows` were updated in version 0.3.5 to be fully async/await compatible. While older synchronous calls might still function, it's best practice to `await` these operations in your tests to prevent race conditions and ensure proper test execution, especially with newer test runners like Vitest.","severity":"gotcha","affected_versions":">=0.3.5"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install node-red node-red-node-test-helper --save-dev` to ensure both packages are available in your project.","cause":"The `node-red` package, a peer dependency, has not been installed alongside `node-red-node-test-helper`.","error":"Error: Cannot find module 'node-red' from '<your-project-path>'"},{"fix":"Wrap assertions in a `try...catch` block and call `done(err)` on error, or `reject(err)` if using promises, to properly report failures and complete the test.","cause":"An assertion inside an asynchronous callback (e.g., `n2.on('input', ...)`) failed, but the error was not propagated, preventing `done()` from being called, or `done()` was never called.","error":"Test timeout of 2000ms exceeded. Ensure the done() callback is being called."},{"fix":"Ensure your test functions (e.g., `beforeEach`, `afterEach`, `it`) are declared `async` and use `await` before calling helper methods like `helper.startServer()`.","cause":"Attempting to call an asynchronous helper method without awaiting it in an `async` function, or potentially using an outdated version where the method signature changed.","error":"TypeError: helper.startServer is not a function (or similar for other async methods)"},{"fix":"Update your Node.js installation to version 14 or newer. You can use a tool like NVM (Node Version Manager) to manage multiple Node.js versions.","cause":"The current Node.js version in your environment is older than the minimum required by `node-red-node-test-helper` (and Node-RED itself since v0.3.0 of the helper).","error":"Node-RED requires Node.js version >= 14"}],"ecosystem":"npm"}