Kover - Gradle plugin for Kotlin code coverage agents: IntelliJ and JaCoCo.
Minimal supported Gradle version: 6.4.
- Collecting code coverage for
JVMtest tasks XMLandHTMLreport generation- Support of
Kotlin/JVM,Kotlin Multiplatformand mixedKotlin-Javasources with zero additional configuration Kotlin Androidsupport without the need to divide into build types and flavours- Customizable filters for instrumented classes
In top-level build file:
Kotlin
plugins {
id("org.jetbrains.kotlinx.kover") version "0.5.0-RC"
}Groovy
plugins {
id 'org.jetbrains.kotlinx.kover' version '0.5.0-RC'
}In top-level build file:
Kotlin
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath("org.jetbrains.kotlinx:kover:0.5.0-RC")
}
}
apply(plugin = "kover")Groovy
buildscript {
repositories {
mavenCentral()
}
dependencies {
classpath 'org.jetbrains.kotlinx:kover:0.5.0-RC'
}
}
apply plugin: 'kover' To apply the plugin to all Gradle projects, you only need to apply the plugin to the top-level build file as shown above. Applying the plugin to subprojects if you have already applied it to the root project will cause configuration errors.
Once applied, the Kover plugin can be used out of the box without additional configuration.
However, in some cases, custom settings are needed - this can be done by configuring special extensions and tasks.
If you need to disable or filter instrumentation for a test task, you may configure the Kover extension for it.
For example, to configure a standard test task for Kotlin/JVM named test, you need to add the following code to the build script of the project where this task is declared:
Kotlin
tasks.test {
extensions.configure(kotlinx.kover.api.KoverTaskExtension::class) {
isDisabled = false
binaryReportFile.set(file("$buildDir/custom/result.bin"))
includes = listOf("com.example.*")
excludes = listOf("com.example.subpackage.*")
}
}Groovy
tasks.test {
kover {
disabled = false
binaryReportFile.set(file("$buildDir/custom/result.bin"))
includes = ['com.example.*']
excludes = ['com.example.subpackage.*']
}
}For other platforms (Android, Kotlin-Multiplatform) the names may differ and you may also have several test tasks, so you first need to determine the name of the required task.
Example of configuring test task for build type debug in Android:
Kotlin
android {
// other Android declarations
testOptions {
unitTests.all {
if (it.name == "testDebugUnitTest") {
it.extensions.configure(kotlinx.kover.api.KoverTaskExtension::class) {
isDisabled = false
binaryReportFile.set(file("$buildDir/custom/debug-report.bin"))
includes = listOf("com.example.*")
excludes = listOf("com.example.subpackage.*")
}
}
}
}
}Groovy
android {
// other Android declarations
testOptions {
unitTests.all {
if (name == "testDebugUnitTest") {
kover {
disabled = false
binaryReportFile.set(file("$buildDir/custom/debug-report.bin"))
includes = ['com.example.*']
excludes = ['com.example.subpackage.*']
}
}
}
}
}Aggregated reports combine classpath and coverage stats from the project in which the plugin is applied and all of its subprojects.
If you need to change the name of the XML report file or HTML directory, you may configure the corresponding tasks in the project in which the plugin is applied (usually this is the root project):
Kotlin
tasks.koverHtmlReport {
isEnabled = true // false to disable report generation
htmlReportDir.set(layout.buildDirectory.dir("my-agg-report/html-result"))
}
tasks.koverXmlReport {
isEnabled = true // false to disable report generation
xmlReportFile.set(layout.buildDirectory.file("my-agg-report/result.xml"))
}Groovy
tasks.koverHtmlReport {
enabled = true // false to disable report generation
htmlReportDir.set(layout.buildDirectory.dir("my-reports/html-result"))
}
tasks.koverXmlReport {
enabled = true // false to disable report generation
xmlReportFile.set(layout.buildDirectory.file("my-reports/result.xml"))
}If you need to change the name of the XML report file or HTML directory for a specific project, you may configure the corresponding tasks in this project:
Kotlin
tasks.koverHtmlProjectReport {
isEnabled = true // false to disable report generation
htmlReportDir.set(layout.buildDirectory.dir("my-project-report/html-result"))
}
tasks.koverXmlProjectReport {
isEnabled = true // false to disable report generation
xmlReportFile.set(layout.buildDirectory.file("my-project-report/result.xml"))
}Groovy
tasks.koverHtmlProjectReport {
enabled = true // false to disable report generation
htmlReportDir.set(layout.buildDirectory.dir("my-project-report/html-result"))
}
tasks.koverXmlProjectReport {
enabled = true // false to disable report generation
xmlReportFile.set(layout.buildDirectory.file("my-project-report/result.xml"))
}You may collect all project reports into one directory using the koverCollectProjectsReports task.
Also, you may specify a custom directory to collect project reports in the build directory of the project in which the plugin
is applied (usually this is the root project):
Kotlin
tasks.koverCollectProjectsReports {
outputDir.set(layout.buildDirectory.dir("all-projects-reports") )
}Groovy
tasks.koverCollectProjectsReports {
outputDir.set(layout.buildDirectory.dir("all-projects-reports") )
}In the project in which the plugin is applied, you can configure the following properties:
Kotlin
kover {
isDisabled = false // true to disable instrumentation of all test tasks in all projects
coverageEngine.set(kotlinx.kover.api.CoverageEngine.INTELLIJ) // change instrumentation agent and reporter
intellijEngineVersion.set("1.0.640") // change version of IntelliJ agent and reporter
jacocoEngineVersion.set("0.8.7") // change version of JaCoCo agent and reporter
generateReportOnCheck.set(true) // false to do not execute `koverReport` task before `check` task
disabledProjects = setOf() // setOf("project-name") to disable coverage for project with name `project-name`
instrumentAndroidPackage = false // true to instrument packages `android.*` and `com.android.*`
}Groovy
kover {
disabled = false // true to disable instrumentation of all test tasks in all projects
coverageEngine.set(kotlinx.kover.api.CoverageEngine.INTELLIJ) // change instrumentation agent and reporter
intellijEngineVersion.set('1.0.640') // change version of IntelliJ agent and reporter
jacocoEngineVersion.set('0.8.7') // change version of JaCoCo agent and reporter
generateReportOnCheck.set(true) // false to do not execute `koverReport` task before `check` task
disabledProjects = [] // ["project-name"] to disable coverage for project with name `project-name`
instrumentAndroidPackage = false // true to instrument packages `android.*` and `com.android.*`
}You may specify one or more rules that check the values of the code coverage counters.
Validation rules work for both types of agents.
The plugin currently only supports line counter values.
To add a rule to check coverage from the code of all projects, you need to add configuration to the project in which the plugin is applied (usually this is the root project):
Kotlin
tasks.koverVerify {
rule {
name = "Minimum number of lines covered"
bound {
minValue = 100000
valueType = kotlinx.kover.api.VerificationValueType.COVERED_LINES_COUNT
}
}
rule {
// rule without a custom name
bound {
minValue = 1
maxValue = 1000
valueType = kotlinx.kover.api.VerificationValueType.MISSED_LINES_COUNT
}
}
rule {
name = "Minimal line coverage rate in percent"
bound {
minValue = 50
// valueType is kotlinx.kover.api.VerificationValueType.COVERED_LINES_PERCENTAGE by default
}
}
}Groovy
tasks.koverVerify {
rule {
name = "Minimum number of lines covered"
bound {
minValue = 100000
valueType = 'COVERED_LINES_COUNT'
}
}
rule {
// rule without a custom name
bound {
minValue = 1
maxValue = 1000
valueType = 'MISSED_LINES_COUNT'
}
}
rule {
name = "Minimal line coverage rate in percent"
bound {
minValue = 50
// valueType is 'COVERED_LINES_PERCENTAGE' by default
}
}
}To add rules for code coverage checks for one specific project, you need to add a configuration to this project:
Kotlin
tasks.koverProjectVerify {
rule {
name = "Minimal line coverage rate in percent"
bound {
minValue = 75
}
}
}Groovy
tasks.koverProjectVerify {
rule {
name = "Minimal line coverage rate in percent"
bound {
minValue = 75
}
}
}The plugin, when applied, automatically creates tasks for the project in which it is applied (usually this is the root project):
koverHtmlReport- Generates code coverage HTML report for all enabled test tasks in all projects.koverXmlReport- Generates code coverage XML report for all enabled test tasks in all projects.koverReport- Executes bothkoverXmlReportandkoverHtmlReporttasks. Executes beforechecktask if propertygenerateReportOnCheckforKoverExtensionistrue(see).koverVerify- Verifies code coverage metrics of all projects based on specified rules. Always executes beforechecktask.koverCollectProjectsReports- Collects all projects reports into one directory. Default directory is$buildDir/reports/kover/projects, names for XML reports and dirs for HTML are projects names. Executing this task does not runkoverXmlReportorkoverHtmlReport, it only copies previously created reports if they exist to the output directory.
Tasks that are created for all projects:
koverHtmlProjectReport- Generates code coverage HTML report for all enabled test tasks in one project.koverXmlProjectReport- Generates code coverage XML report for all enabled test tasks in one project.koverProjectReport- Executes bothkoverXmlProjectReportandkoverHtmlProjectReporttasks.koverProjectVerify- Verifies code coverage metrics of one project based on specified rules. Always executes beforechecktask.
While the plugin is being applied, the artifacts of the JaCoCo or IntelliJ toolkit are dynamically loaded. They are downloaded from the mavenCentral repository.
For the plugin to work correctly, you need to make sure that the mavenCentral (or its mirror) is added to the repository list of the project in which the plugin is applied, if it doesn't already exist (usually this is the root project):
Kotlin
repositories {
mavenCentral()
}Groovy
repositories {
mavenCentral()
}