Documentation/technotes/2021-05-code-coverage.md

   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`.