Kotlin Multiplatform’s three levels of testing with Kotest

Kotlin Multiplatform allows us to share common Kotlin code between various platforms, including JVM, JavaScript, iOS, Android, and native. This is useful when we have shared business logic relevant to all platforms. If functions in that common codebase require a platform-specific implementation, then Kotlin Multiplatform offers a mechanism of expected and actual declarations to essentially create placeholders that are implemented per platform. We examine this mechanism later in this article. A Kotlin Multiplatform project contains multiple modules called source sets to enable such code sharing. By default, each platform has two source sets, one for the code (jvmMain, jsMain) and one for the tests (jvmTest, jsTest) and additionally two source sets for common code (commonMain and commonTest) that are used in all main compilations of a project. These modules are structured in a hierarchy to provide any level of code sharing.

One use case is to share dependencies. Below we see an example where commonTest defines Kotest dependencies used for all platforms, and the JVM-specific dependencies are added to the jvmTest source set.

sourceSets {
    val `commonTest` by getting {
        dependencies {
            implementation(libs.kotest.assertions.core)
            implementation(libs.kotest.framework.engine)
            implementation(kotlin("test-common"))
            implementation(kotlin("test-annotations-common"))
        }
    }

    val jvmTest by getting {
        dependencies {
            implementation(libs.kotest.runner.junit5)
        }
    }
}

Each platform also has its own specific code so that, for instance, the JVM part of your application can implement a server, the front-end is built in JavaScript code, and the mobile apps are created based on the source sets for Android and iOS.

This article shows how we can test all three layers of code in a Kotlin Multiplatform project: common, expected / actual declaration, and platform-specific code. We use Kotest as our testing framework because it has built-in multiplatform support. The framework delegates testing to platform-specific engines, such as JUnit and Mocha. All code samples can be found on GitHub.

Common code

Code that is shared by all platforms by default resides in the commonMain source set. It wouldn’t make sense to write tests for it in every platform, so instead, we can use the commonTest source set to store the common test suite. Let’s say that we need a function that calculates the factorial of a number in source set commonMain:

package nl.bjornvanderlaan.factorial

fun factorial(number: Int): Int
    = (1..number).fold(1) { acc, i -> acc * i}

We can provide the test code in commonTest:

package nl.bjornvanderlaan.factorial

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.ints.shouldBeExactly

class FactorialTest : StringSpec({
    "Factorial of 5 is 120" {
        factorial(5) shouldBeExactly 120
    }
})

As we can see, testing common code works the same as in ‘normal’ Kotlin projects. The cool part however is that this function can now be used in all possible platforms, which can be a huge bonus if we write all the business logic here.

Expected / Actual declarations

Sometimes, there are functions that we want to use in our common code, but they can be implemented much more efficiently with platform-specific code. For instance, Kotlin’s multiplatform standard library does not provide a way to encode a string in base64. We could roll our own implementation or look for an open-source library, but some of our target platforms already provide this functionality out of the box. Kotlin provides a mechanism of expected and actual declarations to tackle this situation. With this mechanism, a common source set defines an expected declaration, and platform-specific source sets provide the actual declaration corresponding to the expected declaration and the actual implementation. Besides functions, this mechanism also works for other constructs such as classes, enums, and annotations. Below we see an example of this mechanism for the JVM. The code is based on a tutorial from JetBrains.

/**
 * Source set: commonMain
 */
package nl.bjornvanderlaan.base64

expect fun encodeBase64(input: String): String

fun encodeGreeting(name: String): String {
    return "Greetings $name, from Kotlin Multiplatform!"
}

/**
 * Source set: jvmMain
 */

package nl.bjornvanderlaan.base64

import java.util.Base64

actual fun encodeBase64(input: String): String {
    return Base64.getEncoder().encode(input.encodeToByteArray()).decodeToString()
}

As we can see, the expected function in commonMain can be used by other functions such as encodeGreeting. Through this mechanism, we can write common code where it makes sense and let leave placeholders where we expect the platforms to deliver an actual implementation. Similar to the common code, we can write our test in commonTest:

/**
 * Source set: commonTest
 */
class Base64Test: StringSpec({
    "String is properly encoded to Base64" {
        val input = "Kotlin is awesome"

        val encodedInput = encodeBase64(input)

        encodedInput shouldBe "S290bGluIGlzIGF3ZXNvbWU="
    }
})

When we let Gradle test our project, it automatically executes this test for all platform-specific variants of the expected function. So even though we have multiple actual implementations, we do not need to repeat our test suite.

Specific Function

Finally, there are parts of the application that we want to build for specific platforms only. Because source sets are organised hierarchically, we can choose which test source we want to put our tests in. When we make a web application, we want the server code to be written specifically for the JVM, and the JavaScript source set would contain the front-end code. The tests are then likely put in jvmTest and jsTest source sets, respectively. We can use Kotest to write tests like we would for single-platform Kotlin projects. The advantage of Kotest is that we have one unified testing framework, and we can also use all helper functions and custom assertions from parent source sets. Let’s say that we want to write a function for the JVM platform that calculates the factorial of a factorial of a number. Note that the value is already bigger than what Integer can handle if the number is 4. Luckily, as this function is specific to the JVM, we can use BigInteger for this purpose.

/**
 * Source set: jvmMain
 */
package nl.bjornvanderlaan.factorialoffactorial

import nl.bjornvanderlaan.factorial.factorial
import java.math.BigInteger

fun factorialOfFactorial(number: Int): BigInteger {
    val bigNumber = factorial(number).toBigInteger()

    var currentNumber = BigInteger.ONE
    var accumulator = BigInteger.ONE

    while(currentNumber <= bigNumber) {
        accumulator *= currentNumber
        currentNumber++
    }
    return accumulator
}


```kotlin

The function above also shows how the jvmMain source set can use the factorial function from its parent commonMain in the same way it can use its own functions. The function above can be tested with Kotest in the same way as we have seen in the other examples:

```kotlin


/**
 * Source set: jvmTest
 */
package nl.bjornvanderlaan.factorialoffactorial

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe
import java.math.BigInteger

class FactorialOfFactorialTest: StringSpec({
    "Factorial of factorial of 4 is 620448401733239439360000" {
        factorialOfFactorial(4) shouldBe BigInteger("620448401733239439360000")
    }
})

This function and its tests are defined in the JVM-specific part of our application and can, therefore, benefits from classes like BigInteger.

Intermediate levels

The examples above assume only two levels of hierarchy: the common parent and its platform-specific children. In practice, we might introduce more levels. For instance, if we also build a mobile application for iOS and Android, we might have an intermediate source sets mobileMain that depends on the commonMain source set and acts as the parent for iosTest and androidMain. In that case, the mobileTest source set can contain tests for functions implemented in mobileMain or expected functions implemented in child source sets.

Conclusion

Kotlin Multiplatform helps us reduce the time spent on writing and maintaining the same code for different platforms, and Kotest helps us to unify our testing efforts by providing a multiplatform framework. Multiplatform projects are structured as a hierarchy of source sets. The rules for testing are the same at every node: Kotest executes our tests on either the implementation in the main source set itself or fetches the actual implementations from child source sets. As such, Kotlin Multiplatform offers us the flexibility to create a super DRY codebase and test suite, regardless of the number of platforms we want to support.