| # Kover Code Coverage Example | |
| This example demonstrates how to use [Kover](https://kotlin.github.io/kotlinx-kover/) as an | |
| alternative to JaCoCo for Kotlin code coverage in rules_kotlin. | |
| Unlike JaCoCo, Kover uses a JVM agent for runtime instrumentation, so application code does not | |
| need to be recompiled with coverage flags. | |
| ## Setup | |
| Enable Kover in your toolchain definition: | |
| ```starlark | |
| load("@rules_kotlin//kotlin:core.bzl", "define_kt_toolchain") | |
| define_kt_toolchain( | |
| name = "kotlin_toolchain", | |
| experimental_kover_enabled = True, | |
| experimental_kover_agent = "@maven//:org_jetbrains_kotlinx_kover_jvm_agent", | |
| ) | |
| ``` | |
| Add the Kover JVM agent to your Maven dependencies: | |
| ```starlark | |
| maven.install( | |
| artifacts = [ | |
| "org.jetbrains.kotlinx:kover-jvm-agent:0.8.3", | |
| ... | |
| ], | |
| ) | |
| ``` | |
| Register the toolchain in `MODULE.bazel`: | |
| ```starlark | |
| register_toolchains("//:kotlin_toolchain") | |
| ``` | |
| ## Running coverage | |
| From `examples/kover` with Bazel 9.3.2 on Linux or macOS, run the same coverage test with output path | |
| mapping disabled and enabled. Use `--modify_execution_info` to opt the sandboxed | |
| `KotlinCompile` actions into path mapping for this run. | |
| ```sh | |
| for mode in off strip; do | |
| bazel coverage --experimental_output_paths="$mode" --strategy=KotlinCompile=sandboxed \ | |
| --modify_execution_info=KotlinCompile=+supports-path-mapping \ | |
| --incompatible_enable_proto_toolchain_resolution --@@protobuf+//bazel/toolchains:prefer_prebuilt_protoc=true \ | |
| --nocache_test_results --run_under=//app:check_report //app:greeter_test || exit 1 | |
| done | |
| ``` | |
| To inspect the mapping, add `--execution_log_json_file=/tmp/kover-$mode.json` inside | |
| the loop. In the `KotlinCompile` spawn for `//app:greeter`, the `--flagfile` path | |
| uses `bazel-out/cfg/bin` in strip mode and the configuration directory in off mode. | |
| The wrapper runs Kover CLI 0.8.3 in the test's runfiles workspace after the JVM exits. | |
| The argument file contains one argument per line. Source and JAR paths are relative | |
| to that workspace, including files from external repositories. The wrapper checks that | |
| the XML records a covered line in `Greeter.greet` and saves `greeter.xml` and | |
| `greeter_test-kover_report.ic` under `bazel-testlogs/app/greeter_test/test.outputs/`. | |
| Plain `bazel coverage //app:greeter_test` runs the agent. Use the example wrapper | |
| to keep its binary report after Bazel discards the test sandbox. |