Home

Awesome

node-coveralls

Build Status Coverage Status

Coveralls.io support for Node.js. Get the great coverage reporting of coveralls.io and add a cool coverage button (like the one above) to your README.

Supported CI services:

Installation:

Add the latest version of coveralls to your package.json:

npm install coveralls --save-dev

If you're using mocha, add mocha-lcov-reporter to your package.json:

npm install mocha-lcov-reporter --save-dev

Usage:

This script bin/coveralls.js can take standard input from any tool that emits the lcov data format (including mocha's LCOV reporter) and send it to coveralls.io to report your code coverage there.

Once your app is instrumented for coverage, and building, you need to pipe the lcov output to ./node_modules/coveralls/bin/coveralls.js.

This library currently supports Travis CI with no extra effort beyond piping the lcov output to coveralls. However, if you're using a different build system, there are a few necessary environment variables:

There are optional environment variables for other build systems as well:

GitHub Actions CI

If you are using GitHub Actions CI, you should look into coverallsapp/github-action.

Parallel runs example workflow.yml

CircleCI Orb

Here's our Orb for quick integration: coveralls/coveralls

Workflow example: config.yml

Travis-CI

Parallel jobs example: .travis.yml

Jest

Check out an example here which makes use of Travis CI build stages

Mocha + Blanket.js

Mocha + JSCoverage

Instrumenting your app for coverage is probably harder than it needs to be (read here), but that's also a necessary step.

In mocha, if you've got your code instrumented for coverage, the command for a Travis CI build would look something like this:

YOURPACKAGE_COVERAGE=1 ./node_modules/.bin/mocha test -R mocha-lcov-reporter | ./node_modules/coveralls/bin/coveralls.js

Check out an example Makefile from one of my projects for an example, especially the test-coveralls build target. Note: Travis CI runs npm test, so whatever target you create in your Makefile must be the target that npm test runs (This is set in package.json's scripts property).

Istanbul

With Mocha:

istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage

With Jasmine:

istanbul cover jasmine-node --captureExceptions spec/ && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage

Nodeunit + JSCoverage

Depend on nodeunit, jscoverage, and coveralls:

npm install nodeunit jscoverage coveralls --save-dev

Add a coveralls script to "scripts" in your package.json:

"scripts": {
  "test": "nodeunit test",
  "coveralls": "jscoverage lib && YOURPACKAGE_COVERAGE=1 nodeunit --reporter=lcov test | coveralls"
}

Ensure your app requires instrumented code when process.env.YOURPACKAGE_COVERAGE variable is defined.

Run your tests with a command like this:

npm run coveralls

For detailed instructions on requiring instrumented code, running on Travis CI and submitting to coveralls see this guide.

Poncho

Client-side JS code coverage using PhantomJS, Mocha and Blanket:

Lab

lab -r lcov | ./node_modules/.bin/coveralls

nyc

Works with almost any testing framework. Simply execute npm test with the nyc bin followed by running its reporter:

nyc npm test && nyc report --reporter=text-lcov | coveralls

TAP

Simply run your tap tests with the COVERALLS_REPO_TOKEN environment variable set and tap will automatically use nyc to report coverage to coveralls.

Command Line Parameters

Usage: coveralls.js [-v] filepath

Optional arguments:

Running locally

If you're running locally, you must have a .coveralls.yml file, as documented in their documentation, with your repo_token in it; or, you must provide a COVERALLS_REPO_TOKEN environment variable on the command-line.

If you want to send commit data to coveralls, you can set the COVERALLS_GIT_COMMIT environment-variable to the commit hash you wish to reference. If you don't want to use a hash, you can set it to HEAD to supply coveralls with the latest commit data. This requires git to be installed and executable on the current PATH.

Contributing

I generally don't accept pull requests that are untested or break the build, because I'd like to keep the quality high (this is a coverage tool after all!).

I also don't care for "soft-versioning" or "optimistic versioning" (dependencies that have ^, x, > in them, or anything other than numbers and dots). There have been too many problems with bad semantic versioning in dependencies, and I'd rather have a solid library than a bleeding-edge one.