Merge pull request #67 from SenseTecnic/npm-5-test

use npm install <folder> to test with npm 5, minor edits

Author: mblackstock

docs/creating-nodes/first-node.md

@@ -7,26 +7,26 @@ title: Creating your first node
 Nodes get created when a flow is deployed, they may send and receive some messages
 whilst the flow is running and they get deleted when the next flow is deployed.
 
-They consist of a pair of files; a JavaScript file that defines what the
+They typically consist of a pair of files; a JavaScript file that defines what the
 node does, and an html file that defines the node's properties, edit dialog and
 help text.
 
-When packaged as an npm module, a `package.json` file is used to pull it all together.
+A `package.json` file is used to package it all together as an npm module.
 
  - [Creating a simple node](#creating-a-simple-node)
    - [package.json](#package-json)
    - [lower-case.js](#lower-casejs)
    - [lower-case.html](#lower-casehtml)
  - [Testing your node in Node-RED](#testing-your-node-in-node-red)
 
-
 ### Creating a simple node
 
 This example will show how to create a node that converts message payloads to
 all lower-case characters.
 
-Create a directory where you will develop your code. Within that directory,
-create the following files:
+Ensure you have the recommended LTS version of Node.js installed on your system.  As of this writing this is version **LTS 8.x** which includes npm version 5.x.
+
+Create a directory where you will develop your code. Within that directory, create the following files:
 
  - `package.json`
  - `lower-case.js`
@@ -65,7 +65,7 @@ to the [packaging guide](packaging).
 
 <h4 id="lower-casejs"><i class="fa fa-file-o"></i> lower-case.js</h4>
 
-{% highlight javascript %}
+```javascript
 module.exports = function(RED) {
     function LowerCaseNode(config) {
         RED.nodes.createNode(this,config);
@@ -77,9 +77,9 @@ module.exports = function(RED) {
     }
     RED.nodes.registerType("lower-case",LowerCaseNode);
 }
-{% endhighlight %}
+```
 
-The node is wrapped as a node module. The module exports a function that gets called
+The node is wrapped as a Node.js module. The module exports a function that gets called
 when the runtime loads the node on start-up. The function is called with a single
 argument, `RED`, that provides the module access to the Node-RED runtime api.
 
@@ -106,7 +106,7 @@ For more information about the runtime part of the node, see [here](node-js).
 <h4 id="lower-casehtml"><i class="fa fa-file-o"></i> lower-case.html</h4>
 
 
-{% highlight html %}
+```html
 <script type="text/javascript">
     RED.nodes.registerType('lower-case',{
         category: 'function',
@@ -133,7 +133,7 @@ For more information about the runtime part of the node, see [here](node-js).
 <script type="text/x-red" data-help-name="lower-case">
     <p>A simple node that converts the message payloads into all lower-case characters</p>
 </script>
-{% endhighlight %}    
+```
 
 A node's HTML file provides the following things:
 
@@ -149,16 +149,85 @@ For more information about the editor part of the node, see [here](node-html).
 
 ### Testing your node in Node-RED
 
-Once you have created a basic node module as described above, you can install
-it into your Node-RED runtime.
+Once you have created a basic node module as described above, you can install it into your Node-RED runtime.
+
+To test a node module locally using npm 5.x, the [`npm install <folder>`](https://docs.npmjs.com/cli/install) command can be used. This allows you
+to develop the node in a local directory and have it linked into a local node-red install during development.
+
+In your node-red user directory, typically `~/.node-red`, run:
+
+    npm install <location of node module>
+
+For example, on Mac OS or linux, if your node is located at `~/dev/node-red-contrib-example-lower-case` you would type the following:
+
+    cd ~/.node-red
+    npm install ~/dev/node-red-contrib-example-lower-case
+
+This creates a symbolic link to your node module project directory in  `~/.node-red/node_modules` so that Node-RED will discover the node when it starts. Any changes to the node's file can be picked up by simply restarting Node-RED.  On Windows, again, using npm 5.x or greater:
+
+    cd C:\Users\my_name\.node_red
+    npm install C:\Users\my_name\Documents\GitHub\node-red-contrib-example-lower-case
+
+If you are using an older version of npm, you can create a symbolic link manually to your project.  For example, on Mac or linux systems:
+
+    cd ~/.node-red/node_modules
+    ln -s ~/dev/node-red-contrib-example-lower-case  .
+
+On Windows with older versions of npm, use `mklink` instead:
+
+    cd C:\Users\my_name\.node_red
+    mklink /D node_modules\node-red-contrib-example-lower-case C:\Users\my_name\Documents\GitHub\node-red-contrib-example-lower-case
+
+<div class="doc-callout">
+<em>Note</em>:  npm 5 will add your module as a dependency in the <code>package.json</code> file located in your user directory.  If you want to prevent this, use the npm <code>--no-save</code> option.
+</div>
+
+### Unit Testing
+
+To support unit testing, an npm module called [`node-red-node-test-helper`](https://www.npmjs.com/package/node-red-node-test-helper) can be used.  The test-helper is a framework built on the Node-RED runtime to make it easier to test nodes.
+
+Using this framework, you can create test flows, and then assert that your node properties and output is working as expected.  For example, to add a unit test to the lower-case node you can add a `test` folder to your node module package containing a file called `_spec.js`
+
+<h4><i class="fa fa-file-o"></i> test/_spec.js</h4>
+
+```javascript
+var should = require("should");
+var helper = require("node-red-test-helper");
+var lowerNode = require("../lower-case.js");
+
+describe('lower-case Node', function () {
+
+  afterEach(function () {
+    helper.unload();
+  });
+
+  it('should be loaded', function (done) {
+    var flow = [{ id: "n1", type: "lower-case", name: "test name" }];
+    helper.load(lowerNode, flow, function () {
+      var n1 = helper.getNode("n1");
+      n1.should.have.property('name', 'test name');
+      done();
+    });
+  });
+
+  it('should make payload lower case', function (done) {
+    var flow = [{ id: "n1", type: "lower-case", name: "test name",wires:[["n2"]] },
+    { id: "n2", type: "helper" }];
+    helper.load(lowerNode, flow, function () {
+      var n2 = helper.getNode("n2");
+      var n1 = helper.getNode("n1");
+      n2.on("input", function (msg) {
+        msg.should.have.property('payload', 'uppercase');
+        done();
+      });
+      n1.receive({ payload: "UpperCase" });
+    });
+  });
+});
+```
 
-To test a node module locally, the `npm link` command can be used. This allows you
-to develop the node in a local directory and have it linked into a local node-red
-install, as if it had been npm installed.
+These tests check to see that the node is loaded into the runtime correctly, and that it correctly changes the payload to lower case as expected.
 
-1. in the directory containing the node's `package.json` file, run: `sudo npm link`.
-2. in your node-red user directory, typically `~/.node-red` run: `npm link <name of node module>`.
+Both tests load the node into the runtime using `helper.load` supplying the node under test and a test flow  The first checks that the node in the runtime has the correct name property.  The second test uses a helper node to check that the output from the node is, in fact, lower case.
 
-This creates the appropriate symbolic links between the two directories so Node-RED
-will discover the node when it starts. Any changes to the node's file can be picked
-up by simply restarting Node-RED.
+The helper module contains other examples of tests taken from the Node-RED core nodes.  For more information on the helper module, see the associated README.