git.iko.soy/haskell.nix
on 40c9713 help sign in
haskell.nix/docs/tutorials/coverage.md
123 lines 3.7 kB history raw
1# Coverage
3haskell.nix can generate coverage information for your package or
4project using Cabal's inbuilt hpc support.
6## Prerequisites
8To get a sensible coverage report, you need to enable coverage on each
9of the packages of your project:
11```nix
12pkgs.haskell-nix.project {
13 src = pkgs.haskell-nix.haskellLib.cleanGit {
14 name = "haskell-nix-project";
15 src = ./.;
16 };
17 compiler-nix-name = "ghc884";
19 modules = [{
20 packages.$pkg.components.library.doCoverage = true;
21 }];
23```
25If you would like to make coverage optional, add an argument to your nix expression:
27```nix
28{ withCoverage ? false }:
30pkgs.haskell-nix.project {
31 src = pkgs.haskell-nix.haskellLib.cleanGit {
32 name = "haskell-nix-project";
33 src = ./.;
34 };
35 compiler-nix-name = "ghc884";
37 modules = pkgs.lib.optional withCoverage [{
38 packages.$pkg.components.library.doCoverage = true;
39 }];
41```
43## Per-package
45```bash
46nix-build default.nix -A "projectWithCoverage.$pkg.coverageReport"
47```
49This will generate a coverage report for the package you requested.
50All tests that are enabled (configured with `doCheck == true`) are
51included in the coverage report.
53See the [developer coverage docs](../dev/coverage.md#package-reports) for more information.
55## Project-wide
57```bash
58nix-build default.nix -A "projectWithCoverage.projectCoverageReport"
59```
61This will generate a coverage report for all the local packages in
62your project.
64See the [developer coverage docs](../dev/coverage.md#project-wide-reports) for more information.
66## Custom
68By default, the behaviour of the `coverageReport` attribute is to
69generate a coverage report that describes how that package affects the
70coverage of all local packages (including itself) in the project.
72The default behaviour of `projectCoverageReport` is to sum the
73default coverage reports (produced by the above process) of all local
74packages in the project.
76You can modify this behaviour by using the `coverageReport` and
77`projectCoverageReport` functions found in the haskell.nix library:
79```nix
80let
81 inherit (pkgs.haskell-nix) haskellLib;
83 project = haskellLib.project {
84 src = pkgs.haskell-nix.haskellLib.cleanGit {
85 name = "haskell-nix-project";
86 src = ./.;
87 };
88 compiler-nix-name = "ghc884";
90 modules = [{
91 packages.$pkgA.components.library.doCoverage = true;
92 packages.$pkgB.components.library.doCoverage = true;
93 }];
94 };
96 # Generate a coverage report for $pkgA that only includes the
97 # unit-test check and only shows coverage information for $pkgA, not
98 # $pkgB.
99 custom$pkgACoverageReport = haskellLib.coverageReport rec {
100 name = "$pkgA-unit-tests-only"
101 inherit (project.$pkgA.components) library;
102 checks = [project.$pkgA.components.checks.unit-test];
103 # Note that this is the default value of the "mixLibraries"
104 # argument and so this line isn't really necessary.
105 mixLibraries = [project.$pkgA.components.library];
106 };
108 custom$pkgBCoverageReport = haskellLib.coverageReport rec {
109 name = "$pkgB-unit-tests-only"
110 inherit (project.$pkgB.components) library;
111 checks = [project.$pkgB.components.checks.unit-test];
112 mixLibraries = [project.$pkgB.components.library];
113 };
115 # Generate a project coverage report that only includes the unit
116 # tests of the project, and only shows how each unit test effects
117 # the coverage of it's package, and not other packages in the
118 # project.
119 allUnitTestsProjectReport = haskellLib.projectCoverageReport [custom$pkgACoverageReport custom$pkgBCoverageReport];
120in {
121 inherit project custom$pkgACoverageReport custom$pkgBCoverageReport allUnitTestsProjectCoverageReport;
123```