kotest

Kotest — Kotlin Testing Framework

Kotest is a flexible and comprehensive testing framework for Kotlin with multiplatform support. It is split into three standalone sub-projects that can be used independently or together:

1. Test Framework — spec-based test definitions with 9 styles
2. Assertions Library — rich matchers and assertion utilities
3. Property Testing — generator-based property test support

Step 0: Analyze the Project

Before writing tests or migrating an existing test suite, understand the project:

1. Read build.gradle.kts (or .gradle) to identify the build system and existing test dependencies
2. Check if the project uses a Gradle version catalog (gradle/libs.versions.toml)
3. Determine the Kotlin version — Kotest 6.x requires Kotlin 2.2+
4. Determine the target platforms — JVM, JS, WasmJS, Native, Android, or Multiplatform
5. Check for existing test frameworks (JUnit 4/5, TestNG, Spek) that may need migration
6. Look for the Kotest IntelliJ plugin configuration (recommended for all JVM Kotest users)
7. Check for an existing ProjectConfig class (used for global test settings)

If Bash is available, run scripts/analyze-project.sh from this skill's directory to get a structured summary.

Classify the Task

Path A: Setup & First Tests

Step 1: Add Dependencies

See references/SETUP-REFERENCE.md for full platform-specific setup.

JVM (Gradle Kotlin DSL)

// build.gradle.kts
plugins {
  id("io.kotest") version "<kotest-version>"  // optional but recommended
}

dependencies {
  testImplementation("io.kotest:kotest-runner-junit5:<kotest-version>")
  testImplementation("io.kotest:kotest-assertions-core:<kotest-version>")
  testImplementation("io.kotest:kotest-property:<kotest-version>")  // optional
}

tasks.withType<Test>().configureEach {
  useJUnitPlatform()
}

Multiplatform

// build.gradle.kts
plugins {
  id("com.google.devtools.ksp") version "<ksp-version>"
  id("io.kotest") version "<kotest-version>"
}

kotlin {
  sourceSets {
    commonTest {
      dependencies {
        implementation("io.kotest:kotest-framework-engine:<kotest-version>")
        implementation("io.kotest:kotest-assertions-core:<kotest-version>")
      }
    }
  }
}

Step 2: Choose a Spec Style

Kotest offers 9 spec styles. All are functionally equivalent — pick one that fits the team:

See references/SPEC-STYLES.md for complete examples of each style.

Step 3: Write Your First Test

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe
import io.kotest.matchers.string.shouldHaveLength

class MyFirstTest : FunSpec({
  test("string length") {
    "hello".shouldHaveLength(5)
  }

  context("arithmetic") {
    test("addition") {
      1 + 1 shouldBe 2
    }
    test("subtraction") {
      10 - 3 shouldBe 7
    }
  }
})

Step 4: Run Tests

• Gradle: ./gradlew test
• IntelliJ: Click the gutter icon next to the test class or individual test
• Specific test: ./gradlew test --tests "com.example.MyFirstTest"

Path B: Migration from JUnit / TestNG / Spek

See references/MIGRATION-GUIDE.md for complete migration mappings.

JUnit 5 → Kotest Quick Mapping

Migration Steps

1. Keep JUnit on the classpath — Kotest JVM runner uses JUnit Platform under the hood
2. Migrate one test class at a time — JUnit and Kotest tests can coexist
3. Replace the class — change class MyTest to class MyTest : FunSpec({}) (or your chosen style)
4. Move @Test methods into test("name") { } blocks inside the init lambda
5. Replace assertions — assertEquals → shouldBe, assertTrue → shouldBeTrue(), etc.
6. Replace lifecycle — @BeforeEach → beforeEach { }, etc.
7. Replace parameterized tests — @ParameterizedTest → withTests(...) data-driven testing
8. Remove JUnit imports — all Kotest imports are under io.kotest.*

Path C: Assertions Only

Kotest assertions can be used with any test framework (JUnit, TestNG, etc.).

Setup (standalone)

testImplementation("io.kotest:kotest-assertions-core:<kotest-version>")

Core Assertions

import io.kotest.matchers.shouldBe
import io.kotest.matchers.shouldNotBe
import io.kotest.matchers.string.*
import io.kotest.matchers.collections.*
import io.kotest.matchers.maps.*

// Equality
result shouldBe expected
result shouldNotBe unexpected

// Strings
name.shouldStartWith("J")
name.shouldContain("oh")
name.shouldHaveLength(4)

// Collections
list.shouldContain("a")
list.shouldContainExactly("a", "b", "c")
list.shouldHaveSize(3)
list.shouldBeSorted()

// Maps
map.shouldContainKey("name")
map.shouldContainValue("John")
map.shouldContain("name", "John")

// Types
obj.shouldBeInstanceOf<String>()
obj.shouldBeNull()
nullable.shouldNotBeNull()

// Exceptions
shouldThrow<IllegalArgumentException> {
  riskyOperation()
}

Soft Assertions

Collect all assertion failures instead of stopping at the first:

assertSoftly {
  name shouldBe "John"
  age shouldBe 30
  email.shouldContain("@")
}
// Reports ALL failures, not just the first

Inspectors

Test elements in collections:

val people = listOf(Person("Alice", 30), Person("Bob", 25), Person("Charlie", 35))

people.forAll { it.age shouldBeGreaterThan (0) }
people.forNone { it.name.shouldBeEmpty() }
people.forAtLeast(2) { it.age shouldBeGreaterThan (25) }
people.forExactly(1) { it.name shouldBe "Bob" }

Custom Matchers

fun beValid() = Matcher<Email> { value ->
  MatcherResult(
    value.isValid(),
    { "expected $value to be a valid email" },
    { "expected $value to not be a valid email" }
  )
}

// Usage:
email should beValid()
email.shouldBeValid() // with extension function

See references/ASSERTIONS-REFERENCE.md for the complete matcher catalog.

Path D: Property Testing

Property testing generates hundreds/thousands of random inputs to harden test coverage.

Setup

testImplementation("io.kotest:kotest-property:<kotest-version>")

Basic Usage

import io.kotest.property.forAll
import io.kotest.property.checkAll
import io.kotest.property.Arb
import io.kotest.property.arbitrary.*

class PropertyTests : FunSpec({
  // forAll — return a Boolean
  test("string concatenation length") {
    forAll<String, String> { a, b ->
      (a + b).length == a.length + b.length
    }
  }

  // checkAll — use assertions
  test("absolute value is non-negative") {
    checkAll<Int> { n ->
      abs(n) shouldBeGreaterThanOrEqualTo 0
    }
  }

  // With specific generators
  test("adults can vote") {
    forAll(Arb.int(18..120)) { age ->
      canVote(age)
    }
  }
})

Built-in Generators (Arbs)

Custom Generators

val personArb = Arb.bind(
  Arb.string(5..20),
  Arb.int(1..120),
  Arb.email()
) { name, age, email ->
  Person(name, age, email)
}

checkAll(personArb) { person ->
  person.age shouldBeGreaterThan 0
}

See references/PROPERTY-TESTING-REFERENCE.md for the full generator catalog and advanced patterns.

Path E: Advanced Configuration

Project Config

Create a global configuration class:

// src/test/kotlin/io/kotest/provided/ProjectConfig.kt
package io.kotest.provided

import io.kotest.core.config.AbstractProjectConfig

object ProjectConfig : AbstractProjectConfig() {
  // Global assertion mode — fail if no assertions in a test
  override val assertionMode = AssertionMode.Error

  // Global soft assertions — all tests use assertSoftly
  override val globalAssertSoftly = true

  // Default timeout for all tests
  override val timeout = 10.seconds

  // Parallelism
  override val specConcurrencyMode = SpecConcurrencyMode.Concurrent
  override val testConcurrencyMode = TestConcurrencyMode.Sequential

  // Global extensions
  override val extensions = listOf(
    MyDatabaseExtension(),
  )
}

Lifecycle Hooks

class DatabaseTest : FunSpec({
  // Per-test hooks
  beforeEach { println("Before each test") }
  afterEach { println("After each test") }

  // Per-spec hooks
  beforeSpec { println("Before all tests in this spec") }
  afterSpec { println("After all tests in this spec") }

  // Per-container / per-leaf hooks
  beforeContainer { println("Before each container test") }
  afterContainer { println("After each container test") }

  test("my test") { /* ... */ }
})

Tags & Filtering

object Slow : Tag()
object Database : Tag()

class MyTest : FunSpec({
  test("slow integration test").config(tags = setOf(Slow, Database)) {
    // ...
  }
})

// Run only specific tags:
// ./gradlew test -Dkotest.tags="Slow & Database"
// ./gradlew test -Dkotest.tags="!Slow"  (exclude)

Isolation Modes

class StateTest : FunSpec({
  isolationMode = IsolationMode.InstancePerRoot  // fresh instance per root test

  val counter = AtomicInteger(0)

  test("first") { counter.incrementAndGet() shouldBe 1 }
  test("second") { counter.incrementAndGet() shouldBe 1 }  // passes! fresh instance
})

Coroutine Testing

All Kotest tests run inside coroutines by default:

class CoroutineTest : FunSpec({
  test("async operations") {
    val deferred = async { fetchData() }
    deferred.await() shouldBe expectedData
  }

  test("with timeout").config(timeout = 5.seconds) {
    // will fail if takes longer than 5 seconds
    longRunningOperation()
  }
})

Non-Deterministic Testing

// Eventually — retry until passes or timeout
eventually(5.seconds) {
  eventStore.getById(id).status shouldBe "COMPLETED"
}

// Continually — assert remains true for duration
continually(2.seconds) {
  server.isHealthy().shouldBeTrue()
}

// Retry — with custom config
retry(3, 1.seconds) {
  api.call() shouldBe success
}

Data-Driven Testing

class ConversionTest : FunSpec({
  context("celsius to fahrenheit") {
    withTests(
      Pair(0, 32),
      Pair(100, 212),
      Pair(-40, -40),
    ) { (celsius, fahrenheit) ->
      cToF(celsius) shouldBe fahrenheit
    }
  }
})

For data classes with more fields, use data class rows:

data class PythagTriple(val a: Int, val b: Int, val c: Int)

class PythagorasTest : FunSpec({
  withTests(
    PythagTriple(3, 4, 5),
    PythagTriple(5, 12, 13),
    PythagTriple(8, 15, 17),
  ) { (a, b, c) ->
    a * a + b * b shouldBe c * c
  }
})

Extensions

Create reusable test plugins:

class DatabaseExtension : BeforeSpecListener, AfterSpecListener {
  override suspend fun beforeSpec(spec: Spec) {
    Database.start()
    Database.migrate()
  }
  override suspend fun afterSpec(spec: Spec) {
    Database.stop()
  }
}

// Register in a spec
class MySpec : FunSpec({
  extension(DatabaseExtension())
  // tests ...
})

// Or register globally in ProjectConfig
object ProjectConfig : AbstractProjectConfig() {
  override val extensions = listOf(DatabaseExtension())
}

AutoClose

Automatically close resources after a spec:

class ResourceTest : FunSpec({
  val connection = autoClose(Database.connect())

  test("query") {
    connection.query("SELECT 1").shouldNotBeNull()
  }
  // connection is automatically closed after all tests
})

Path F: KMP Testing

See references/SETUP-REFERENCE.md for platform-specific setup.

Key Points

• JVM: Uses kotest-runner-junit5 + JUnit Platform
• JS / WasmJS / Native: Uses kotest-framework-engine + KSP + Kotest Gradle plugin
• Android: Uses kotest-runner-junit4 for instrumented tests, kotest-runner-junit5 for unit tests
• commonTest: Tests in commonTest run on all targets
• Non-JVM engines are feature-limited (no annotation-based config, no classpath scanning)

Common Gotchas

• Tests must be in a class extending a Spec style — top-level functions are not discovered
• On JS/Native: @AutoScan does not work; register extensions explicitly
• On Native: Data-driven tests require at least one non-data test in the spec
• Android instrumented tests use JUnit4 runner: kotest-runner-junit4

Path G: Kotest Debugging

See references/KOTEST-DEBUGGING.md for the full guide.

Quick Checklist

1. Enable debug logging — set KOTEST_DEBUG=true to get verbose engine output
2. Collect versions — Kotest, Kotlin, Gradle, JVM, and target platform
3. Capture full output — KOTEST_DEBUG=true ./gradlew test 2>&1 | tee kotest-debug.log
4. Check test reports — build/reports/tests/test/index.html
5. Isolate the failure — ./gradlew test --tests "com.example.MyFailingTest"
6. Verify ProjectConfig — grep debug output for projectconfig if config changes have no effect
7. Reproduce minimally — stripped-down spec with no external dependencies

Verification

After setup or migration, verify with the checklist. Key checks:

1. ./gradlew test succeeds with no errors
2. Tests are discovered and executed (check test report)
3. IntelliJ shows gutter icons for running individual tests
4. Assertions produce clear failure messages with diffs
5. No stale JUnit imports remain (if migrated)

Common Issues

See references/KNOWN-ISSUES.md for details. Key gotchas:

Framework Issues

• Tests not discovered — ensure useJUnitPlatform() is in build config (JVM), or KSP + Kotest plugin applied (KMP)
• ProjectConfig not picked up — must be at io.kotest.provided.ProjectConfig or set via system property kotest.framework.config.fqn
• @AutoScan not working — removed in Kotest 6.0; register extensions explicitly
• Coroutine timeout — use .config(timeout = ...) on tests, or blockingTest = true for blocking code
• InstancePerTest deprecated — use InstancePerRoot instead

Assertion Issues

• assertSoftly not catching errors — only works with Kotest's own assertions; wrap others in shouldNotThrowAny { }
• Matcher not found — check the correct import; matchers are in type-specific packages like io.kotest.matchers.string.*

Property Testing Issues

• Test too slow — reduce iterations: checkAll(100) { ... }
• Flaky seed — fix the seed: checkAll(PropTestConfig(seed = 12345)) { ... }
• Custom type — use Arb.bind() to compose generators for data classes

Reference Files

• Setup Reference — platform-specific dependency and configuration setup
• Spec Styles — complete examples of all 9 spec styles
• Assertions Reference — full matcher catalog with examples
• Property Testing Reference — generators, config, shrinking
• Migration Guide — JUnit 4/5, TestNG, Spek migration mappings
• Known Issues — common problems and workarounds
• Kotest Debugging — how to gather diagnostic info and reproduce issues