Coverage

Description

Measures the coverage of the unit tests with kcov. FPC does not emit the .gcno and .gcda files that gcov and lcov read, but kcov needs no instrumentation: it reads the DWARF line info of the test executable and sets a breakpoint on each line, so any FPC executable with debug info works.

Example:

pasc coverage

Like pasc test, the command looks for the test project in the current folder or in a tests subfolder. Then it:

• Adds a Coverage build mode to the .lpi of the test project when it is missing. It has the options of the Default one, with the same search paths, which pasc deps keeps in sync, plus DWARF 3 debug info, no optimization, so lines are not merged or removed, and no heaptrc. The units go to lib/coverage, so they do not get mixed with the Default build, and the executable stays next to the Default one as Test<name>-coverage, so tests that find their files from the folder of the executable still work.

• Builds the test project with lazbuild --bm=Coverage and runs the tests under kcov, counting only the sources of the project: its src folder, without the tests and the modules.

• Shows the report of the tests, the coverage of each source file and the path of the HTML report, written to a coverage folder at the root of the project or workspace. When the project is in a git repository, the folder and the Test<name>-coverage executable are added to the .gitignore at that root if git does not ignore them yet.

Coverage apps/cmd 94.00% (47/50 lines)
          89.66%   26/29  src/commands/Command.Count.pas
         100.00%   21/21  src/commands/Command.Greet.pas
  Report coverage/cmd/index.html

At the root of a workspace it covers every member that has a tests folder, shows the total and merges the reports of the members in coverage/index.html.

Units that no test uses

kcov only sees the units linked into the test executable. A unit that no test uses, directly or indirectly, does not appear in its report, instead of appearing with 0%, which would make the percentage look better than it is. The command lists those units, the ones with code, so the gap is visible:

Not counted src/features/health/Health.Routes.pas (no test uses it)

Units with only declarations, like types and constants, have no line for kcov and are not listed.

Options

• –min=<percent> exits with 1 when the coverage, or the total of the workspace, is below the given percentage, which is useful in a CI: pasc coverage --min=80.

• –open opens the HTML report in the browser.

The exit code is 1 when the build fails, when the tests could not run or any of them failed, and when the coverage is below –min.

Installing kcov

kcov runs on Linux and macOS, not on Windows. When it is not in the PATH, the command shows how to install it:

• Arch Linux: sudo pacman -S kcov

• Debian 13: sudo apt install kcov

• Fedora: sudo dnf install kcov

• macOS: brew install kcov

Ubuntu 24.04 has no kcov package; it can be built from the sources, as the kcov repository explains.

Next Deps Command

---

Generated by PasDoc 1.0.4.