JavaScript unit testing with Mocha and Grunt

Introduction

This is the first article in a series of three in which I will explain how I have setup unit testing for a JavaScript module. It documents the initial project setup and explains in a step-by-step fashion what I have done to get it up in running. In future articles I will explain how to add code coverage reports and integration with a continuous integration (CI) server.

Series overview

This series consists of the following articles:

Part 1: JavaScript unit testing with Mocha and Grunt
Part 2: Generating code coverage reports using Istanbul
Part 3: Running unit tests on a continuous integration service like Travis CI or Wercker

The demo project on GitHub

The files of the demo project are available on GitHub. For every step in getting the project setup there is separate branch in the repository. Whenever there is a branch with the current state of the code in the article I will make a mention of it in the text.

Intial setup

My demo project for this document is a very simple one, you can easily create it yourself. It looks like this, names in [] are folders:


Project Folder
  |- [grunt]
  |- [lib]
  |    |- Example.js
  |- [test]
  |    |- [spec]
  |- package.json

Project folder layout

The following should be said about the files:

[grunt]: I always use load-grunt-config for my Gruntfile. In this folder we will place the configuration for the various tasks.
[test]: this is the folder which eventually will be where the unit tests and wrapper are stored in.
[test/spec]: this is the folder where the unit tests will be stored in.
package.json: just a boilerplate version of the file. It only needs the keys author, name, and version for it to be a valid file.
Example.js: this is the module we will be unit testing. The only thing noteworthy about my use case is that my module was an AMD-module and would be loaded using Require.js. For the remainder of this article we will assume the module is this:


define([], function() {
    var exports = function() {

    };

    exports.prototype = {
        add: function(valueA, valueB) {
            return valueA + valueB;
        }
    };

    return exports;
});

Example.js

To run the unit test I will be using a Grunt task, this means we need to install the task runner with the command:

npm install --save-dev grunt

If you're following along and you haven't installd the grunt-cli yet on your system then you can do so using the following command:

npm install -g grunt-cli

We also need to install the `load-grunt-config` module for making the `Gruntfile.js` more modular and less verbose.

npm install --save-dev load-grunt-config

As I explained for `Example.js`, I am using AMD-modules and the unit tests will also be written as AMD-modules. This makes the require library another necessity for the project. It can be added like this:

npm install --save-dev requirejs

Unit test framework

There are many unit test frameworks, all of them have their own strengths and weaknesses. I've looked at Jasmine, Mocha, Intern, Karma, and some others I've already forgotten about. In the end I settled on Mocha, it has the features I was looking for and I came across some good tutorials on how to set it up. To add Mocha to the project the following command can be executed:

npm install --save-dev mocha

There is a Grunt task which will allow you to run Mocha specs in a headless browser (PhantomJS), this is exactly what I was looking for. The original project can be found at grunt-mocha. This is however not the version I wound up using. I also wanted code coverage reports and to get this to work with Mocha there is a small modification needed for grunt-mocha. This modification has already been done by Jon Bretman and his version can be installed using the following command:

npm install --save-dev git+https://github.com/jonbretman/grunt-mocha.git

For me the command wouldn't execute properly without the git+https part but your milage may vary. If you're interested in exactly what has been changed in order to support code coverage, you can see the changes here.

Assertion library

With the testing framework sorted it was necessary to pick an assertion library. There is the assert style.


assert.ok(true, 'everything is okay').

Assert style test

To me this wasn't the most intuitive way to read and write my unit tests. Luckily there are two other styles which are more geared towards behaviour-driven development (BDD), should and expect.


var foo = 'bar';

foo.should.equal('bar');
expect(foo).to.be('bar');

Should and Expect styles

The expect style felt the most natural to me so that is what I went with. The library I picked is Expect.js and it can be installed with the following command:

npm install --save-dev expect.js

On the Expect.js GitHub page there are some people who have voiced concerns about the lack of project updates. At the time of writing the last update was about 7 months ago. The other popular expect style library I came across, Chai, shows the same kind of inactivity. Therefore I don't think it makes a huge difference which one you pick. So far I've not run into any issues with Expect.js.

Add a unit test

I will not go into detail about how to write unit tests. For this article it is enough to have a simple test which checks if 1 plus 1 equals 2.


define(['Example'], function(Example) {
    'use strict';

    var example;
    beforeEach(function() {
        example = new Example();
    });

    describe('Example', function() {
        it('should have a method named "add"', function() {
            expect(example.add).to.be.a('function');
        });

        describe('.add()', function() {
            it('should return the sum of two numbers', function() {
                expect(example.add(1,1)).to.be(2);
            });
        });
    });
});

The unit test for Example.js

This unit test can be saved as /test/spec/Example.spec.js. This takes care of the unit test but now we still need a way to run it using Mocha. The solution I will be explaining works when you just have a single spec file or if you have multiple spec files. It is a bit of an overkill for this example but it makes the solution usable for larger projects.

HTML test runner

First off I need and HTML-file which will serve as the test runner. Because I want something reusable I am going to use some placeholders which will get replaced by the actual values using a Grunt task. The template for the test runner looks like this:


<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Mocha</title>
    <!-- This will include Mocha's default look & feel -->
    <link rel="stylesheet" href="../node_modules/mocha/mocha.css">
    <!-- We need Mocha itself -->
    <script src="../node_modules/mocha/mocha.js"></script>
    <!-- This will load the assertion library -->
    <script src="../node_modules/expect.js/index.js"></script>
    <!-- This will add require.js for loading the AMD-modules -->
    <script src="../node_modules/requirejs/require.js"></script>
</head>
<body>
    <!-- This is the container Mocha will use to display the test results -->
    <div id="mocha">
    </div>

    <script>
        // Setup Mocha
        mocha.setup('bdd');
        // Configure the require library. We're using two placeholders so we can use
        // Grunt to configure the HTML file the specs we want.
        require.config({
            baseUrl: {{ baseUrl }},
            deps: {{ tests }},
            callback: mocha.run
        });
    </script>
</body>
</html>

Template for the HTML test runner

This file will be saved as test/index.template.html. With the template file completed it is time to setup Grunt to replace those two placeholders with actual values.

Grunt test task

For Grunt it is necessary to have a Gruntfile.js file in the root folder, this file holds the definition of the Grunt tasks and their targets. Because I use load-grunt-config the initial file will look like this:


module.exports = function(grunt) {
  'use strict';

  // load the grunt setup
  require('load-grunt-config')(grunt);
};

The basic Gruntfile.js

For more information on how to use and configure your Grunt tasks with load-grunt-config, you can read the documentation here or this great tutorial by HTML5Rocks.

Now we need to add a test task, we can add the following code after the require statement in Gruntfile.js:


// When we add support for code coverage the test task will have two targets.
// Because of this I am using grunt.registerMultiTask instead of using
// grunt.registerTask.
grunt.registerMultiTask('test', 'Run JS Unit tests', function () {
    // Get the options for the current target
    var options = this.options();
    // In the options for the task you can configure which spec files should be
    // run. We use this to create a list of file names which we can insert into
    // the {{ tests }} placeholder in our HTML template
    var tests = grunt.file.expand(options.files).map(function(file) {
        return '../' + file;
    });

    // build the template by replacing the placeholders for their actual values
    var template = grunt.file.read(options.template).replace('{{ tests }}', JSON.stringify(tests)).replace('{{ baseUrl }}', JSON.stringify(options.baseUrl));

    // write template to tests directory
    grunt.file.write(options.runner, template);

    // Run the tests.
    grunt.task.run('mocha:test');
});

Grunt test task

With the Grunt task registered we need to configure it. We will create a new file named grunt/test.js, this needs to have the same name as the task we registered, with the following content:


module.exports = {
    // Configure the test task with the following options:
    // 1: The name of the HTML template file, this is the file with the
    //    placeholders.
    // 2: This is the filename that is used to write the modified template to, it
    //    is the file that we will run with Mocha.
    // 3: The pattern for the spec files to include in the test runner, you can
    //    use a glob pattern for this.
    options: {
        template: 'test/index.template.html', /* [1] */
        runner: 'test/index.html',            /* [2] */
        files: 'test/spec/**/*.js'            /* [3] */
    },

    // Configure the testonly target
    // 4: This is the path where the JavaScript files to test are located, it is
    //    relative to the /test folder.
    testonly: {
        options: {
            baseUrl: '../lib'                 /* [4] */
        }
    }
};

Configuration for the test task

Because our test task will in turn call the Mocha Grunt task we will also have to configure this. To do this we need to create a file named grunt/mocha.js and give it the following content:


module.exports = {
    // Configure the Mocha task with the following options:
    // 1: The default reporter, Dot, just shows dots as output, that is not very
    //    informative. The Spec reporter is more verbose and shows all the test
    //    descriptions and results.
    // 2: The test should not start automatically. We will start it manually in
    //    our index.html file.
    options: {
        reporter: 'Spec',         /* [1] */
        run: false                /* [2] */
    },
    // Configure the test target
    // 3: This is the path to the HTML test runner
    test: {
        src: 'test/index.html'    /* [3] */
    }
};

Configuration for the mocha task

Running the test

Now that everthing is configured we can run the unit test. To run the test use the following command:

grunt test:testonly

This results in the following output in the terminal as shown in the image below. As you can see both tests passed.

The result from the unit test

Wrapping up

So far I've added a unit test and configured Mocha to be run using a Grunt task. The Grunt task has been made configurable so it is easy to share the task over multiple projects. In this example it only runs a single spec file but it can run multiple spec files just as easy. In the next part I will explain how I have added Istanbul code coverage to the project.