grunt-mochaccino

A grunt plugin to run tests via command-line mocha.

Other mocha plugins for grunt use the mocha library programmatically, which loses a lot of useful diagnostic information. This plugin is an alternative to those, instead using the command line tool to keep mocha's full output.

It also tries to make production of coverage reports simple, mainly by documenting exactly how to produce them.

Note that the configuration options available for the task are limited, as the aim of the plugin was to keep complexity low. Feature requests or patches are welcome, of course.

License

Apache version 2, copyright Intel Corporation Ltd. See LICENSE for more details.

Contributing

Contributions are welcome. Some examples of how you could help:

1. Report bugs or make feature requests through the issue tracker.

2. Fix bugs or add features, then make a pull request to have your code merged. The preferred approach is to make a github fork, write your code, and make a pull request for it to be merged into the grunt-mochaccino master branch. The [#Hacking] section explains a bit more about how to this.

Hacking

1. Make a fork of grunt-mochaccino on github.

2. Clone it to your development machine.

3. Modify the task code: currently it's in a single file, tasks/grunt-mochaccino.

4. Run the meagre test suite. There is a basic functional test in test/functional to check that the plugin mostly works. Run it by opening that directory and entering grunt at the command line. Feel free to add more tests...

5. Make a github pull request to have your branch merged into grunt-mochaccino master.

Getting started

You will need Grunt ~0.4.0.

You will also need a global install of mocha:

npm install -g mocha

Next, install the grunt-mochaccino plugin in your project with:

npm install grunt-mochaccino --save-dev

Then add a line to your Gruntfile.js near the top:

module.exports = function (grunt) {
  grunt.loadNpmTasks('grunt-mochaccino');

  // ... rest of your grunt config ...
};

See the next section for configuration options.

mochaccino task

The mochaccino task calls the command-line mocha runner, passing any required extra options (e.g. -R blanket if you configure the reporter as "html-cov") and the list of test files (derived from the files property for the task).

While grunt-mochaccino doesn't provide all the mocha command line switches as configuration options, you can still set these in a mocha.opts file if you wish. The example in test/functional/ shows how to do this (see the test/mocha.opts file inside this example, which turns off color for the reports on the console).

Note that grunt-mochaccino is a multi-task, so you can configure it to run unit tests separately from integration tests etc.

Options

files

type: grunt file spec, mandatory

Specifies the test files to run with mocha.

cmd

type: string, default: MOCHA environment variable, if set; if not, "mocha"

The mocha command to run. Should either be on your path (e.g. "mocha") or an absolute path (e.g. "/home/bilbo/bin/mocha").

reporter

type: string, default: "dot"

The mocha reporter to use. Note that if you're using fancy reporters, you will need to install them into your project yourself.

Using the "html-cov" reporter exposes more options to do with generating a coverage report (see below).

reportDir

type: string, default: "."

The directory to output coverage reports to.

browserCmd

type: string, default: null

Command to start a browser from the command line.

If set, and reporter == "html-cov", grunt-mochaccino will attempt to open the generated coverage report using this browser command.

Note that the command is fed directly to the command line, so you need to either specify an absolute path (e.g. "/home/bilbo/bin/google-chrome") or a command on your path (e.g. "google-chrome", "firefox").

blanket

type: string, default: 'blanket'

The path to the blanket node module. In most contexts, the default should be OK, but you may need to set it manually if you're running tests from a subdirectory (as is the case with grunt-mochaccino's own tests; see test/functional/Gruntfile.js).

See Producing coverage reports for more details about coverage reporting.

Producing coverage reports

This plugin will also write coverage reports to a configurable directory. To use this functionality you will need to do the following in your project:

1. Install blanket:

   npm install blanket --save-dev

   Note that I've tested this on my own projects with the current development version of blanket.

2. Configure blanket in package.json by adding a blanket property to the the scripts object. For example, if your project is in the myproject directory, and the source under test is in myproject/src, your package.json should look something like this:

   {
     "name": "myproject",
     "scripts": {
       "blanket": {
         "pattern": "myproject/src/"
       }
     },
     ... more properties ...
   }

   Note the slightly counter-intuitive "myproject/src". This is because blanket compares the paths of files imported by require() against this pattern: if you just use "src" as the pattern, you might find that blanket produces coverage statistics for other src directories in your project (e.g. inside node_modules).

3. In your mochaccino task configuration in Gruntfile.js, set the reporter to 'html-cov':

   grunt.initConfig({
     // ... other task configuration ...
   
     mochaccino: {
       cov: {
         files: [
           { src: 'test/unit/*.test.js' },
           { src: 'test/integration/*.test.js' }
         ],
         reporter: 'html-cov',
         reportDir: 'build',
         browserCmd: 'google-chrome'
       }
     }
   });

   grunt-mochaccino uses standard grunt file sources, so you can set the files property how you like. The example above shows how to configure a coverage task mochaccino:cov for the test/unit/ and test/integration/ directories.

   browserCmd is an optional property specifying the command to start a browser in your environment. If set, grunt-mochaccino will open the browser with the path to the generated coverage report.

4. Run the task. With the above configuration, you'd do:

   grunt mochaccino:cov

   The output should look something like this (this example is extracted from grunt-tizen):

   looking for tasks in /home/ell/dev/js/grunt-tasks/grunt-tizen/node_modules/grunt-mochaccino/tasks
   Running "mochaccino:cov" (mochaccino) task
   >> mocha command: mocha -R html-cov --require blanket test/unit/bridge.test.js test/unit/file-lister.test.js test/unit/tizen-config.test.js test/unit/tizen-tasks.test.js test/integration/tizen-config-maker.test.js
   >> coverage report is available at build/cov-2013-06-28_145716.html
   
   Done, without errors.

   The report filenames use the convention <reportDir>/cov-<timestamp>.html.