istanbul-traceur

Istanbul is a robust code coverage tool, could be run on both Node.js and browsers, provides many report formats (HTML, LCOV, etc.) to have testing and continuous integration done right. But Istanbul could not understand JavaScript of the future (e.g. ECMCScript 6). The next JavaScript provides new language features which help development process goes faster and produces less bugs.

Fortunately, we have Traceur, which is a transpiler (source-to-source compiler) which could convert JavaScript of the future to current JavaScript.

This module is here to help connecting these two awesome thing together. It stands as an alternative to Istanbul, enables you to use Traceur to write applications in modern JavaScript without worrying about code coverage.

Installation

This module can be installed easily with npm:

$ npm install istanbul-traceur

Usage

Directly

main.js:

var fs = require('fs');

var istanbul = require('istanbul-traceur');
var instrumenter = new istanbul.Instrumenter();

var content = fs.readFileSync('es6.js', 'utf8');
var code = instrumenter.instrumentSync(content, '/path/to/file.js');

eval(code);
//=> prints "You have done right!"

es6.js:

import assert from 'assert';

export var isOdd = (n) => {
  return !!(n & 1);
};

assert(isOdd(7), '7 is odd.');
assert(!isOdd(4), '4 is even.');

console.log('You have done right!');

With Gulp

gulpfile.js:

var gulp = require('gulp');
var istanbul = require('gulp-istanbul');
var mocha = require('gulp-mocha');

var istanbulTraceur = require('istanbul-traceur');

gulp.task('test', function (cb) {
  var usedIstanbul = require('gulp-istanbul/node_modules/istanbul');
  var Instrumenter = usedIstanbul.Instrumenter;

  // Overrides `Instrumenter`
  usedIstanbul.Instrumenter = istanbulTraceur.Instrumenter;

  gulp.src([ 'lib/**/*.js' ])
    .pipe(istanbul())
    .on('finish', function () {
      gulp.src([ 'test/**/*.js' ])
        .pipe(mocha())
        .pipe(istanbul.writeReports())
        .on('end', function (err) {
          // Restores original `Instrumenter`
          usedIstanbul.Instrumenter = Instrumenter;
          cb(err);
        });
    });
});

gulp test in Terminal:

HTML report:

With Grunt

Gruntfile.js:

var istanbulTraceur = require('istanbul-traceur');

module.exports = function (grunt) {
  grunt.loadNpmTasks('grunt-mocha-test');
  grunt.loadNpmTasks('grunt-istanbul');

  grunt.initConfig({
    instrument: {
      files: 'lib/**/*.js',
      options: {
        basePath: 'coverage/instrumented',
        lazy: true
      }
    },
    mochaTest: [
      'test/**/*.js'
    ],
    storeCoverage: {
      options: {
        dir: 'coverage/reports'
      }
    },
    makeReport: {
      src: 'coverage/reports/**/*.json',
      options: {
        type: 'lcov',
        dir: 'coverage/reports',
        print: 'detail'
      }
    }
  });

  var usedIstanbul;
  var Instrumenter;

  grunt.registerTask('istanbul:override', function () {
    usedIstanbul = require('grunt-istanbul/node_modules/istanbul');
    Instrumenter = usedIstanbul.Instrumenter;

    // Overrides `Instrumenter`
    usedIstanbul.Instrumenter = istanbulTraceur.Instrumenter;
  });

  grunt.registerTask('istanbul:restore', function () {
    // Restores original `Instrumenter`
    usedIstanbul.Instrumenter = Instrumenter;
  });

  grunt.registerTask('test', [
    'istanbul:override',
    'instrument',
    'mochaTest',
    'storeCoverage',
    'makeReport',
    'istanbul:restore',
  ]);
};

When using with Grunt:

NOTE: Because instrumented copies of your source files lie in different directory, you have to make sure all require methods in your test files pointing to correct source file's locations.

grunt test in Terminal:

HTML report is also available when using with Grunt.

Command-line usage

This feature is not available at the moment and will be implemented soon. If you want to give a hand, create a pull request.

Compatibility

• This module has been tested to run properly with Traceur version 0.0.61 (latest version at the time of writing). It could be broken in the future if Traceur introduces non backward-compatible changes. In that circumstance, feel free to create new issue or create a pull request.

Contributing

Before create a pull request, make sure that you:

• Followed coding convention as described in .editorconfig or .jshintrc file (more information can be found at editorconfig.org and www.jshint.com/docs, respectively).

• Added tests for your code.

• Passed all tests!

To execute all tests, simply run:

$ npm test

Contributors

• Author: Meo

License

This module is released under MIT license.