takes json-cov output into stdin and POSTs to

npm install coveralls
1 529 downloads in the last day
8 503 downloads in the last week
36 029 downloads in the last month


Build Status Coverage Status Codeship Build Status Build
Status support for node.js. Get the great coverage reporting of and add a cool coverage button ( like the one above ) to your README.

Supported CI services: travis-ci, codeship, circle-ci, jenkins


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

npm install coveralls --save

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

npm install mocha-lcov-reporter --save


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 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 that, but if you're using a different build system, there are a few environment variables that are necessary:

  • COVERALLS_SERVICE_NAME (the name of your build system)
  • COVERALLS_REPO_TOKEN (the secret repo token from

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

  • COVERALLS_SERVICE_JOB_ID (an id that uniquely identifies the build job)
  • COVERALLS_RUN_AT (a date string for the time that the job ran. RFC 3339 dates work. This defaults to your build system's date/time if you don't set it.)

Mocha + Blanket.js

  • Install blanket.js
  • Configure blanket according to docs.
  • Run your tests with a command like this:
NODE_ENV=test YOURPACKAGE_COVERAGE=1 ./node_modules/.bin/mocha \
  --require blanket \
  --reporter mocha-lcov-reporter | ./node_modules/coveralls/bin/coveralls.js

Mocha + JSCoverage

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

In mocha, if you've got your code instrumented for coverage, the command for a travis 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 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 cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && cat ./coverage/ | ./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 and submitting to coveralls see this guide.


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

  • Configure Mocha for browser
  • Mark target script(s) with data-cover html-attribute
  • Run your tests with a command like this:
./node_modules/.bin/poncho -R lcov test/test.html | ./node_modules/coveralls/bin/coveralls.js

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.

npm loves you