coveralls

What is coveralls?

The coveralls npm package is used to integrate your project with Coveralls, a web service that provides test coverage history and statistics. It helps developers ensure that their code is well-tested by tracking the percentage of code covered by tests over time.

What are coveralls's main functionalities?

Sending Coverage Reports

This feature allows you to send your test coverage reports to Coveralls. The code sample reads the coverage report from a file and sends it to Coveralls using the `handleInput` method.

const coveralls = require('coveralls');
const fs = require('fs');

fs.readFile('coverage/lcov.info', 'utf8', (err, data) => {
  if (err) {
    console.error('Error reading coverage file:', err);
    return;
  }
  coveralls.handleInput(data, (err) => {
    if (err) {
      console.error('Error sending to Coveralls:', err);
    } else {
      console.log('Coverage report sent to Coveralls');
    }
  });
});

Custom Git Information

This feature allows you to send custom Git information along with your coverage report. The code sample demonstrates how to include custom Git metadata when sending the coverage report to Coveralls.

const coveralls = require('coveralls');
const fs = require('fs');

const gitInfo = {
  head: {
    id: 'commit-sha',
    author_name: 'Author Name',
    author_email: '[e-mail]',
    committer_name: 'Committer Name',
    committer_email: '[e-mail]',
    message: 'Commit message'
  },
  branch: 'main'
};

fs.readFile('coverage/lcov.info', 'utf8', (err, data) => {
  if (err) {
    console.error('Error reading coverage file:', err);
    return;
  }
  coveralls.handleInput(data, { git: gitInfo }, (err) => {
    if (err) {
      console.error('Error sending to Coveralls:', err);
    } else {
      console.log('Coverage report with custom git info sent to Coveralls');
    }
  });
});

Other packages similar to coveralls

codecov

Codecov is another popular service for tracking code coverage. It provides similar functionalities to Coveralls, such as integrating with CI/CD pipelines and supporting multiple languages and coverage formats. Codecov also offers additional features like detailed coverage graphs and pull request comments.

nyc

NYC is a command-line tool for generating code coverage reports. It is often used in conjunction with other tools like Mocha or Jest. While NYC itself does not provide a web service for tracking coverage history, it can be used to generate coverage reports that can then be sent to services like Coveralls or Codecov.

jest

Jest is a JavaScript testing framework that includes built-in support for generating code coverage reports. While Jest focuses more on testing, it can be configured to output coverage reports in formats compatible with services like Coveralls and Codecov.

README

#node-coveralls

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

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

npm install coveralls --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 coveralls.io to report your code coverage there.

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

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

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

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.

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).