1  # Unit Test Code Coverage
 2  
 3  Code coverage for the coreboot unit tests allows us to see what lines of
 4  code in the coreboot library are covered by unit tests, and allows a test
 5  author to see where they need to add test cases for additional coverage.
 6  
 7  Code coverage requires `lcov`; install the tool if necessary by
 8  `sudo apt install lcov` or the equivalent for your system.
 9  
10  Enable code coverage in your unit test build by setting the environment
11  variable `COV` to 1; either `export COV=1` in your shell, or add it to your
12  `make` command, e.g. `COV=1 make unit-tests`.
13  
14  The build output directory is either `build/tests` or `build/coverage`,
15  depending on whether `COV=1` is set in the environment.
16  
17  All of the unit test targets are available with and without `COV=1`
18  * `clean-unit-tests`
19  * `build-unit-tests`
20  * `run-unit-tests`
21  * `unit-tests` (which is just `build-unit-tests` followed by `run-unit-tests`)
22  
23  There are two new `make` targets:
24  * `coverage-report` generates a code coverage report from all of the
25  GCOV data (`*.gcda` and `*.gcno` files) in the build directory. To view the
26  coverage report, open `build/coverage/coverage_reports/index.html` in your web
27  browser.
28  * `clean-coverage-report` deletes just the coverage report.
29  
30  The `coverage-report` and `clean-coverage-report` targets automatically set
31  `COV=1` if it is not already set in the environment.
32  
33  
34  ## Examples
35  
36  `COV=1 make unit-tests coverage-report` builds all of the unit tests with code
37  coverage, runs the unit tests, and generates the code coverage report.
38  
39  `COV=1 make build-unit-tests` builds all of the unit tests with code coverage.
40  
41  `COV=1 make run-unit-tests` runs the unit tests, building them with code
42  coverage if they are out-of-date.
43  
44  `COV=1 make coverage-report` creates the code coverage report. This
45  target does not explicitly depend on the tests being built and run; it gathers
46  the code coverage data from the output directory, which it assumes already
47  exists.
48  
49  `COV=1 make tests/lib/uuid-test coverage-report` builds the uuid test
50  with code coverage, runs it, and generates a code coverage report just for
51  that test.
52  
53  As a demonstration that building with and without coverage uses different
54  output directories:
55  1. `make build-unit-tests` builds unit tests without code coverage into
56  `build/tests`.
57  2. `COV=1 make clean-unit-tests` cleans `build/coverage`
58  3. `make build-unit-tests` doesn't need to build anything in `build/tests`,
59  because those files weren't affected by the previous `clean-unit-tests`.