Writing Tests With Kotlin Test

Writing Tests With kotlin.test — One Assertion API Across Every Target

kotlin.test is Kotlin's own thin test library: framework-agnostic assert* functions plus @Test/@BeforeTest/@AfterTest annotations that typealias onto whatever runner is on the classpath (JUnit4, JUnit5, TestNG, the JS/Native runners). Write import kotlin.test.* once and the same test source compiles in commonTest, on the JVM, and on every Kotlin Multiplatform target. This skill covers the API surface, the @OnlyInputTypes compile-time guard, the Asserter extension point, and the Gradle wiring. It is the assertion layer; the runner layer for Android instrumentation is ../../../jvm-tests/runner/configuring-junit4-on-android/SKILL.md.

When to use this skill

• The module is Kotlin Multiplatform and tests live in commonTest — JUnit's org.junit.* is not available there; kotlin.test is.
• The user wants one assertion vocabulary that reads the same on JVM, Android, JS, and Native.
• The user reaches for assertFailsWith<IllegalStateException> { … }, assertContentEquals(...), assertIs<Foo>(value), assertContains(list, x), expect(3) { compute() }, or @BeforeTest/@AfterTest.
• A JVM module has testImplementation(kotlin("test")) and the test "runs on JUnit but I never added JUnit" — explaining the capability-based resolution.
• kotlin.test.assertEquals failures render as a plain AssertionError with no diff, and the user wants the JUnit-style comparison failure back.

When NOT to use this skill

• The user wants rich fluent assertions (assertThat(x).isEqualTo(...), soft assertions, collection matchers) — that is AssertJ / Google Truth / Kotest assertions, deliberately out of kotlin.test's minimal scope.
• The user is writing an Android instrumentation test and asking about the runner (@RunWith(AndroidJUnit4::class), AndroidJUnitRunner, androidx.test:*) — use ../../../jvm-tests/runner/configuring-junit4-on-android/SKILL.md and ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md. (You can still use kotlin.test assertions inside those tests.)
• The user is testing coroutines / Flow — runTest, TestScope, Dispatchers.setMain is ../../../jvm-tests/coroutines/testing-coroutines-with-runtest/SKILL.md; Turbine is ../../../jvm-tests/coroutines/testing-flows-with-turbine/SKILL.md. (kotlin.test supplies the assert* calls inside those.)
• The user wants Compose UI assertions (assertIsDisplayed, assertTextEquals) — that is the compose/assertions/ skills, unrelated to kotlin.test.

Prerequisites

• Gradle: for a JVM/Android module, testImplementation(kotlin("test")). For a Kotlin Multiplatform module, kotlin.test is added to the commonTest source set: sourceSets { commonTest.dependencies { implementation(kotlin("test")) } }.
• The kotlin("test") shorthand is a capability-based dependency (Kotlin 1.4+). On the JVM it resolves to the JUnit4 variant (kotlin-test-junit) by default; if the Test task is configured with useJUnitPlatform(), it resolves to the JUnit5 variant (kotlin-test-junit5) instead. You can also depend on a specific adapter explicitly: org.jetbrains.kotlin:kotlin-test-junit, :kotlin-test-junit5, :kotlin-test-testng, :kotlin-test-js.
• A test runner on the classpath for the chosen target — kotlin.test's @Test is only an annotation; something has to execute it (JUnit, TestNG, the Kotlin/JS or Kotlin/Native test infra). The adapter artifact pulls it in.

Workflow

• 1. Add kotlin("test") to the test source set, not a hardcoded JUnit dependency. In a multiplatform module put it in commonTest; in a JVM/Android module use testImplementation(kotlin("test")). Do not also add junit:junit or org.junit.jupiter:* directly unless you have framework-specific needs — the adapter brings the right one.

• 2. Import the framework-agnostic symbols. import kotlin.test.* (or the specific ones). The annotations come from kotlin.test, not org.junit:

import kotlin.test.Test
import kotlin.test.BeforeTest
import kotlin.test.AfterTest
import kotlin.test.Ignore
import kotlin.test.assertEquals

class CartTest {
    private lateinit var cart: Cart

    @BeforeTest fun setUp() { cart = Cart() }      // == @Before (JUnit4) / @BeforeEach (JUnit5)
    @AfterTest  fun tearDown() { cart.clear() }    // == @After  (JUnit4) / @AfterEach  (JUnit5)

    @Test fun emptyCartTotalsZero() {
        assertEquals(Money.ZERO, cart.total())
    }

    @Ignore @Test fun flaky() { /* skipped — == @Disabled on JUnit5 */ }
}

On JVM-JUnit4, kotlin.test.Test is typealias'd to org.junit.Test, BeforeTest to org.junit.Before, AfterTest to org.junit.After, Ignore to org.junit.Ignore. On JUnit5 they map to org.junit.jupiter.api.Test/BeforeEach/AfterEach/Disabled. So the same source runs on either engine, and in commonTest.

• 3. Pick the precise assertion. kotlin.test is small on purpose — there is exactly one obvious call per intent:

• 4. Assert on a thrown exception with assertFailsWith, not a try/catch. It returns the exception so you can assert its message/cause:

@Test fun withdrawOverdraws() {
    val e = assertFailsWith<InsufficientFundsException> { account.withdraw(BigDecimal(100)) }
    assertEquals("balance is 20", e.message)
}

• 5. Lean on @OnlyInputTypes — type mismatches are compile errors, not runtime failures. assertEquals, assertContentEquals, assertContains, assertSame, expect are declared with <@OnlyInputTypes T>, so assertEquals(1, "1") does not compile. Don't widen to Any to "make it pass" — fix the test.

• 6. Restore JUnit-style diffs on the JVM by keeping the JUnit adapter on the classpath. kotlin.test resolves an Asserter at runtime via ServiceLoader<AsserterContributor>. The kotlin-test-junit artifact registers a contributor that, when org.junit.Assert is present, returns a JUnitAsserter delegating assertEquals to org.junit.Assert.assertEquals — which throws ComparisonFailure, giving the clickable expected/actual diff in IDEs. With no contributor, DefaultAsserter throws a plain AssertionError. So kotlin.test failures look like JUnit failures automatically as long as the adapter is there (it is, via kotlin("test")). Only implement a custom Asserter + register an AsserterContributor (JVM: META-INF/services/kotlin.test.AsserterContributor) if you need a non-JUnit reporting backend.