Haskell Program Coverage (Hpc) is a tool-kit to record and display Haskell Program Coverage. Hpc includes tools that instrument Haskell programs to record program coverage, run instrumented programs, and display the coverage information obtained.
Typically coverage tools are used to determine if test suites is actually innovating parts of a program.
Hpc is included with ghc-6.8.1, and no extra downloading or installing is needed!
There is an older version of hpc, called hpc-0.4, which used a source-to-source translator, and can be obtained from the authors.
% cat Main.hs
main = print ("Hello, World " ++ show (const 1 2))
To compile use the ghc-6.8.1 (or later) command line option -fhpc:
% ghc -fhpc Main.hs
[1 of 1] Compiling Main ( Main.hs, Main.o )
Linking Main ...
% ./a.out
"Hello, World 1"
% hpc report a.out
85% expressions used (6/7)
100% boolean coverage (0/0)
100% guards (0/0)
100% 'if' conditions (0/0)
100% qualifiers (0/0)
100% alternatives used (0/0)
100% local declarations used (0/0)
You run an instrumented binary, and then run hpc markup after execution. (If you have have just run the example about, there is no need to re-compile and re-run the binary; the coverage information is preserved in the file Main.tix)
% ./a.out % hpc markup Main Writing: Main.hs.html Writing: hpc_index.html Writing: hpc_index_fun.html Writing: hpc_index_alt.html Writing: hpc_index_exp.html
Now we have a file, Main.hs.html, which looks like this
1 main = print ("Hello, World " ++ show (const 1 2)) |
The number 1 at the start of the line is the line number, and we can
see that '2' is highlighted; it was never evaluated during the
execution of this program. We have also generated some index files,
that list all the modules in our
executable. hpc_index.html looks like this.
| module | Top Level Definitions | Alternatives | Expressions | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| % | covered / total | % | covered / total | % | covered / total | ||||||||
| module Main | 100% | 1/1 | - | 0/0 | 85% | 6/7 | |||||||
| Program Coverage Total | 100% | 1/1 | - | 0/0 | 85% | 6/7 | |||||||
| File | Summary | Location Example |
Contents Example |
|---|---|---|---|
| .tix | array of ticks, on for each location in the program, one per program | Main.tix, a.out.tix |
Tix [TixModule "Main" 123 9 [1,2,3,2,2,1,2,4], ...] |
| .mix | module specific information, mapping tick number to source location, one per module | .hpc/Main.mix, .hpc/Foo.mix |
Mix Main.hs" 1182484948 51696526 8 [(1:15-1:29,ExpBox False),...] |
hpc-build also uses .pix files, which are lists of modules involved in
If you run the same instrumented binary twice, the total coverage for
both invocations are added together. The .tix file is
placed in the current working directory, with the name
'BINARY-NAME.tix'. Each invocation of an instrumented Haskell program
looks for this .tix file, and updates the same file
with the extra .tix information from the current invocation.
If you have several .tix files from running a binary in different
directories, you can join then with the hpc sum
% hpc sum <file1.mix> <file2.mix> [...] -output==newfile.mix
hpc sum can also combine executions from different
binaries! Any modules shared between the binaries need to have been
compiled with the same options (specifically generate the same .mix
file), and we use a simple hash value to sanity check this property.
This feature can be used to combine a unit testing binaries with binaries
used for system-level tests, providing the ability to see what code
fragments were missed by both testing methodologies.
Yes. Look at the Hpc documentation released with GHC 6.8.1.
Hpc has a new badge, in the footsteps of the Cabal, QuickCheck and Catch badges.
Feel free to use it to promote the quality of your Haskell application or library, provided you actually use Hpc as part of your quality control process. Xmonad is a great example of Hpc usage, where Hpc is used to assess the quality of the QuickCheck tests.
You can copy it by right-clicking the picture, and the badge should link to http://www.haskell.org/hpc.
Thank you to Dana Herz from galois for creating it.
ghc-6.8.1 is out!
The tools provided with Hpc are
| Commands: | |
| help | Display help for hpc or a single command |
|---|---|
| Reporting Coverage: | |
| report | Output textual report about program coverage |
| markup | Markup Haskell source with program coverage |
| Processing Coverage files: | |
| sum | Sum multiple .tix files in a single .tix file |
| combine | Combine two .tix files in a single .tix file |
| map | Map a function over a single .tix file |
| Coverage Overlays: | |
| overlay | Generate a .tix file from an overlay file |
| draft | Generate draft overlay that provides 100% coverage |
| Others: | |
| show | Show .tix file in readable, verbose format |
| version | Display version for hpc |
use hpc help <command> to see more details.