Registry / testing / node-red-node-test-helper

node-red-node-test-helper

library0.3.6jsnpmunverified

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.

testing

npm install node-red-node-test-helper

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-RED-NODE-TEST

node-red-node-test-helper

testingjavascriptv0.3.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

helper

✓ import helper from 'node-red-node-test-helper';

✗ import { helper } from 'node-red-node-test-helper';

The module exports a default object containing all helper functions. While primarily CommonJS, it can be imported as a default ESM module.

require ('node-red-node-test-helper')

✓ const helper = require('node-red-node-test-helper');

CommonJS import style, widely used in existing Node-RED node projects and examples.

init

✓ helper.init(require.resolve('node-red'));

✗ helper.init();

The `init` function must be called with the path to the Node-RED runtime, typically found via `require.resolve('node-red')`.

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.

import helper from 'node-red-node-test-helper'; import should from 'should'; import path from 'path'; // Assuming your node is in ../my-awesome-node.js relative to the test file const myAwesomeNode = require(path.resolve(__dirname, '../my-awesome-node.js')); // Initialize the helper to locate the Node-RED runtime helper.init(require.resolve('node-red')); describe('My Awesome Node', function () { beforeEach(async function () { await helper.startServer(); }); afterEach(async function () { await helper.unload(); await helper.stopServer(); }); it('should be loaded correctly', async function () { const flow = [{ id: 'n1', type: 'my-awesome-node', name: 'test node' }]; await helper.load(myAwesomeNode, flow); const n1 = helper.getNode('n1'); n1.should.have.property('name', 'test node'); }); it('should process input and send expected output', async function () { const flow = [ { id: 'n1', type: 'my-awesome-node', name: 'test node', wires:[['n2']] }, { id: 'n2', type: 'helper' } ]; await helper.load(myAwesomeNode, flow); const n2 = helper.getNode('n2'); const n1 = helper.getNode('n1'); const promise = new Promise((resolve, reject) => { n2.on('input', function (msg) { try { msg.should.have.property('payload', 'processed value'); resolve(); } catch(err) { reject(err); } }); }); n1.receive({ payload: 'initial value' }); await promise; }); });

Debug

Known issues

breakingVersion 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.

fix

Upgrade your Node.js environment to version 14 or later. For example, use `nvm install 18 && nvm use 18`.

affects: >=0.3.0

gotchaNode-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.

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.

affects: >=0.1.0

gotchaThe `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.

fix

Install both packages together as dev dependencies: `npm install node-red-node-test-helper node-red --save-dev`.

affects: >=0.1.0

gotchaAsynchronous 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.

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.

affects: >=0.3.5

Errors

Common errors & fixes

Error: Cannot find module 'node-red' from '<your-project-path>'

The `node-red` package, a peer dependency, has not been installed alongside `node-red-node-test-helper`.

fix

Run `npm install node-red node-red-node-test-helper --save-dev` to ensure both packages are available in your project.

Test timeout of 2000ms exceeded. Ensure the done() callback is being called.

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.

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.

TypeError: helper.startServer is not a function (or similar for other async methods)

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.

fix

Ensure your test functions (e.g., `beforeEach`, `afterEach`, `it`) are declared `async` and use `await` before calling helper methods like `helper.startServer()`.

Node-RED requires Node.js version >= 14

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).

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.

Upgrade

Version history

0.3.6latest on npm

Audit

Dependencies

node-redrequiredRequired as a peer dependency for the test helper to start and interact with the Node-RED runtime.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/node-red/node-red-node-test-helper ↗

packagehttps://www.npmjs.com/package/node-red-node-test-helper ↗

homepagehttps://nodered.org ↗