babel-plugin-transform-adana

Minimal, complete code-coverage tool for babel 6+.

Has all the features (and more) of istanbul including line, function and branch coverage, but works as a babel plugin instead of relying on esparse and escodegen. Works great with west, mocha, jasmine and probably more.

Features:

• First-class babel support,
• Per-line/function/branch coverage,
• Tagged instrumentation,
• User-defined tags,
• Smart branch detection.

Usage

Install babel-plugin-transform-adana:

npm install --save-dev babel-plugin-transform-adana

Setup your .babelrc to use it:

{
  "env": {
    "test": {
      "plugins": [[
        "transform-adana", {
          "ignore": "test/**/*"
        }
      ]]
    }
  }
}

IMPORTANT: This plugin works best when it runs as the first plugin in the babel transform list, since its purpose is to instrument your original code, not whatever other transformations happen to get made.

NOTE: This plugin is only responsible for instrumenting your code, not verifying the coverage information or reporting. You can install something like adana-cli to get something like instanbul check-coverage. See the adana-cli repository for more information.

mocha

Usage with mocha is straight-forward. The only thing you need to do after running your code is dump the coverage information to disk so it can be processed; mocha can do this via its -r flag.

Install the necessary packages:

npm install --save-dev \
  mocha \
  adana-cli \
  adana-dump \
  adana-format-lcov \
  babel-plugin-transform-adana

Start testing with mocha:

#!/bin/sh

# Run tests and dump the coverage information.
NODE_ENV="test" mocha \
  -r adana-dump \
  -r @babel/register \
  test/*.spec.js

# Upload coverage data to coveralls.
cat ./coverage/coverage.json \
  | ./node_modules/.bin/adana --format lcov \
  | ./node_modules/coveralls/bin/coveralls.js

jasmine

Usage with jasmine is less straight-forward than with mocha since there is no native babel support. The package jasmine-es6 can be used to use babel (and therefore adana) with jasmine.

Install the necessary packages:

npm install --save-dev \
  jasmine-es6 \
  adana-cli \
  adana-dump \
  adana-format-lcov \
  babel-plugin-transform-adana

Add the output tool as a helper to jasmine via jasmine.json in order to ensure your coverage data gets output:

{
  "spec_dir": "spec",
  "spec_files": [
    "**/*[sS]pec.js"
  ],
  "helpers": [
    "../node_modules/jasmine-es6/lib/install.js",
    "../node_modules/adana-dump/index.js",
    "helpers/**/*.js"
  ]
}

Start testing with jasmine:

#!/bin/sh
NODE_ENV="test" jasmine

# Upload coverage data to coveralls.
cat ./coverage/coverage.json \
  | ./node_modules/.bin/adana --format lcov \
  | ./node_modules/coveralls/bin/coveralls.js

west

TODO: Write me!

Tags

There is no ignore flag, but you can tag functions, branches or statements which can be used to determine relevant coverage information. This allows you to ask things like "Have I covered all the code that pertains to authentication in the file?" and "Has this run in IE covered all the IE-specific cases?". Existing ignore comments simply tag a function with the ignore tag.

• Add a tag with +tag, remove a tag with -tag.
• Tags above a function declaration apply to all code in that function.
• Tags above a class declaration apply to all code in that class.
• Tags before the first statement of a branch apply to the branch and its code.
• Tags on a line apply to everything on that line.

/* adana: +ie +firefox -chrome */
function foo(i) {
  ++i; // +chrome
  console.log('foo', i); // adana: +test
  return i;
}


if (foo(1)) {
  /* adana: +chrome */
  console.log('bar');
}

FAQ

• Why is let i;, function foo() {}, etc. not marked at all? – Some things are not executable code per se (i.e. declarations). They do nothing to effect program state and are therefore not instrumented.

Configuration

There are a couple of configuration options available to control how your program is instrumented. They can be set via the standard mechanism babel employs for configuring transforms.

{
  // Pattern to match to determine if the file should be covered. The pattern
  // must be matched for coverage to be enabled for the file. Takes precedence
  // over `ignore`.
  // See `only` of https://babeljs.io/docs/usage/options/
  only: 'src/**/*.js',
  // Pattern to match to determine if the file should NOT be covered. The
  // pattern must NOT be matched for coverage to be enabled for the file.
  // See `ignore` of https://babeljs.io/docs/usage/options/
  ignore: 'test/**/*',
  // Name of the global variable to store all the collected coverage information
  // in.
  global: '__coverage__'
}

API

Again, this plugin is simply a babel transformer that injects markers to determine if specific parts of the code have been run. Usage is as a normal babel plugin:

import {transform} from '@babel/core';

const result = transform('some code', {
  plugins: ['transform-adana']
});

// Access result.code, result.map and result.metadata.coverage

To collect information about code that has been instrumented, simply access the configured global variable, e.g. __coverage__.

import vm from 'vm';
const sandbox = vm.createContext({});
sandbox.global = sandbox;
vm.runInContext(result.code, sandbox);
console.log(sandbox.__coverage__);

The __coverage__ object has the following shape:

{
  // Hash of the file.
  hash: '2892834823482374234234235',
  // Path to the file being instrumented.
  path: 'some/file.js',
  // Detailed information about every location that's been instrumented.
  locations: [{
    id: 0,
    loc: { start: { line: 0, column 0 }, end: { line: 0, column: 0 } },
    name: 'foo',
    group: 'bar',
    tags: [ 'tagA', 'tagB' ],
    count: 5
  }, {
    ...
  }, ...]
}

More useful processing of this object can be done with adana-analyze.