The hpc-coveralls package

[Tags: bsd3, library, program]

This utility converts and sends Haskell projects hpc code coverage to coverall.io.

Usage

Below is the simplest example of .travis.yml configuration to use with Travis CI:

 language: haskell
 ghc: 7.8
 script:
   - cabal configure --enable-tests --enable-library-coverage && cabal build && cabal test
 after_script:
   - cabal install hpc-coveralls
   - hpc-coveralls [options] [test-suite-names]

Further information can be found in the README.


[Skip to ReadMe]

Properties

Versions0.1.0, 0.1.2, 0.2.0, 0.2.1, 0.2.2, 0.3.0, 0.4.0, 0.5.0, 0.6.0, 0.6.1, 0.7.0, 0.8.0, 0.8.1, 0.8.2, 0.8.3, 0.9.0
Change logCHANGELOG.md
Dependenciesaeson, async (>=2.0), base (==4.*), bytestring (>=0.10), cmdargs (>=0.10), containers (>=0.5), curl (>=1.3.8), directory (>=1.2), directory-tree (>=0.12), hpc (>=0.6), process (>=1.1.0.1), pureMD5 (>=2.1), regex-posix, retry (>=0.5), safe (>=0.3), split [details]
LicenseBSD3
Copyright(c) 2014-2015 Guillaume Nargeot
AuthorGuillaume Nargeot
MaintainerGuillaume Nargeot <guillaume+hackage@nargeot.com>
Stabilityexperimental
CategoryControl
Home pagehttps://github.com/guillaume-nargeot/hpc-coveralls
Bug trackerhttps://github.com/guillaume-nargeot/hpc-coveralls/issues
Source repositoryhead: git clone https://github.com/guillaume-nargeot/hpc-coveralls.git
Executablesrun-cabal-test, hpc-coveralls
UploadedSun Mar 1 05:33:58 UTC 2015 by killy971
DistributionsLTSHaskell:0.9.0, Stackage:0.9.0
Downloads6637 total (271 in last 30 days)
Votes
0 []
StatusDocs available [build log]
Last success reported on 2015-03-01 [all 1 reports]

Modules

[Index]

Downloads

Maintainers' corner

For package maintainers and hackage trustees

Readme for hpc-coveralls-0.9.0

hpc-coveralls

Build Status Gitter chat BSD3 License Version on Hackage Stories in Ready

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

Below is the simplest example of configuration for your project .travis.yml:

language: haskell
ghc: 7.8
script:
  - cabal configure --enable-tests --enable-library-coverage && cabal build && cabal test
after_script:
  - cabal install hpc-coveralls
  - hpc-coveralls [options] [test-suite-names]

When building with Cabal 1.22 or a newer version, use the --enable-coverage flag instead of --enable-library-coverage.

If the build fails during the test phase with an error message starting by "hpc:", just 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]

This will prevent the build to fail because of hpc related reasons, which are usually not fatal and should not affect the coverage data. Details are available in the next section.

You may also experience some issues related to your project dependencies, which can be solved by using the --avoid-reinstalls/--force-reinstalls flags.</br> Another way to solve problems related dependencies is to install hpc-coveralls in a sandbox, as in the example below:

after_script:
  - cabal sandbox init && cabal install hpc-coveralls
  - .cabal-sandbox/bin/hpc-coveralls [options] [test-suite-names]

For a real world example usage, please refer to this-project .travis.yml file (result on coveralls).<br/> Other real world examples can be found on this wiki page which contains a list of GitHub repositories using hpc-coveralls.

The run-cabal-test command

Under certain conditions related to the project structure and the version of hpc, cabal test may output an error message and exit with the error code 1, which would result in a build failure.<br/>

To prevent this from happening, hpc-coveralls provides the run-cabal-test command which runs cabal test and returns with 0 if the following regular expression never matches any line of the output:

/^Test suite .*: FAIL$/

Below are some of the conditions under which you will likely need to use run-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:

run-cabal-test --cabal-name=cabal-1.20

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:

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/ directory 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.<br/> Below are the two modes currently available, with an explanation of what the hit count values mean.

--coverage-mode=AllowPartialLines (default):

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:

Please also note that there is an open issue on coveralls issue tracker in order to improve this (add support for partial line coverage).

--repo-token

This option allows to specify your repo token when sending the report to coveralls.io.

--display-report

This boolean option prints the raw json coverage report to be sent to coveralls.io.

--dont-send

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

--curl-verbose

This boolean option enables curl verbose mode and prints the raw json response received after posting the coverage report to coveralls.io.

Limitations

Because of the way hpc works, coverage data is only generated for modules that are referenced directly or indirectly by the test suites. As a result, the total package coverage computed by coveralls may be higher than what it really is. An option will be added soon in order to allow specifying source folders to include in the total coverage computation.

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