hpc-coveralls

hpc-coveralls converts and sends Haskell projects hpc code coverage to coverall.io.

At the moment, only Travis CI has been tested, but hpc-coveralls should be compatible with other CI services (Check HpcCoverallsMain source 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:

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:

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 .travis.yml file (result on coveralls). You can also refer to the .travis.yml file of hpc-coveralls itself, which is configured with 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:

/^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.
Below is an example which can be useful for projects with a Travis configuration based on multi-ghc-travis:

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.
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.
For example, if your test suite are named test1 and test2, use the command as follows:

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.
You can exclude source files located under the test/ by using this option as in the following example:

hpc-coveralls --exclude-dir=test [test-suite-names]

You can specify multiple excluded folders by using the following example syntax:

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

Please share your comments and suggestions on hpc-coveralls Gitter channel!

License

BSD3 (tl;dr)

Notes

• HPC publication: http://ittc.ku.edu/~andygill/papers/Hpc07.pdf