1. Overview

Kotest is a multi-platform testing framework written in Kotlin. It consists of 3 main subprojects:

  • Test framework
  • Assertions library
  • Property testing

We can use each project independently from other testing frameworks. For example, it is possible to use the Kotest framework instead of Jupiter with assertj assertions.

We can execute Kotest tests in JVM, Javascript or Native. This enables us to use the same testing library for backend, mobile, and web development.

In this tutorial, we’ll focus on running the tests only on the JVM platform.

2. Testing on JVM

Kotest uses the JUnit Platform on the JVM. So, in a Maven project, we can activate it using the following declarations:


3. Testing Styles

Kotest provides many different testing styles. Let’s look at examples of some popular styles.

3.1. Behavior Spec

We can write BDD like tests in this style using given, when and then keywords:

class CardPaymentTests : BehaviorSpec({
    given("I have sufficient balance") {
        `when`("I make a card payment") {
            then("The card payment should be successful") {
                // test code

3.2. Should Spec

We can create tests using the should keyword:

class MoneyTests : ShouldSpec({
    should("Convert input money to the target currency") {
        // test code

We can group related tests in a context block:

class PaymentTests : ShouldSpec({
    context("CardPayments") {
        should("Make a card payment") {
            // test code
    context("BankTransfers") {
        should("Make an external bank transfer") {
            // test code

3.3. Feature Spec

Next, let’s see how can write end-to-end, cucumber like tests using feature and scenario keywords:

class HomePageTests : FeatureSpec({
    feature("signup") {
        scenario("should allow user to signup with email") {
            // test code
    feature("signin") {
        scenario("should allow user with valid credentials to login") {
            // test code

3.4. Describe Spec

Using describe, we can write tests in a style that’s very popular among Javascript and Ruby developers:

class PaymentTests : DescribeSpec({
    describe("CardPayments") {
        it("Should make a card payment") {
            // test code
    describe("BankTransfers") {
        it("Should make an external bank transfer") {
            // test code

4. Assertions

We have previously seen that Kotest has separate libraries meant for assertions. These libraries provide us with several matcher functions to write fluent assertions in our tests. There are two broad categories of assertion libraries:

  • Core matchers
  • External matchers

Let’s look at some examples of matchers in the kotest-assertions-core library:

// verify actual object is equal to expected object

// verify actual expression is true

// verify actual object is of given type

// verify actual map contains the given key

// verify actual map contains the given values

// verify actual string contains the given substring

// verify actual string is equal to the given string ignoring case

// verify actual file should have the given size

// verify actual date is after the given date

In addition to the core assertion module, there are several other modules that provide matchers for a wide variety of scenarios, e.g., JSON matchers, JDBC matches, and so on.

5. Testing Exceptions

On the other hand, testing exceptions with Kotest is very simple:

val exception = shouldThrow<ValidationException> {
   // test code
exception.message should startWith("Invalid input")

6. Lifecycle Hooks

We can use lifecycle hooks to set up or teardown test fixtures before or after tests. These hooks are very similar to setup and teardown methods in Junit. Let’s look at an example:

class TransactionStatementSpec : ShouldSpec({
    beforeTest {
      // add transactions
    afterTest { (test, result) ->
      // delete transactions

7. Data-Driven Tests

Data-driven tests in Kotest are similar to parameterized tests in Junit5. We can provide several inputs to a single test case to check different examples instead of writing several tests with just different input data. We can use the useData function from the kotest-framework-datatest-jvm library to supply data to tests.

Let’s see an example:

data class TaxTestData(val income: Long, val taxClass: TaxClass, val expectedTaxAmount: Long)

class IncomeTaxTests : FunSpec({
      TaxTestData(1000, ONE, 300),
      TaxTestData(1000, TWO, 350),
      TaxTestData(1000, THREE, 200)
    ) { (income, taxClass, expectedTaxAmount) ->
        calculateTax(income, taxClass) shouldBe expectedTaxAmount

8. Non-Deterministic Tests

Sometimes, we need to test functions that do not return results synchronously. Unfortunately, it is tricky to test such functions as we have to write custom boilerplate code to wait for results using techniques like callback functions or sleeping on the thread.

Kotest provides a few useful functions that we can use to write such non-deterministic tests in a declarative fashion.

Let’s look at an example of the eventually function:

class TransactionTests : ShouldSpec({
    val transactionRepo = TransactionRepo()

    should("Should make transaction complete") {
            duration = 5000
            interval = FixedInterval(1000)
        }) {
            transactionRepo.getStatus(120) shouldBe "COMPLETE"

Here, our test will check the transaction’s status every second for up to 5 seconds.

9. Mocking

We can integrate any mocking library such as mockk with Kotest. Kotest doesn’t provide its own mocking library:

class ExchangeServiceTest : FunSpec({
    val exchangeRateProvider = mockk<ExchangeRateProvider>()
    val service = ExchangeService(exchangeRateProvider)

    test("Exchanges money using rate from exchange rate service") {
        every { exchangeRateProvider.rate("USDEUR") } returns 0.9
        service.exchange(Money(1200, "USD"), "EUR") shouldBe 1080

10. Test Coverage

We can integrate Jacoco with Kotest to measure test coverage. To integrate we need to ensure that the test coverage reports are generated after unit tests are run:

tasks.test {

We can find the test coverage HTML report inside the $buildDir/reports/jacoco/test directory.

11. Grouping Tests with Tags

Sometimes, we want to run only certain tests in some specific environment. For example, we may want to avoid running some slow tests as part of our git pull request verification builds. To do that we need to first tag our tests:

class SlowTests : ShouldSpec({})

12. Conclusion

In this tutorial, we learned about several basic functionalities provided by the Kotest framework.

As usual, the code examples can be found over on GitHub.

Comments are closed on this article!