Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update README.md #195

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Update README.md #195

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
134 changes: 86 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,65 +3,95 @@
[![Build Status][travis-image]][travis-url] [![Coverage Status][coveralls-image]][coveralls-url]
[![Known Vulnerabilities](https://snyk.io/test/github/nickmerwin/node-coveralls/badge.svg)](https://snyk.io/test/github/nickmerwin/node-coveralls)

[Coveralls.io](https://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.
[Coveralls.io](https://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: [travis-ci](https://travis-ci.org/), [codeship](https://www.codeship.io/), [circleci](https://circleci.com/), [jenkins](http://jenkins-ci.org/), [Gitlab CI](http://gitlab.com/), [AppVeyor](http://appveyor.com/), [Buildkite](https://buildkite.com/)
Supported CI services:
* [travis-ci](https://travis-ci.org)
* [codeship](https://www.codeship.io)
* [circleci](https://circleci.com)
* [jenkins](http://jenkins-ci.org)
* [Gitlab CI](http://gitlab.com)
* [AppVeyor](http://appveyor.com)
* [Buildkite](https://buildkite.com)

## Installation:
Add the latest version of `coveralls` to your package.json:
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:
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](http://mochajs.org/)'s [LCov reporter](https://npmjs.org/package/mocha-lcov-reporter)) and send it to coveralls.io to report your code coverage there.
This script ( `bin/coveralls.js` ) can take standard input from any tool that emits the `lcov` data format (including [mocha](http://mochajs.org)'s [LCov reporter](https://npmjs.org/package/mocha-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`.
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](https://travis-ci.org/) with no extra effort beyond piping the lcov output to coveralls. However, 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 coveralls.io)

### Travis CI Usage

This library supports [travis-ci] with no extra effort beyond piping the `lcov` output to coveralls.


### Non-Travis CI Usage

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

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.)
* COVERALLS_PARALLEL (more info here: https://coveralls.zendesk.com/hc/en-us/articles/203484329)
### [Jest](https://facebook.github.io/jest/)
- Install [jest](https://facebook.github.io/jest/docs/en/getting-started.html)
- Use the following to run tests and push files to coveralls:

* `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.)
* `COVERALLS_PARALLEL` (more info here: https://coveralls.zendesk.com/hc/en-us/articles/203484329)


#### [Jest](https://facebook.github.io/jest)

* Install [jest](https://facebook.github.io/jest/docs/en/getting-started.html)
* Use the following to run tests and push files to coveralls:

```sh
jest --coverage --coverageReporters=text-lcov | coveralls
```
Check out an example [here](https://github.com/Ethan-Arrowood/harperdb-connect/blob/master/.travis.yml) which makes use of Travis-CI build stages

### [Mocha](http://mochajs.org/) + [Blanket.js](https://github.com/alex-seville/blanket)
- Install [blanket.js](http://blanketjs.org/)
- Configure blanket according to [docs](https://github.com/alex-seville/blanket/blob/master/docs/getting_started_node.md).
- Run your tests with a command like this:
[Here’s an example](https://github.com/Ethan-Arrowood/harperdb-connect/blob/master/.travis.yml) which makes use of Travis-CI build stages.


#### [Mocha](http://mochajs.org) + [Blanket.js](https://github.com/alex-seville/blanket)
* Install [`blanket.js`](http://blanketjs.org)
* Configure blanket according to [docs](https://github.com/alex-seville/blanket/blob/master/docs/getting_started_node.md).
* Run your tests with a command like this:

```sh
NODE_ENV=test YOURPACKAGE_COVERAGE=1 ./node_modules/.bin/mocha \
--require blanket \
--reporter mocha-lcov-reporter | ./node_modules/coveralls/bin/coveralls.js
```
### [Mocha](http://mochajs.org/) + [JSCoverage](https://github.com/fishbar/jscoverage)

Instrumenting your app for coverage is probably harder than it needs to be (read [here](http://www.seejohncode.com/2012/03/13/setting-up-mocha-jscoverage/)), 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:
#### [Mocha](http://mochajs.org/) + [JSCoverage](https://github.com/fishbar/jscoverage)

Instrumenting your app for coverage is probably harder than it needs to be, but it's also a necessary step.
(See [here](http://www.seejohncode.com/2012/03/13/setting-up-mocha-jscoverage/) for more info.)

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

```sh
YOURPACKAGE_COVERAGE=1 ./node_modules/.bin/mocha test -R mocha-lcov-reporter | ./node_modules/coveralls/bin/coveralls.js
```
Check out an example [Makefile](https://github.com/cainus/urlgrey/blob/master/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](https://github.com/gotwarlost/istanbul)
Check out an example [`Makefile`](https://github.com/cainus/urlgrey/blob/master/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. (Set `npm test` in your `package.json`\'s `scripts` property).


#### [Istanbul](https://github.com/gotwarlost/istanbul)

**With Mocha:**

Expand All @@ -75,15 +105,15 @@ istanbul cover ./node_modules/mocha/bin/_mocha --report lcovonly -- -R spec && c
istanbul cover jasmine-node --captureExceptions spec/ && cat ./coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js && rm -rf ./coverage
```

### [Nodeunit](https://github.com/caolan/nodeunit) + [JSCoverage](https://github.com/fishbar/jscoverage)
#### [Nodeunit](https://github.com/caolan/nodeunit) + [JSCoverage](https://github.com/fishbar/jscoverage)

Depend on nodeunit, jscoverage and coveralls:
Depend on `nodeunit`, `jscoverage`, and `coveralls`:

```sh
npm install nodeunit jscoverage coveralls --save-dev
```

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

```javascript
"scripts": {
Expand All @@ -100,52 +130,60 @@ 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](https://github.com/alanshaw/nodeunit-lcov-coveralls-example).
For detailed instructions on requiring instrumented code, running on Travis, and submitting to coveralls, [see this guide](https://github.com/alanshaw/nodeunit-lcov-coveralls-example).

#### [Poncho](https://github.com/deepsweet/poncho)
Client-side JS code coverage using [PhantomJS](https://github.com/ariya/phantomjs), [Mocha](http://mochajs.org) and [Blanket](https://github.com/alex-seville/blanket):

### [Poncho](https://github.com/deepsweet/poncho)
Client-side JS code coverage using [PhantomJS](https://github.com/ariya/phantomjs), [Mocha](http://mochajs.org/) and [Blanket](https://github.com/alex-seville/blanket):
- [Configure](http://mochajs.org/#running-mocha-in-the-browser) Mocha for browser
- [Mark](https://github.com/deepsweet/poncho#usage) target script(s) with `data-cover` html-attribute
- Run your tests with a command like this:
* [Configure](http://mochajs.org/#running-mocha-in-the-browser) Mocha for browser
* [Mark](https://github.com/deepsweet/poncho#usage) target script(s) with `data-cover` html-attribute
* Run your tests with a command like this:

```sh
./node_modules/.bin/poncho -R lcov test/test.html | ./node_modules/coveralls/bin/coveralls.js
```

### [Lab](https://github.com/hapijs/lab)
#### [Lab](https://github.com/hapijs/lab)

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

### [nyc](https://github.com/bcoe/nyc)
#### [nyc](https://github.com/bcoe/nyc)

works with almost any testing framework. Simply execute
`npm test` with the `nyc` bin followed by running its reporter:
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](https://github.com/isaacs/node-tap)
#### [TAP](https://github.com/isaacs/node-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.
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

## Command Line Interface

```
Usage: coveralls.js [-v] filepath
```

#### Optional arguments:
### Optional arguments

```
-v, --verbose

filepath - optionally defines the base filepath of your source files.
```


## Running locally

If you're running locally, you must have a `.coveralls.yml` file, as documented in [their documentation](https://coveralls.io/docs/ruby), 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.
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`.

[travis-image]: https://travis-ci.org/nickmerwin/node-coveralls.svg?branch=master
[travis-url]: https://travis-ci.org/nickmerwin/node-coveralls
Expand All @@ -155,6 +193,6 @@ If you want to send commit data to coveralls, you can set the `COVERALLS_GIT_COM

## 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 afterall!).
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.
I also don't care for "soft-versioning" or "optimistic versioning" (i.e. dependencies that have `^`, `x`, or `>` in them...or anything other than numbers and dots). There have been too many problems with bad semantic versioning in dependencies. I'd rather have a solid library than a bleeding edge one.