@gregoriusrippenstein/erlang-red-unittest 0.12.3 → 0.15.0

package/README.md

@@ -1,4 +1,4 @@
-## Unit testing nodes for Erlang-RED
+## Unit testing nodes for Erlang-Red and Node-RED
 
 Node-RED Nodes for testing flow correctness in the [Erlang-Red](https://github.com/gorenje/erlang-red) project.
 
@@ -38,6 +38,10 @@ This package also defines the following actions that can be mapped to keyboard s
 - Send Halt To Test Server: (Erlang-Red only) restarts the server
 - Run All Tests: (Erlang-Red only) run all defined unit tests.
 
+## Forum Discussions
+
+- [Flow testsuite for testing core node functionality - May 2025](https://discourse.nodered.org/t/flow-testsuite-for-testing-core-node-functionality/97106)
+
 ## Tee Time
 
 <a href="https://www.buymeacoffee.com/gorenje" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-red.png" alt="Buy Me A Tee" style="height: 42px !important;width: 152px !important;" ></a>

package/nodes/locales/en-US/ut-assert-success.html

@@ -1,6 +1,12 @@
 <script type="text/html" data-help-name="ut-assert-success">
-  <p>This node failes if, during flow execution, it is not reached.</p>
-  A success assertion meaning that this node **must** be reached when a flow is executed as part of a test.
+<p>This node failes if, during flow execution, it is not reached.</p>
+A success assertion meaning that this node <b>must</b> be reached when a flow is executed as part of a test.
 
+<p>
 If this node isn't reached, then the test will fail.
+</p>
+
+<p>
+A message count of zero is assumed to be <b>at least one message</b>, it's the same as minimum of one message.
+</p>
 </script>

package/nodes/locales/en-US/ut-assert-success.json

@@ -7,7 +7,13 @@
       "succeed": "assert succeed",
       "count": "Msg Count",
       "unsupported": "Unsupported",
-      "failed": "assert failed"
+      "failed": "assert failed",
+      "messages": "Msgs",
+      "limit": {
+        "upperlimit" : "Max",
+        "exactly": "Exactly",
+        "lowerlimit": "Min"
+      }
     },
 
     "status": {

package/nodes/ut-assert-debug.js

@@ -5,34 +5,418 @@ module.exports = function(RED) {
     var node = this;
     var cfg = config;
 
-    node.on('close', function() {
-      node.status({});
+    node.on('close', function (removed, done) {
+      if (removed) {
+        node.status({});
+      } else {
+        // use node.log(..) here because node.error(..) sends a message to the debug
+        // panel but that errors out because the frontend can't find the workspace:
+        //    Uncaught TypeError: can't access property "label", RED.nodes.workspace(...) is undefined
+        // that has follow-on effects.
+        node.log(`UNSUPPORTED [${node.z}] debug is not supported`)
+      }
+      done()
     });
 
     /* msg handler, in this case pass the message on unchanged */
     node.on("input", function(msg, send, done) {
-        // How to send a status update
-        node.status({ fill: "green", shape: "ring", text: RED._("ut-assert-debug.label.statusset") });
-
-        // Send a message and how to handle errors.
+      // How to send a status update
+      node.status({ fill: "green", shape: "ring", text: RED._("ut-assert-debug.label.statusset") });
+      setTimeout(() => { node.status({}); }, 1000)
+      
+      // Send a message and how to handle errors.
+      try {
         try {
-          try {
-            send(msg);
-            done();
-          } catch ( err ) {
-            // use node.error if the node might send subsequent messages
-            node.error("error occurred", { ...msg, error: err })
-            done();
-          }
-        } catch (err) {
-          // use done if the node won't send anymore messages for the
-          // message it received.
-          msg.error = err
-          done(err.message, msg)
+          send(msg);
+          done();
+        } catch ( err ) {
+          // use node.error if the node might send subsequent messages
+          node.error("error occurred", { ...msg, error: err })
+          done();
         }
+      } catch (err) {
+        // use done if the node won't send anymore messages for the
+        // message it received.
+        msg.error = err
+        done(err.message, msg)
+      }
     });
   }
 
   RED.nodes.registerType("ut-assert-debug", Coreut_assert_debugFunctionality);
 
+  // Backend endpoints
+RED.httpAdmin.get("/UnitTesting/:flowid/runtest",
+  (req, res) => {
+    const path = require('path');
+    const fs = require('fs')
+    const jsonClone = require("rfdc")();
+    
+    // API defined here --> https://github.com/node-red/node-red/blob/master/packages/node_modules/%40node-red/runtime/lib/index.js
+    const runtime = require("@node-red/runtime");
+
+    let testDir = path.resolve(path.dirname(__filename), "..", "testflows")
+
+    // if a test generates an uncaught exception, then captcha that and generate
+// a failure - tests are considered failed if they generate uncaught exceptions/errors.
+let createExtraCatchNode = () => {
+  let changeId = runtime.util.generateId()
+  let assertId = runtime.util.generateId()
+  let debugId = runtime.util.generateId()
+
+  return [
+    {
+      "id": runtime.util.generateId(),
+      "type": "catch",
+      "name": "",
+      "scope": null,
+      "uncaught": true,
+      "wires": [
+        [
+          changeId
+        ]
+      ]
+    },
+    {
+      "id": changeId,
+      "type": "change",
+      "name": "",
+      "rules": [
+        {
+          "t": "set",
+          "p": "_unittest_triggered",
+          "pt": "msg",
+          "to": "true",
+          "tot": "bool"
+        }
+      ],
+      "action": "",
+      "property": "",
+      "from": "",
+      "to": "",
+      "reg": false,
+      "wires": [
+        [
+          assertId,
+          debugId
+        ]
+      ]
+    },
+    {
+      "id": debugId,
+      "type": "debug",
+      "name": "",
+      "active": true,
+      "tosidebar": false,
+      "console": true,
+      "tostatus": false,
+      "complete": "payload",
+      "targetType": "msg",
+      "statusVal": "",
+      "statusType": "auto",
+      "wires": []
+    },
+    {
+      "id": assertId,
+      "type": "ut-assert-failure",
+      "name": "",
+      "wires": []
+    }
+  ]
+}
+
+let isTestPending = (tabDetails) => {
+  return tabDetails.env.filter(d => d.name == "NRED_PENDING")[0]?.value == "true"
+}
+
+// chunkify an array into chunks of `size` size
+let chunkify = (array, size) => {
+  const chunkedArray = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunkedArray.push(array.slice(i, i + size));
+  }
+  return chunkedArray;
+}
+
+// respond to request with a list of total tests to be done. The frontend then
+// shows a progress indication of success / pending / failure
+let respondWithCount = (res, count) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ status: "ok", todo: count }));
+}
+
+
+    if (req.params.flowid == "all") {
+      //
+      // Run all tests. This is a little more complicated as this runs all tests in batches
+      // of ten tests at a time but these have to be added in serial and also removed in 
+      // serial, so there has to be promise handling ... and that makes this stuff a little
+      // more complicated.
+      //
+
+      let allTests = fs.globSync(`${testDir}/**/*.json`)
+
+      // if a limit (i.e. a list of testFlow ids) is provided, only peform those tests.
+      if (req.query.limit) {
+        let testIds = req.query.limit.split(",")
+
+        allTests = allTests.filter( filename => {
+          let origFlowId = path.basename(path.parse(filename).dir)
+          return testIds.indexOf(origFlowId) > -1
+        })
+      }
+
+      let chunkedFilenames = chunkify(allTests, 10)
+
+      respondWithCount(res, allTests.length)
+
+      let runTestsForFileNames = (fileIdx) => {
+        if (fileIdx >= chunkedFilenames.length) { return }
+
+        // test all is a multi step process, first we have to add all flows to the main show
+        // then we have to trigger them and finally we have to remove those that weren't
+        // there in the first place.
+        let flowIdsToBeRemoved = []
+        let injNodesToBeTriggered = {}
+
+        let timeoutValues = []
+
+        let flowsToAdd = chunkedFilenames[fileIdx].map((filename) => {
+          
+          let origFlowId = path.basename(path.parse(filename).dir)
+
+          let flowDetails = JSON.parse(fs.readFileSync(filename))
+          let tabDetails = flowDetails.filter(d => d.type == "tab")[0]
+          let injNodesIds = flowDetails.filter(d => d.type == "inject").map(d => d.id)
+          
+          RED.log.debug(`unittest: adding test case [${origFlowId}] - '${tabDetails.label}'`)
+
+          if (isTestPending(tabDetails) && req.query["testpend"] != "true") {
+            RED.comms.publish("unittesting:testresults", {
+              flowid: origFlowId,
+              status: "pending"
+            })
+            return null
+          }
+
+          // compute any timeout that is defined for the flow test
+          tabDetails.env.filter(d => d.name == "NRED_TIMEOUT").forEach( d => {
+            timeoutValues.push(parseInt(d.value) * 1000)
+          })
+
+          // add an catch all and trigger a assert false if any exceptions are
+          // raised by the test - if there isn't already a catch all node.
+          if (flowDetails.filter(d => d.type == "catch").filter(d => d.scope == null).length == 0) {
+            flowDetails = flowDetails.concat(createExtraCatchNode())
+          }
+
+          if (runtime._.flows.getFlow(origFlowId)) {
+            injNodesToBeTriggered[origFlowId] = injNodesIds.map(d => d)
+            return null
+          } else {
+            return {
+              injNodesIds: injNodesIds, origFlowId: origFlowId, nodes: flowDetails
+            }
+          }
+        }).filter(d => !!d)
+
+        // addFlow is a promise but I want to add flows in series not parallel, so the
+        // promise returns a promise that adds the next flow after the initial flow
+        // has been added. It's promises all the way down - until the turtles start.
+        let addFlow = (idx) => {
+          if (idx >= flowsToAdd.length) { return }
+          var { injNodesIds, origFlowId, nodes } = flowsToAdd[idx]
+
+          var newConfig = jsonClone(runtime._.flows.getFlows().flows);
+          newConfig = newConfig.concat(nodes);
+
+          return runtime._.flows.setFlows(newConfig, null, 'flows', false, null, "root")
+            .then(() => {
+              let newFlowId = origFlowId
+              injNodesToBeTriggered[newFlowId] = injNodesIds.map(d => d)
+              flowIdsToBeRemoved.push(newFlowId)
+            })
+            .catch(e => { RED.log.error(e); RED.log.error(`Exception happened with ${origFlowId}`) })
+            .finally(() => addFlow(idx + 1))
+        }
+
+        Promise.all([addFlow(0)]).then(() => {
+          RED.log.debug("unittest: done adding all flows")
+
+          runtime._.flows.startFlows("full", null, false, true).then(d => {
+            Object.keys(injNodesToBeTriggered).forEach(flowId => {
+              injNodesToBeTriggered[flowId].forEach(ndeId => {
+                RED.log.debug(`unittest: triggering inject node: ${ndeId}`)
+                RED.nodes.getNode(ndeId)?.receive({"_unittest_triggered": true})
+              })
+            })
+
+            let removeFlow = (idx) => {
+              if (idx >= flowIdsToBeRemoved.length) { return }
+              let flowid = flowIdsToBeRemoved[idx]
+
+              return runtime._.flows.removeFlow(flowid, "root")
+                .then((_ignore) => {
+                  RED.comms.publish("unittesting:testresults", {
+                    flowid: flowid,
+                    status: "stopped"
+                  })
+                })
+                .catch(e => {
+                  RED.log.error(e);
+                  RED.log.error(`Error happened removing flow ${flowid}`)
+                  RED.comms.publish("unittesting:testresults", {
+                    flowid: flowid,
+                    status: "stopped"
+                  })
+                })
+                .finally(() => removeFlow(idx + 1))
+            }
+
+            setTimeout(() => {
+              Promise.all([removeFlow(0)]).then(() => {
+                RED.log.debug("unittest: removed all flows")
+                runTestsForFileNames(fileIdx+1)
+              })
+            }, Math.max(...(timeoutValues.concat([5000]))))
+          })
+        })
+      }
+      runTestsForFileNames(0)
+    } else {
+
+      //
+      // run a single unit test but ensure that the test case does exist on disk
+      //
+
+      respondWithCount(res, 1)
+
+      fs.globSync(`${testDir}/**/*.json`).filter(d => d.includes(req.params.flowid)).forEach(filename => {
+        let flowDetails = JSON.parse(fs.readFileSync(filename))
+        let origFlowId = req.params.flowid
+
+        let tabDetails = flowDetails.filter(d => d.type == "tab")[0]
+        let injNodesIds = flowDetails.filter(d => d.type == "inject").map(d => d.id)
+
+        let timeoutValues = []
+
+        if (isTestPending(tabDetails) && req.query["testpend"] != "true") {
+          RED.comms.publish("unittesting:testresults", {
+            flowid: origFlowId,
+            status: "pending"
+          })
+          return null
+        }
+
+        // compute any timeout that is defined for the flow test
+        tabDetails.env.filter(d => d.name == "NRED_TIMEOUT").forEach(d => {
+          timeoutValues.push(parseInt(d.value) * 1000)
+        })
+        
+        // add an catch all and trigger a assert false if any exceptions are
+        // raised by the test - if there isn't already a catch all node.
+        if (flowDetails.filter(d => d.type == "catch").filter(d => d.scope == null).length == 0) {
+          flowDetails = flowDetails.concat(createExtraCatchNode())
+        }
+
+        // if flow already exists, then just trigger the inject nodes
+        if (runtime._.flows.getFlow(origFlowId)) {
+          setTimeout(() => {
+            injNodesIds.forEach(ndeId => {
+              RED.nodes.getNode(ndeId)?.receive({"_unittest_triggered": true})
+            })
+          }, 500)
+
+          setTimeout(() => {
+            // tell the frontend that we've done with the test. If no 
+            // status has been posted for the unit test, then it succeeds.                
+            RED.comms.publish("unittesting:testresults", {
+              flowid: origFlowId,
+              status: "stopped"
+            })
+          }, Math.max(...(timeoutValues.concat([5000]))))
+        } else {
+          var newConfig = jsonClone(runtime._.flows.getFlows().flows);
+          newConfig = newConfig.concat(flowDetails);
+
+          runtime._.flows.setFlows(newConfig, null, 'flows', false, null, "root").then(() => {
+            runtime._.flows.startFlows("full", null, false, true).then(d => {
+              setTimeout(() => {
+                injNodesIds.forEach(ndeId => {
+                  RED.nodes.getNode(ndeId)?.receive({"_unittest_triggered": true})
+                })
+              }, 500)
+
+              setTimeout(() => {
+                runtime._.flows.removeFlow(origFlowId, "root").then(result => {
+                  // tell the frontend that we've done with the test. If no 
+                  // status has been posted for the unit test, then it succeeds.                
+                  RED.comms.publish("unittesting:testresults", {
+                    flowid: origFlowId,
+                    status: "stopped"
+                  })
+                })
+              }, Math.max(...(timeoutValues.concat([5000]))))
+            })
+          })
+        }
+      })
+    }
+  });
+
+RED.httpAdmin.get("/UnitTesting/halt",
+  (req, res) => {
+    var runtime = require("@node-red/runtime");
+    runtime._.flows.stopFlows()
+    res.sendStatus(200);
+  });
+
+RED.httpAdmin.get("/UnitTesting/:flowid/retrieve",
+  (req, res) => {
+    const path = require('path');
+    const fs = require('fs')
+
+    let fileName = path.resolve(path.dirname(__filename), "..", "testflows", req.params.flowid, "flows.json")
+    const data = fs.readFileSync(fileName);
+
+    try {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ flowdata: JSON.parse(data) }));
+    } catch (err) {
+      res.sendStatus(500);
+    }
+  });
+
+RED.httpAdmin.get("/UnitTesting/tests.json",
+  (req, res) => {
+    let testData = {
+      "status": "ok",
+      "last_updated_at": "2025-04-09T14:54:01.665Z",
+      "data": {
+      }
+    }
+
+    const path = require('path');
+    const fs = require('fs')
+
+    let testDir = path.resolve(path.dirname(__filename), "..", "testflows")
+
+    fs.globSync(`${testDir}/**/*.json`).forEach(filename => {
+      let details = path.parse(filename)
+      const data = fs.readFileSync(filename);
+
+      testData.data[path.basename(details.dir)] = {
+        "id": path.basename(details.dir),
+        "name": JSON.parse(data).filter(d => d.type == "tab")[0].label
+      }
+    })
+
+    try {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(testData));
+    } catch (err) {
+      res.sendStatus(500);
+    }
+  });
+
 }

package/nodes/ut-assert-failure.js

@@ -1,35 +1,46 @@
-module.exports = function(RED) {
+module.exports = function (RED) {
   function CoreutassertfailureFunctionality(config) {
-    RED.nodes.createNode(this,config);
+    RED.nodes.createNode(this, config);
 
     var node = this;
     var cfg = config;
 
-    node.on('close', function() {
+    node.on('close', function () {
       node.status({});
     });
 
     /* msg handler, in this case pass the message on unchanged */
-    node.on("input", function(msg, send, done) {
+    node.on("input", function (msg, send, done) {
 
-       node.status({ fill: "red", shape: "dot", text: RED._("ut-assert-failure.label.failed") });
+      RED.comms.publish("unittesting:testresults", {
+        flowid: node.z,
+        status: "failed"
+      })
 
-        // Send a message and how to handle errors.
+      // use node.log(..) here because node.error(..) sends a message to the debug
+      // panel but that errors out because the frontend can't find the workspace:
+      //    Uncaught TypeError: can't access property "label", RED.nodes.workspace(...) is undefined
+      // that has follow-on effects.
+      // see https://nodered.org/docs/creating-nodes/node-js#logging-events for more details
+      node.log(`FAILED [${node.z}] assert failure was sent a message`, msg)
+      node.status({ fill: "red", shape: "dot", text: RED._("ut-assert-failure.label.failed") });
+
+      // Send a message and how to handle errors.
+      try {
         try {
-          try {
-            send(msg);
-            done();
-          } catch ( err ) {
-            // use node.error if the node might send subsequent messages
-            node.error("error occurred", { ...msg, error: err })
-            done();
-          }
+          send(msg);
+          done();
         } catch (err) {
-          // use done if the node won't send anymore messages for the
-          // message it received.
-          msg.error = err
-          done(err.message, msg)
+          // use node.error if the node might send subsequent messages
+          node.error("error occurred", { ...msg, error: err })
+          done();
         }
+      } catch (err) {
+        // use done if the node won't send anymore messages for the
+        // message it received.
+        msg.error = err
+        done(err.message, msg)
+      }
     });
   }
 

package/nodes/ut-assert-status.js

@@ -5,31 +5,41 @@ module.exports = function(RED) {
     var node = this;
     var cfg = config;
 
-    node.on('close', function() {
-      node.status({});
+    node.on('close', function(removed, done) {
+      if ( removed) {
+        node.status({});
+      } else {
+        // use node.log(..) here because node.error(..) sends a message to the debug
+        // panel but that errors out because the frontend can't find the workspace:
+        //    Uncaught TypeError: can't access property "label", RED.nodes.workspace(...) is undefined
+        // that has follow-on effects.
+        node.log(`UNSUPPORTED [${node.z}] status is not supported`)
+      }
+      done()
     });
 
     /* msg handler, in this case pass the message on unchanged */
     node.on("input", function(msg, send, done) {
-        // How to send a status update
-        node.status({ fill: "green", shape: "ring", text: RED._("ut-assert-status.label.statusset") });
+      // How to send a status update
+      node.status({ fill: "green", shape: "ring", text: RED._("ut-assert-status.label.statusset") });
+      setTimeout(() => { node.status({}); }, 1000)
 
-        // Send a message and how to handle errors.
+      // Send a message and how to handle errors.
+      try {
         try {
-          try {
-            send(msg);
-            done();
-          } catch ( err ) {
-            // use node.error if the node might send subsequent messages
-            node.error("error occurred", { ...msg, error: err })
-            done();
-          }
-        } catch (err) {
-          // use done if the node won't send anymore messages for the
-          // message it received.
-          msg.error = err
-          done(err.message, msg)
+          send(msg);
+          done();
+        } catch ( err ) {
+          // use node.error if the node might send subsequent messages
+          node.error("error occurred", { ...msg, error: err })
+          done();
         }
+      } catch (err) {
+        // use done if the node won't send anymore messages for the
+        // message it received.
+        msg.error = err
+        done(err.message, msg)
+      }
     });
   }