kotlin/kotlin-native/CODE_COVERAGE.md

Code Coverage

Kotlin/Native has a code coverage support that is based on Clang's Source-based Code Coverage.

Please note:

1. ⚠️ Coverage support is far from being ready for usage. Known issues are:

   • Coverage information may be inaccurate.
   • Line execution counts may be wrong.
   • The thing might just not work.

2. Most of described functionality will be incorporated into Gradle plugin.

Usage

TL;DR

kotlinc-native main.kt -Xcoverage
./program.kexe
llvm-profdata merge program.kexe.profraw -o program.profdata
llvm-cov report program.kexe -instr-profile program.profdata

Compiling with coverage enabled

There are 2 compiler flags that allows to generate coverage information:

• -Xcoverage. Generate coverage for immediate sources.
• -Xlibrary-to-cover=<path>. Generate coverage for specified klib. Note that library also should be either linked via -library/-l compiler option or be a transitive dependency.

Running covered executable

After the execution of the compiled binary (ex. program.kexe) program.kexe.profraw will be generated. By default it will be generated in the same location where binary was created. The are two ways to override this behavior:

• -Xcoverage-file=<path> compiler flag.
• LLVM_PROFILE_FILE environment variable. So if you run your program like this:

LLVM_PROFILE_FILE=build/program.profraw ./program.kexe

Then the coverage information will be stored to the build dir as program.profraw.

Parsing *.profraw

Generated file can be parsed with llvm-profdata utility. Basic usage:

llvm-profdata merge default.profraw -o program.profdata

See command guide for more options.

Creating reports

The last step is to create a report from the program.profdata file. It can be done with llvm-cov utility (refer to command guide for detailed usage). For example, we can see a basic report using:

llvm-cov report program.kexe -instr-profile program.profdata

Or show a line-by-line coverage information in html:

llvm-cov show program.kexe -instr-profile program.profdata  -format=html > report.html

Sample

Usually coverage information is collected during running of the tests. Please refer to samples/coverage to see how it can be done.

Useful links

• LLVM Code Coverage Mapping Format