kotlinx-kover

Kover is a Gradle plugin designed to measure code coverage for tests running on the JVM and generate coverage reports. It supports both Kotlin JVM and Kotlin Multiplatform projects, including Android projects with build variants.

Key features include:

• Coverage Collection: Measures coverage through JVM tests (note: JS and native targets are currently unsupported).
• Report Generation: Produces HTML and XML reports.
• Verification: Allows setting verification rules with bounds to enforce coverage thresholds.
• Automatic Task Management: Automatically creates report tasks and manages dependencies between them.
• Smart Detection: Automatically detects project source code, compilation tasks, test tasks, and Android build variants to configure Kover tasks.
• Language Support: Supports mixed Kotlin and Java sources.
• JaCoCo Integration: Can use the JaCoCo library as an alternative for measuring coverage and generating reports.

Starting with 0.8.0, the concept of 'default reports' has been replaced by Total reports and Custom reports.

To combine multiple targets (e.g., a JVM target and an Android 'release' variant) into a single report, you must create a custom variant. A variant is a collection of project classes, test tasks, and exclusion rules.

Steps to create a custom variant:

1. Define the variant in kover.currentProject.createVariant("name").
2. Use add("variantName") to include existing targets (like jvm or Android build variants).
3. Configure report settings for that variant in kover.reports.variant("name").

Task Naming Convention: Kover automatically generates tasks for your custom variant using the pattern: kover<Type>Report<VariantName>. For a variant named custom, tasks include koverHtmlReportCustom, koverXmlReportCustom, etc.

kover {
    currentProject {
        createVariant("custom") {
            add("jvm")
            add("release")
        }
    }

    reports {
        variant("custom") {
            filters {
                // filters only for custom variant
            }
        }
    }
}

Kover functional tests run Gradle in a separate system process and verify the results. There are five distinct test types available for different testing scenarios:

1. examples: Tests run against ready-made projects located in the examples subdirectory. These projects must use the latest release version of the plugin (defined by the releaseVersion property).
2. templates: Tests targeting specific rare cases using projects located in the templates directory. You can execute any Gradle command for these projects.
3. single generated test: Tests that launch a project without pre-existing source code. The project is built dynamically using a BuildConfigurator within the test code, allowing for versatile configurations of script languages, Kotlin plugins, or coverage tools.
4. sliced generated test: Similar to single generated tests, but executed multiple times across different combinations of script language, Kotlin Plugin type, and Coverage Tool (collectively referred to as a "slice").
5. simple test: Tests that do not perform any actions with Gradle; all logic must be implemented manually within the test code using available functions.

Filtering allows you to include or exclude specific classes from reports and verification.

Filter Types

• classes: Filter by fully-qualified class name (supports wildcards * and ?).
• annotatedBy: Filter by annotations (requires BINARY or RUNTIME retention).
• inheritedFrom: Filter by class/interface inheritance.

Priority and Levels

Filters can be defined at different levels:

1. Common level: Applies to all variants in the project.
2. Variant level: Applies to a specific report variant (e.g., total or release).

Important Rules:

• If both includes and excludes are specified, excludes have priority.
• A higher-priority filter (variant level) completely replaces the rules from the level below (common level).
• To disable all filtering, use an empty filter block: filters { }.

Note: Additional filters like annotatedBy do not work when using the JaCoCo coverage library.

kover {
    reports {
        // Common filters for all variants
        filters {
            excludes {
                classes("com.example.Class1", "com.example.Class2")
            }
            includes {
                classes("com.example.Class1", "com.example.Class3")
            }
        }

        // Overriding filters for a specific variant
        variant("release") {
            filters {
                excludes {
                    classes("com.example.OtherClass")
                }
            }
        }
    }
}