hpc-coveralls [](https://travis-ci.org/guillaume-nargeot/hpc-coveralls) [](https://gitter.im/guillaume-nargeot/hpc-coveralls) [](https://tldrlegal.com/license/bsd-3-clause-license-%28revised%29)
=============
hpc-coveralls converts and sends Haskell projects hpc code coverage to [coverall.io](http://coveralls.io/).
At the moment, only [Travis CI](http://travis-ci.org) has been tested, but hpc-coveralls should be compatible with other CI services (Check `HpcCoverallsMain` [source](https://github.com/guillaume-nargeot/hpc-coveralls/blob/master/src/HpcCoverallsMain.hs) for the list).
hpc-coveralls is still under development and any contributions are welcome!
# Usage
## Travis CI
Commands to add to your project `.travis.yml` when using GHC 7.8:
```yaml
before_install:
- cabal install hpc-coveralls
script:
- cabal configure --enable-tests --enable-library-coverage && cabal build && cabal test
after_script:
- hpc-coveralls [options] [test-suite-names]
```
When using a GHC version prior to 7.8, you have to replace the `cabal test` command by `run-cabal-test`, as in the following example:
```yaml
before_install:
- cabal install hpc-coveralls
script:
- cabal configure --enable-tests --enable-library-coverage && cabal build
- run-cabal-test [options] [cabal-test-options]
after_script:
- hpc-coveralls [options] [test-suite-names]
```
The reason for this is explained in the next section.
For a real world example usage, please refer to [this-project](https://github.com/guillaume-nargeot/project-euler-haskell) `.travis.yml` file ([result on coveralls](https://coveralls.io/r/guillaume-nargeot/project-euler-haskell)).
You can also refer to the `.travis.yml` file of hpc-coveralls itself, which is configured with [multi-ghc-travis](https://github.com/hvr/multi-ghc-travis).
## The run-cabal-test command
When using hpc 0.6, `cabal test` outputs an error message and exits with the error code `1`, which results in a build failure.
In order to prevent this from happening, hpc-coveralls provides the `run-cabal-test` command which runs `cabal test` and returns with `0` if the following regex never matches any line of the output:
```perl
/^Test suite .*: FAIL$/
```
As this issue is fixed in the hpc version shipped with GHC 7.8, you don't have to use `run-cabal-test` when testing with GHC 7.8 and can safely use `cabal test`.
### Options
The `--cabal-name` option can be used to specify a custom executable name instead of the default `cabal` when calling `cabal test`.<br/>
Below is an example which can be useful for projects with a Travis configuration based on [multi-ghc-travis](https://github.com/hvr/multi-ghc-travis):
```yaml
run-cabal-test --cabal-name=cabal-1.18
```
## The hpc-coveralls command
This command parses the hpc generated output, converts its to Coveralls json format and finally sends it to coveralls.io over http.<br/>
Multiple test suites can be specified, in which case the coverage report will be made of the merged coverage data generated by the specified test suites.<br/>
For example, if your test suite are named `test1` and `test2`, use the command as follows:
```yaml
hpc-coveralls test1 test2
```
### Options
#### --exclude-dir
The `--exclude-dir` option allows to exclude source files located under a given directory from the coverage report.<br/>
You can exclude source files located under the `test/` by using this option as in the following example:
```yaml
hpc-coveralls --exclude-dir=test [test-suite-names]
```
You can specify multiple excluded folders by using the following example syntax:
```yaml
hpc-coveralls --exclude-dir=test1 --exclude-dir=test2 [test-suite-names]
```
#### --coverage-mode
As Coveralls doesn't support partial-line coverage yet, hpc-coveralls currently converts hpc coverage data into line based coverage data, which is the only format supported at the moment.
The `--coverage-mode` option allows to configure how the coverage data is converted into Coveralls format, based on your needs.<br/>
Below are the two modes currently available, with an explanation of what the hit count values mean.
`--coverage-mode=AllowPartialLines` (default):
- `0` : the line is never hit,
- `1` : the line is partially covered,
- `2` : the line is fully covered.
Note that `AllowPartialLines` conversion mode follows the same convention as the one used by [cloverage](https://github.com/lshift/cloverage) coveralls output for Clojure projects code coverage.
`--coverage-mode=StrictlyFullLines`:
- `0` : the line is never hit or only partially covered,
- `1` : the line is fully covered.
Please also note that there is an [open issue](https://github.com/lemurheavy/coveralls-public/issues/216) on coveralls issue tracker in order to improve this (add support for partial line coverage).
#### --dont-send
The `--dont-send` option prevents hpc-coveralls from sending the coverage report to coveralls.io.
This option can be used together with `--display-report` for testing purpose.<br/>
For example, you can try various combinations of the other options and confirm the difference in the resulting report outputs.
# Contributing
hpc-coveralls is still under development and any contributions are welcome!
[Future Plans and Ideas](https://github.com/guillaume-nargeot/hpc-coveralls/wiki/Future-Plans-and-Ideas)
Please share your comments and suggestions on hpc-coveralls [Gitter channel](https://gitter.im/guillaume-nargeot/hpc-coveralls)!
# License
BSD3 ([tl;dr](https://tldrlegal.com/license/bsd-3-clause-license-(revised)))
# Notes
- HPC publication: http://ittc.ku.edu/~andygill/papers/Hpc07.pdf