Setting up Node environment for Utility Library using ESDoc, Mocha+Chai and TDD approach

In this article we are going to:

1. Setup Node project using node package manager
2. Add Git ignore file
3. Setup Babel with related dependencies
4. Setup Mocha Test Framework and Chai Assertion Library
5. Implement First Test for MathHelper Utility
6. Setup ESDoc (documentation generator for JavaScript)
7. Create documentation for Utility Library

Create main directory, and setup node project using node package manager

mkdir helpers
cd ./helpers
npm init

After last command node package manager will ask for project configurations. You can skip that by clicking enter. We will update it manually.

It would be helpful to add git ignore file:

touch .gitignore

Inside of .gitignore file should be the following line of code:

node_modules/

Now lets go there a take a look on structure and initial package.json with .gitignore:

Now we need to setup Babel. Babel.js is JavaScript compiler (more details on Babel.js site). We will need it in order to use es6 feature, especially export/import functionality because on time when I’m creating this article ESDoc not supports node export/require.

Insert the following dev dependencies to your package.json and run in project directory npm install using terminal.

"devDependencies": {
  "babel-cli": "6.26.0",
  "babel-core": "6.26.0",
  "babel-preset-env": "1.6.0"
},

Next add Babel configuration file .babelrc
In terminal

touch .babelrc

Here is content:

{
  "presets": ["env"]
}

We are going to use TDD approach. It stands for Test-driven development.

From wikipedia:

Test-driven development (TDD) is a software development process that relies on the repetition of a very short development cycle: Requirements are turned into very specific test cases, then the software is improved to pass the new tests, only. This is opposed to software development that allows software to be added that is not proven to meet requirements.

Now we need some great test framework and as was mentioned previously we are going to use Mocha and also Assertion Library Chai (more details on Mocha and Chai site).

Firstly let’s add new dev dependencies to our package.json.

"devDependencies": {
  ...
  
  "chai": "3.5.0",
  "mocha": "3.1.2"
},

and run in terminal npm install.

Now we are ready to create first tests and try if all is working as expected.

Create src and specs folder in helpers directory
In terminal:

mkdir src && mkdir specs

In specs folder add file with name math-helper.spec.js with following content:

import { assert, expect } from 'chai';
import { MathHelper } from '../src/MathHelper.js';
describe('Math Helper Tests', () => {
  it('test add method', () => {
    assert.equal(4, MathHelper.add(2, 2));
  });
});

Here we are importing all needed dependencies and creating first test for MathHelper#add method. But do not rush to run it because for now it’s not working. Now we need to create our MathHelper class and implement .add() method inside.

So in src folder add file with name MathHelper.js and paste the following content:

export class MathHelper {
  static add(augend, addend) {
    return augend + addend;
  }
}

In order to run our test we need to add new npm command to scripts object inside of package.json file

"scripts": {
  "test-math-helper": "mocha --compilers js:babel-core/register ./specs/MathHelper.spec.js"
},

and run it in terminal

npm run test-math-helper

In your terminal you should see one test that was successfully passed.
Now let’s add few more tests:

import { assert, expect } from 'chai';
import { MathHelper } from '../src/MathHelper.js';
describe('Math Helper Tests', () => {
  it('test add method', () => {
    assert.equal(4, MathHelper.add(2, 2));
  });
  it('test subtract method', () => {
    assert.equal(2, MathHelper.subtract(4, 2));
  });
  it('test divide method', () => {
    assert.equal(2, MathHelper.divide(4, 2));
  });
  it('test multiply method', () => {
    assert.equal(4, MathHelper.multiply(2, 2));
  });
});

MathHelper class method Implementation:

export class MathHelper {
  static add(augend, addend) {
    return augend + addend;
  }
  static subtract(minuend, subtrahend) {
    return minuend - subtrahend;
  }
  static divide(dividend, divisor) {
    return dividend / divisor;
  }
  static multiply(multiplier, multiplicand) {
    return multiplier * multiplicand;
  }
}

And once again run it:

Great, all seems to be good:

Now will be the last part of current article.
Let’s create documentation for our awesome Math library. For that task we will choose a ESDoc documentation generator for JavaScript. (more details on ESDoc site)

Add new dependencies into package.json by running in terminal:

npm install esdoc esdoc-standard-plugin

create esdoc configuration file in root folder:

touch .esdoc.json

and content of .esdoc.json:

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    {
      "name": "esdoc-standard-plugin",
      "option": {
        "test": {
          "source": "./specs/",
          "interfaces": [
            "describe",
            "it",
            "context",
            "suite",
            "test"
          ],
          "includes": [
            "(spec|Spec|test|Test)\\.js$"
          ],
          "excludes": [
            "\\.config\\.js$"
          ]
        }
      }
    }
  ]
}

add README.md file

touch README.md

content of README.md file:

# Awesome Math Library
Helps to work with numbers.

paste the following line to .gitignore file (here we excluding docs folder)

docs/

add commands to package.json for generating/displaying documentation:

"scripts": {
  "test-math-helper": "mocha --compilers js:babel-core/register ./specs/MathHelper.spec.js",
  "generate-doc": "./node_modules/.bin/esdoc",
  "show-docs": "open ./docs/index.html"
}

but before we will generate docs we need to describe our class with methods:

/**
 * Utility class that helps to work with numbers.
 */
export class MathHelper {
    /**
     * Adds two numbers.
     * @param {number} augend The first number in an addition.
     * @param {number} addend The second number in an addition.
     * @return {number} Returns the total.
     */
    static add(augend, addend) {
        return augend + addend;
    }
    /**
     * Subtract two numbers.
     * @param {number} minuend The first number in a subtraction.
     * @param {number} subtrahend The second number in a subtraction.
     * @return {number} Returns the difference.
     */
    static subtract(minuend, subtrahend) {
        return minuend - subtrahend;
    }
    /**
     * Divide two numbers.
     * @param {number} dividend The first number in a division.
     * @param {number} divisor The second number in a division.
     * @return {number} Returns the quotient.
     */
    static divide(dividend, divisor) {
        return dividend / divisor;
    }
    /**
     * Multiply two numbers.
     * @param {number} multiplier The first number in a multiplication.
     * @param {number} multiplicand The second number in a multiplication.
     * @return {number} Returns the product.
     */
    static multiply(multiplier, multiplicand) {
        return multiplier * multiplicand;
    }
}

Ok, let’s take a look:

MathHelper documentation Page

Now let’s create documentation for tests:

import { assert, expect } from 'chai';
import { MathHelper } from '../src/MathHelper.js';
/** @test {MathHelper} */
describe('Math Helper Tests', () => {
    /** @test {MathHelper#add} */
    it('MathHelper#add test method', () => {
        assert.equal(4, MathHelper.add(2, 2));
    });
    /** @test {MathHelper#subtract} */
    it('MathHelper#subtract test method', () => {
        assert.equal(2, MathHelper.subtract(4, 2));
    });
    /** @test {MathHelper#divide} */
    it('MathHelper#divide test method', () => {
        assert.equal(2, MathHelper.divide(4, 2));
    });
    /** @test {MathHelper#multiply} */
    it('MathHelper#multiply test method', () => {
        assert.equal(4, MathHelper.multiply(2, 2));
    });
});

MathHelper Test Page

And that’s all!

Conclusion

Thank you guys for reading. I hope you enjoyed it and learned some new stuff related to JavaScript. Please subscribe and press ‘Clap’ button if you like this article.