hpc-codecov
Generate reports from hpc data
https://github.com/8c6794b6/hpc-codecov#readme
Version on this page: | 0.6.0.0 |
LTS Haskell 22.33: | 0.5.0.0 |
Stackage Nightly 2024-09-07: | 0.6.2.0 |
Latest on Hackage: | 0.6.2.0 |
hpc-codecov-0.6.0.0@sha256:9e0e5de725c7e95733996c3f61a2c1a314d77da7b1c59537f309c10fbaff492e,4170
Module documentation for 0.6.0.0
- Trace
hpc-codecov
![Stackage](https://www.stackage.org/package/hpc-codecov/badge/lts)
The hpc-codecov
package contains an executable and library codes
for generating Codecov JSON coverage report,
LCOV tracefile report,
or Cobertura XML report from
.tix
and .mix
files made with
hpc. The generated report
is ready to be uploaded to Codecov with other tools such as Codecov
uploader.
The hpc-codecov
executable can search .tix
and mix
files
under the directories made by the
cabal-install and
stack build tools.
The executable also has options to explicitly specify the file paths
and directories for .tix
and mix
files, to support generating
reports with test data made by other build tools than
cabal-install
and stack
.
Installing
From Package Repository
hpc-codecov
is available from
Hackage and
Stackage. To
install with cabal-install
, run:
$ cabal install hpc-codecov
To install with stack
, run:
$ stack install hpc-codecov
Pre-compiled binaries
For Windows, MacOS, and Linux (with glibc and libgmp), pre-compiled binary executables are available here.
QuickStart
To illustrate an example, initializing a sample project named
my-project
with cabal-install
:
$ cabal --version
cabal-install version 3.4.0.0
compiled using version 3.4.0.0 of the Cabal library
$ cabal init --simple --tests --test-dir=test -p my-project
The directory contents look like below:
.
├── app
│ └── Main.hs
├── CHANGELOG.md
├── my-project.cabal
├── src
│ └── MyLib.hs
└── test
└── MyLibTest.hs
Run tests with coverage option:
$ cabal test --enable-coverage
Write Codecov coverage report to codecov.json
:
$ hpc-codecov cabal:my-project-test -X my-project -o codecov.json
Show coverage report contents:
$ cat codecov.json
{"coverage":{"test/MyLibTest.hs":{"4":1}}}
Using in GitHub workflow
See hpc-codecov-action to generate Codecov coverage report from GitHub workflow.
Examples
Showing help
Show usage information:
$ hpc-codecov --help
Project using cabal-install
Search under the directory made by cabal-install
, generating a report
for a test suite named my-project-test
. Skip searching under the
directories with base name my-project
, and exclude modules named
Main
and Paths_my_project
from the report. Note the use of
comma to separate multiple values for the -x
option:
$ hpc-codecov -X my-project -x Main,Paths_my_project cabal:my-project-test
Project using cabal-install, count expressions only
Search under the directry made by cabal-install
, generating a
report for a test suite named my-project-test
. Ignore the entries
in .mix
file other than ExpBox
(i.e.; ignore TopLevelBox
,
LocalBox
, and BinBox
constructors of
BoxLabel
data in .mix
file).
$ hpc-codecov --expr-only cabal:my-project-test
Project using cabal-install, ignore compiler generated source codes
Search under the directory made by cabal-install
, generating a
report for a test suite named my-projejct-test
. Ignore the
consecutive .mix
entries with identical start and end source code
positions, which is a sign of compiler-generated source codes. The
--ignore-dittos
option may affects codes containing record field
declarations, derived instances, and TemplateHaskell.
$ hpc-codecov --ignore-dittos cabal:my-project-test
Project using stack
Search under the directory made by stack
for a test suite named
my-project-test
, show verbose information, and write output to
codecov.json
:
$ hpc-codecov --verbose -o codecov.json stack:my-project-test
Project using stack, with multiple packages
Search under the directory made by stack
for a combined report of
multiple cabal packages, and write output to codecov.json
:
$ hpc-codecov stack:all -o codecov.json
Project using stack, with multiple packages, generate LCOV tracefile
Search under the directory made by stack
for a combined report of
multiple cabal packages, and write the output report in LCOV tracefile
format to lcov.info
:
$ hpc-codecov stack:all -f lcov -o lcov.info
Project using stack, with multiple packages, generate Cobertura XML file
Search under the directory made by stack
for a combined report of
multiple cabal packages, and write output report in Cobertura XML
format to coverage.xml
:
$ hpc-codecov stack:all -f cobertura -o coverage.xml
Project using stack, running via Docker
Search under the directory made by stack
for a combined report of
multiple cabal packages, running via Docker:
$ docker run --rm -v $PWD:$PWD ghcr.io/8c6794b6/hpc-codecov hpc-codecov -r $PWD stack:all
Low-level examples
The following shows two examples for generating a test coverage report
of the hpc-codecov
package itself without specifying the build
tool. One with using the build artifacts made by cabal-install
Nix-style local build commands, and another with stack
.
With cabal-install
First, run the tests with the coverage option to generate .tix
and
mix
files:
$ cabal --version
cabal-install version 3.4.0.0
compiled using version 3.4.0.0 of the Cabal library
$ cabal v2-configure --enable-test --enable-coverage
$ cabal v2-test
Then generate a Codecov JSON coverage data from the .tix
and
.mix
files:
$ proj=hpc-codecov-0.4.0.0
$ tix=$(find ./dist-newstyle -name $proj.tix)
$ mix=$(find ./dist-newstyle -name vanilla -print -quit)/mix/$proj
$ hpc-codecov --mix=$mix --exclude=Paths_hpc_codecov --out=codecov.json $tix
The --out
option specifies the output file to write the JSON
report. Observing the contents of codecov.json
with
jq
:
$ jq . codecov.json | head -10
{
"coverage": {
"src/Trace/Hpc/Codecov/Options.hs": {
"48": 1,
"50": 1,
"52": 1,
"54": 1,
"56": 1,
"59": 1,
"63": 1,
Send the resulting JSON report file to Codecov with the Codecov
uploader. The file name
codecov.json
is listed in the uploader script as one of the file
name patterns to upload, no need to specify the report filename
explicitly:
$ codecov -t ${CODECOV_TOKEN}
According to the Codecov
FAQ, the
uploader should work from Travis,
CircleCI,
Azure,
and GitHub Actions for public
projects without the Codecov token (i.e., without the -t ${CODECOV_TOKEN}
option).
With stack
Build the package and run the tests with the coverage option:
$ stack --numeric-version
2.5.1
$ stack build --test --coverage
As done in cabal-install
example, specify the path of .tix
and
.mix
files. Using the path
sub-command to get the local hpc root
directory and dist directory:
$ hpcroot=$(stack path --local-hpc-root)
$ tix=$(find $hpcroot -name 'test-main.tix')
$ mix=$(stack path --dist-dir)/hpc
$ hpc-codecov --mix=$mix --exclude=Paths_hpc_codecov -o codecov.json $tix
References
Changes
Revision history for hpc-codecov
0.6.0.0 – 2024-04-26
-
Add “–expr-only” option. This option will ignore other constructor than ‘ExpBox’ in ‘Trace.Hpc.Mix.BoxLabel’ data type when collecting ‘Trace.Hpc.Mix.MixEntry’ info.
-
Add “–ignore-dittos” option. This option will remove the coverage info of repeated occurance of entries with identical start and end position.
As of mix data format generated by ghc 9.4/9.6/9.8, this option removes mix entries of record field declarations, type class member functions in derived instances (when the member function is more than two), and codes generated via TemplateHaskell.
0.5.0.0 – 2023-11-01
-
Add Cobertura XML format for the generated report with “–format=cobertura” option.
-
Modify “readMix’” to fill in the field of Mix values with the timestamp in a .mix file instead of a dummy value.
-
Drop support for GHC < 8.10.
-
Slightly tidy up the help message.
0.4.2.0 – 2023-10-18
-
Support GHC 9.8.1.
-
Update package dependency version bound for the
bytestring
package.
0.4.1.0 – 2023-09-17
- Update package dependency version bound for the
hpc
andtasty
packages.
0.4.0.0 – 2023-07-10
Add “–format” option to select the output report format. Add LCOV tracefile format for generated report.
Modify the generated report to preserve line hit counts.
Add simple ByteString
based parsers for reading .mix
and
.tix
files to improve performance.
Remove Paths_hpc_codecov
from exported modules.
0.3.0.0 – 2021-04-02
Modify command-line argument to support TOOL:TEST_SUITE style target, support searching .tix and .mix files made by cabal-install and stack. Add options to customize the search for .mix and .tix files with temporary directories made with cabal-install and stack.
Add new module Trace.Hpc.Codecov.Discover
. Rename module
Trace.Hpc.Codecov.Error
to Trace.Hpc.Codecov.Exception
.
Rename function main
to defaultMain
in
Trace.Hpc.Codecov.Main
.
0.2.0.2 – 2021-03-25
Minor modification to support GHC 9.0.1.
CI configuration update to manage git repository.
0.2.0.1 – 2021-01-02
Minor package dependency updates.
0.1.0.0 – 2020-02-08
Initial release.