Isolate Konsist Tests

Aim for better test separation.

Typically, it's advisable to consolidate all Konsist tests in a unified location. This approach is preferred because these tests are often designed to validate the structure of the entire project's codebase. There are three potential options for storing Konsist tests in project codebase:

	Android	Spring	KMP	Pure Kotlin
Existing Test Source Set	✅	✅	✅	✅
#dedicated-konsist-test-source-set	❌	✅	✅	✅
Dedicated Module	✅	✅	✅	✅

Recommended approach is to use Dedicated konsistTest Source Set or a Dedicated Module. These approaches allows to easily isolate Konsist tests from other types of tests e.g. separate unit tests from Konsist tests.

Existing Test Source Set

The Konsist library can be added to the project by adding the dependency on the existing test source set .

test sorce directory

To execute tests run ./gradlew test command.

The downside of this approach is that various types of tests are mixed in test source set e.g. unit tests and Konsist tests.

Dedicated konsistTest Source Set

This section demonstrates how to add the konsistTest test source directory inside the app module. This configuration is mostly useful for Spring and Kotlin projects.

This page describes the test located in the app module with the build config file located in app a folder. If the project does not contain any module then configuration should be applied in the root build config file.

This test directory will have a kotlin folder containing Kotlin code.

Gradle (Kotlin)

Use the Gradle built-in JVM Test Suite Plugin to define the konsistTest source set. Add a testing block to the project configuration:

// build.gradle.kts (root)

plugins {
    `jvm-test-suite`
}

testing {
    suites {
        register("konsistTest", JvmTestSuite::class) {
            dependencies {
                // Add 'main' source set dependency
                implementation(project())
                
                // Add Konsist dependency
                implementation("com.lemonappdev:konsist:0.13.0") 
            }
        }
    }
}

// Optional : Remove Konsist tests from the 'check' task if it exists
tasks.matching { it.name == "check" }.configureEach {
  setDependsOn(dependsOn.filter { it.toString() != "konsistTest" })
}

Gradle (Groovy)

Use the Gradle built-in JVM Test Suite Plugin to define the konsistTest source set. Add a testing block to the project configuration:

// build.gradle (root)

plugins {
    id 'jvm-test-suite'
}

testing {
    suites { 
        test { 
            useJUnitJupiter() 
        }

        konsistTest(JvmTestSuite) { 
            dependencies {
                // Add 'main' source set dependency
                implementation project() 
                
                // Add Konsist dependency
                implementation "com.lemonappdev:konsist:0.13.0"
            }

            targets { 
                all {
                    testTask.configure {
                        shouldRunAfter(test)
                    }
                }
            }
        }
    }
}

// Optional: Remove Konsist tests from the 'check' task if it exists
tasks.matching { it.name == "check" }.configureEach { task ->
    task.setDependsOn(task.getDependsOn().findAll { it.toString() != "konsistTest" })
}

Maven

Use the Maven Build Helper Plugin to define the konsistTest test source directory. Add plugin config to the project configuration:

# app/pom.xml

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>build-helper-maven-plugin</artifactId>
    <version>3.3.0</version>
    <executions>
        <execution>
            <id>add-konsist-test-source</id>
            <phase>generate-test-sources</phase>
            <goals>
                <goal>add-test-source</goal>
            </goals>
            <configuration>
                <sources>
                    <source>${project.basedir}/src/konsistTest/kotlin</source>
                </sources>
            </configuration>
        </execution>
    </executions>
</plugin>

Create app/src/konsistTest/kotlin folder and reload the project. The IDE will present a new konsistTest source set in the app module.

konsistTest sorce directory

The konsistTest test source folder works exactly like the build-in test source folder, so Kosist tests can be defined and executed in a similar way:

Gradle

./gradlew app:konsistTest

Maven

mvn test

Dedicated Module

This section demonstrates how to add the konsistTest module to the project. This configuration is primarily helpful for Android projects and Kotlin Multiplatform (KMP) projects, however, this approach will also work with Spring and pure Kotlin projects.

The Android Gradle Plugin is used to build Android apps. The Android Gradle Plugin is not compatible with the JVM Test Suite Plugin and it does not allow adding new source sets. To fully isolate tests a new module is required.

The Kotlin Multiplatform project contains modules with code for different platforms. To decouple Konsist tests from a single platform dedicated module containing Konsist test should be added.

Add konsistTest Module:

Gradle (Kotlin)

Create konsistTest/src/test/kotlin directory in the project root:

Add module include inside settings.gradle.kts file:

// settings.gradle.kts
include(":konsistTest")

Gradle (Groovy)

Create konsistTest/src/test/kotlin directory in the project root:

Add module include inside settings.gradle.kts file:

// settings.gradle
include ':konsistTest'

For Android projects add com.android.library plugin in the konsistTest/scr/test/kotlin/build.gradle file.

Refresh/Sync the Gradle Project in IDE.

Running Konsist Tests

To execute tests defined inkonsistTest module run ./gradlew konsistTest:test --rerun-tasks command.

When running Konsist tests in a multi-module Gradle project, always include the --rerun-tasks flag.

The Gradle flag --rerun-tasks is essential when Konsist tests are located in a separate module. Without this flag, Gradle assumes the tests are current if the module remains unchanged, leading to test skipping. This becomes problematic with Konsist, as it examines the entire codebase. Consequently, test results may be misleading since Gradle doesn't recognize that these tests are actually evaluating code across multiple modules.

To avoid manually passing --rerun-tasks flag each time a custom konsistCheck task can be added to the root build config file:

Gradle Kotlin

Add to root build.gradle.kts:

tasks.register("konsistCheck") {
    group = "verification"
    description = "Runs Konsist static code analysis"

    doLast {
        val output = ByteArrayOutputStream()
        val result = project.exec {
            commandLine("./gradlew", "konsistTest:test", "--rerun-tasks")
            standardOutput = output
            errorOutput = output
            isIgnoreExitValue = true
        }

        println(output.toString())

        if (result.exitValue != 0) {
            throw GradleException("Konsist tests failed")
        }
    }
}

Gradle Groovy

Add to root build.gradle:

tasks.register("konsistCheck") {
    group = "verification"
    description = "Runs Konsist static code analysis"

    doLast {
        def output = new ByteArrayOutputStream()
        def result = project . exec {
            commandLine './gradlew', 'konsistTest:test', '--rerun-tasks'
            standardOutput = output
            errorOutput = output
            ignoreExitValue = true
        }

        println output . toString ()

        if (result.exitValue != 0) {
            throw new GradleException ("Konsist tests failed")
        }
    }
}

After adding konsistCheck task run ./gradlew konsistCheck to execute all Konsist tests.

To execute all unit tests besides tests in the konsistTest module run:

./gradlew test -x konsistTest:test