travi / grunt-mocha-cov

Run Mocha server-side tests in Grunt with code coverage support and optional integration to coveralls.io.

Grunt Mocha Test Coverage

Use Grunt to execute server-side Mocha tests with optional code coverage using Blanket. You can also use this to send coverage data to Coveralls.

This is based on grunt-mocha-cli and can be used in place of this library with support for running code coverage reports or integration into Coveralls.

Getting Started

You can install this plugin with this command:

npm install grunt-mocha-cov --save-dev

Note: This is a grunt plugin. If you haven't used Grunt before, check out their Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.

Usage

Options

All of the Mocha command line options are supported, plus some extras.

The list of test files to run can be specified using either the standard Grunt format or by using the files option. If neither is specified, the Mocha default will be used (test/*.js).

Mocha Options

• invert (boolean) - inverts grep matches.
• colors (boolean) - force enabling of colors.
• no-colors (boolean) - force disabling of colors.
• growl (boolean) - enable growl notification support.
• debug (boolean) - enable node's debugger, synonym for node --debug.
• bail (boolean) - bail after first test failure.
• recursive (boolean) - include sub directories.
• debug-brk (boolean) - enable node's debugger breaking on the first line.
• async-only (boolean) - force all tests to take a callback (async).
• check-leaks (boolean) - check for global variable leaks.
• sort (boolean) - sort test files.
• inline-diffs (boolean) - display actual/expected differences inline within each string.
• no-exit (boolean) - require a clean shutdown of the event loop: mocha will not call process.exit().
• reporter (string) - specify the reporter to use.
• ui (string) - specify user-interface (bdd|tdd|exports).
• grep (string) - only run tests matching pattern.
• timeout (string) - set test-case timeout in milliseconds [2000].
• slow (string) - "slow" test threshold in milliseconds [75].
• globals (array) - allow the given comma-delimited global names.
• compilers (array) - use the given module(s) to compile files.
• require (array) - require the given modules.
• expose-gc (boolean) - expose gc extension, synonym for node --expose-gc.
• gc-global (boolean) - always perform global GCs, synonym for node --gc-global.
• harmony (boolean) - enable all harmony features (except typeof), synonym for node --harmony.
• harmony-proxies (boolean) - enable harmony proxies, synonym for node --harmony-proxies.
• harmony-collections (boolean) - enable harmony collections, synonym for node --harmony-collections.
• harmony-generators (boolean) - enable harmony generators, synonym for node --harmony-generators.
• prof (boolean) - log statistical profiling information, synonym for node --prof.

Coverage Options

• instrument (boolean) - instrument the source using blanket. Defaults to true when you setup coveralls, or use specify a *-cov reporter, otherwise false.

Coveralls Options

• coveralls (Boolean|Object) - Indicate you wish to send a coverage report to coveralls.io. Generally you can get away with seting this to true and letting node-coveralls pick the necessary values out of the environment.
  • serviceName (string) - name of the CI service for coveralls to integrate with (options are travis-ci, jenkins, circleci, or codeship).
  • serviceJobId (string) - The job id used by coveralls (default based on service).
  • repoToken (string) - repository identifier as provided by coveralls (defaults to the COVERALLS_REPO_TOKEN environment variable).

Extras

• quiet (boolean) - disable printing of Mocha's output to the terminal.
• files (string|array) - glob(s) of test files to run.
• output (string) - path to save report to disk.

Examples

Standard Mocha Test

Define test files using the standard Grunt format:

grunt.initConfig({
  mochacov: {
    options: {
      reporter: 'spec',
      require: ['should']
    },
    all: ['test/*.js']
  }
});

grunt.registerTask('test', ['mochacov']);

Built in HTML Coverage Report

If you use one of the built in coverage reports your code will automaticaly be instrumented by blanket:

grunt.initConfig({
  mochacov: {
    options: {
      reporter: 'html-cov',
      require: ['should']
    },
    all: ['test/*.js']
  }
});

grunt.registerTask('test', ['mochacov']);

For this to work properly you will also need to inform Blanket about what needs to be instrumented. The best way to do so is adding a block to your package.json such as:

"config": {
  "blanket": {
    "pattern": [
      "src"
    ]
  }
}

This would instrument any .js files found under src.

Coveralls.io Integration with Travis CI

It's easy to send coverage data to coveralls.io from the most popular CI serivces (like Travis CI). Simply set the coveralls option to true:

grunt.initConfig({
  mochacov: {
    coverage: {
      options: {
        coveralls: true
      }
    },
    test: {
      options: {
        reporter: 'spec'
      }
    },
    options: {
      files: 'test/*.js'
    }
  }
});

grunt.registerTask('travis', ['mochacov:coverage']);
grunt.registerTask('test', ['mochacov:test']);

Keep your Coveralls repo token out of the environment

Don't want to keep your repo token in the environment where anyone could access it? Pass it in via the coveralls.repoToken option:

grunt.initConfig({
  mochacov: {
    options: {
      coveralls: {
        repoToken: 'YOURREPOTOKEN'
      }
    },
    coverage: ['test/*.js']
  }
})

Setup intrumentation yourself

If you want to start blanket yourself, as in this example, just set the instrument option to false.

grunt.initConfig({
  mochacov: {
    options: {
      coveralls: true,
      instrument: false
    },
    all: ['test/*.js']
  }
});

grunt.registerTask('json_coverage', ['mochacov']);

License

Grunt Mocha Coveralls is based on original works by Gregg Caines and Roland Warmerdam. Modifications and new works by Mike Moulton released under the MIT license.

Copyright © 2013 Mike Moulton