---
name: kotlin-testing
description: Write and improve Kotlin tests with Kotest, MockK, coroutine test tools, property tests, Kover, and the red-green-refactor TDD cycle. Use for new Kotlin code, missing tests, test bugs, slow or flaky tests, and coverage setup.
origin: ECC
---

# Kotlin Testing

> Original skill by ECC. Credit ECC in any copy or shared version of this skill.

Write small, clear, and stable Kotlin tests. Use Kotest for tests, MockK for test doubles, coroutine test tools for suspend code, and Kover for coverage.

## When to Use

Use this skill when you:

- Add a Kotlin function or class
- Add tests to old Kotlin code
- Fix a broken or flaky test
- Test suspend functions or flows
- Add property tests
- Set up Kover coverage
- Follow test-driven development, or TDD

## Main Steps

1. Read the code and its build files.
2. Find the public result that must be true.
3. Pick the smallest useful test type.
4. Write one test that fails for the right reason.
5. Run that test and check the failure.
6. Write the least code needed to pass.
7. Run the full test set.
8. Clean up the code while tests stay green.
9. Check coverage for missed cases.

Do not change build tool or test library unless the task needs it.

## Pick the Right Test

- Use `StringSpec` for short, direct cases.
- Use `FunSpec` when setup or hooks help.
- Use `BehaviorSpec` when Given, When, and Then make a rule easier to read.
- Use a property test when many inputs follow the same rule.
- Use an integration test when real file, data, or network parts must work together.

Test what code does. Do not test private methods on their own.

## TDD Cycle

```text
RED      Write one failing test.
GREEN    Write the least code that makes it pass.
REFACTOR Make the code clearer.
REPEAT   Add the next rule.
```

A RED test must fail because the feature is missing. A test that fails due to bad setup does not count.

## Basic Kotest Example

```kotlin
package com.example.math

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class CalculatorTest : StringSpec({
    "adds two numbers" {
        Calculator.add(2, 3) shouldBe 5
    }

    "adds negative numbers" {
        Calculator.add(-2, -3) shouldBe -5
    }
})
```

Use clear test names. Each name should state one rule.

## Matchers

Use the most exact matcher you can.

```kotlin
result shouldBe expected
result shouldNotBe wrongValue

name shouldStartWith "Al"
name shouldContain "lic"

items shouldHaveSize 3
items shouldContain "book"
items.shouldBeEmpty()

value.shouldBeNull()
value.shouldNotBeNull()
value.shouldBeInstanceOf<User>()

count shouldBeGreaterThan 0

shouldThrow<IllegalArgumentException> {
    validateAge(-1)
}.message shouldBe "Age must be positive"
```

Check error type and useful error data. Do not only check that some error happened.

For money and decimal values, use the exact type used by the app. For floating point values, use a small allowed gap.

## MockK

Mock only code outside the unit under test. Prefer real value objects and small fake classes when they are easy to build.

```kotlin
class UserServiceTest : FunSpec({
    val repository = mockk<UserRepository>()
    val service = UserService(repository)

    beforeTest {
        clearMocks(repository)
    }

    test("returns the saved user") {
        val user = User(id = "1", name = "Alice")
        every { repository.findById("1") } returns user

        service.findUser("1") shouldBe user

        verify(exactly = 1) {
            repository.findById("1")
        }
        confirmVerified(repository)
    }
})
```

Rules:

- Use `every` and `verify` for normal functions.
- Use `coEvery` and `coVerify` for suspend functions.
- Use `relaxed = true` only when unused calls do not matter.
- Clear shared mocks before each test.
- Stub every call that affects the result.
- Verify key effects, not every small call.
- Avoid mocking the class under test.
- Do not hide missing setup with broad `any()` rules unless the input does not matter.

## Coroutine Tests

Use `runTest` from `kotlinx-coroutines-test`. It gives safe test scope and virtual time.

```kotlin
import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe
import io.mockk.coEvery
import io.mockk.coVerify
import io.mockk.mockk
import kotlinx.coroutines.test.runTest

class AsyncUserServiceTest : FunSpec({
    val repository = mockk<UserRepository>()
    val service = UserService(repository)

    test("loads a user") {
        runTest {
            val user = User(id = "1", name = "Alice")
            coEvery { repository.findById("1") } returns user

            service.getUser("1") shouldBe user

            coVerify(exactly = 1) {
                repository.findById("1")
            }
        }
    }
})
```

Do not use real sleep calls. Use virtual time tools such as `advanceTimeBy`, `runCurrent`, or `advanceUntilIdle`.

Pass a test dispatcher or clock into app code when time or thread choice matters. Restore any changed main dispatcher after the test.

For flows:

- Collect only the values the test needs.
- End collection in the test.
- Test empty, error, and cancel cases.
- Do not leave jobs running after the test ends.

## Property Tests

Use property tests for rules that should hold for many values.

```kotlin
import io.kotest.core.spec.style.StringSpec
import io.kotest.property.Arb
import io.kotest.property.arbitrary.int
import io.kotest.property.checkAll
import io.kotest.matchers.shouldBe

class MathPropertyTest : StringSpec({
    "adding zero keeps the same value" {
        checkAll(Arb.int()) { value ->
            value + 0 shouldBe value
        }
    }
})
```

Keep property tests stable:

- Limit data to valid input when needed.
- Add direct tests for key edge cases.
- Include empty, zero, negative, min, and max values when valid.
- Save the random seed when a failure must be run again.
- Keep each property simple.
- Do not use random data when a short table of cases is clearer.

## Concrete Usage Example

Task: add an email check.

First, write tests:

```kotlin
class EmailValidatorTest : StringSpec({
    "accepts a valid email" {
        validateEmail("user@example.com")
            .getOrNull() shouldBe "user@example.com"
    }

    "rejects a blank email" {
        validateEmail("").isFailure shouldBe true
    }

    "rejects an email with no at sign" {
        validateEmail("user.example.com").isFailure shouldBe true
    }
})
```

Run the test:

```bash
./gradlew test --tests '*EmailValidatorTest'
```

Check that it fails because `validateEmail` is missing or not done. Then add the least code needed:

```kotlin
fun validateEmail(email: String): Result<String> {
    if (email.isBlank()) {
        return Result.failure(
            IllegalArgumentException("Email cannot be blank")
        )
    }

    if ('@' !in email) {
        return Result.failure(
            IllegalArgumentException("Email must contain @")
        )
    }

    return Result.success(email)
}
```

Run the test again. Then run all tests:

```bash
./gradlew test
```

Add more rules only when the app needs them. Do not claim full email rule support from a small check.

## Edge Cases

Check cases that fit the code:

- Empty and blank text
- Null values when the type allows null
- Zero and negative numbers
- Min and max values
- Empty and very large lists
- Duplicate items
- Unicode text
- Time zones and daylight saving time
- Missing files
- Bad data
- Timeouts
- Cancelled coroutines
- Failed work after part of a task is done
- Calls made more than once
- Shared state between tests

Use fixed clocks, test data, and random seeds. Tests must not depend on the current time, test order, local machine, or internet.

## Kover Coverage

Use the Kover tasks already set by the project. Common tasks are:

```bash
./gradlew koverHtmlReport
./gradlew koverVerify
```

Open the HTML report and check missed branches, not only the total score.

Aim for 80 percent or the project rule, whichever is set. Coverage is a guide. A high score does not prove good tests. Do not add weak tests only to raise the number. Do not test generated code unless the project asks for it.

## Final Check

Before finishing:

- Run the changed test by itself.
- Run the full test set.
- Check that no test depends on run order.
- Check that coroutine jobs end.
- Check that mocks do not leak between tests.
- Check key errors and edge cases.
- Run Kover if coverage is part of the task.
- Report any test you could not run and why.