kotlin-test

Active contributors: Ilya Gorbunov, Sergej Jaskiewicz, Filipp Zhinkin

libraries/kotlin.test/ is the multiplatform Kotlin test framework. It provides assertEquals, assertTrue, fail, and a small assertion API that works on every Kotlin target. On the JVM it adapts to existing test runners (JUnit 4/5, TestNG); on JS/Native/Wasm it ships minimal in-tree runners.

Purpose

Give Kotlin code a single, target-uniform test API that integrates with each platform's idiomatic runner. A commonTest source set in a Multiplatform project can use kotlin-test and run on all targets without code duplication.

Directory layout

libraries/kotlin.test/
├── common/                kotlin-test (the assertion API + framework hooks)
├── annotations-common/    Common @Test, @Ignore, @BeforeTest, @AfterTest annotations
├── jvm/                   JVM glue
├── junit/                 kotlin-test-junit (JUnit 4 adapter)
├── junit5/                kotlin-test-junit5 (JUnit 5 adapter)
├── testng/                kotlin-test-testng adapter
├── js/                    kotlin-test-js (in-tree JS runner)
├── wasm/                  kotlin-test-wasm
└── native/                Native test runner glue (most lives in kotlin-native)

Key abstractions

Type	Where	Role
assertEquals, assertNotEquals, assertSame, assertTrue, assertFalse, fail, expect	libraries/kotlin.test/common/.../Assertions.kt	The assertion API.
@Test, @Ignore, @BeforeTest, @AfterTest	libraries/kotlin.test/annotations-common/...	Common annotations expanded by per-target adapters.
Asserter	libraries/kotlin.test/common/.../Asserter.kt	The interface every adapter implements.
JUnitAsserter (JUnit), TestNGAsserter, JsAsserter, WasmAsserter, NativeAsserter	per-adapter	Plug each platform's failure-reporting into the common API.

How adapters work

kotlin-test calls assertEquals(...) on the active Asserter. Each adapter installs its own Asserter so failures route into the host runner. On the JVM, the JUnit and TestNG adapters use the runner's exception types so failures are reported correctly. On JS/Wasm/Native, the in-tree runners convert assertion failures into Throwable subtypes that each platform's test reporter handles.

Per-target distribution

The user-facing artifacts:

• kotlin-test — the multiplatform umbrella module.
• kotlin-test-junit — JUnit 4 adapter.
• kotlin-test-junit5 — JUnit 5 adapter.
• kotlin-test-testng — TestNG adapter.
• kotlin-test-js — JS runner (Mocha-flavored).
• kotlin-test-wasm-js, kotlin-test-wasm-wasi — Wasm runners.
• Native: bundled with the Native runtime; KGP wires in the test executor.

A Multiplatform project usually depends on kotlin-test in its commonTest source set; KGP automatically resolves the right per-target adapter.

kotlin-test-native-xctest

native/kotlin-test-native-xctest/ ties Kotlin/Native tests into XCTest, the test runner shipped with Xcode. This is what powers KMM iOS tests run from Xcode.

Tests for kotlin-test itself

libraries/kotlin.test/test/ runs the framework against each adapter to ensure parity.

Integration points

• Consumed by: every Kotlin Multiplatform project, plus countless JVM-only projects that prefer the Kotlin assertion vocabulary.
• Adapters for: JUnit 4, JUnit 5, TestNG, JS Mocha, Wasm runners, Native, XCTest.
• Tested by: libraries/kotlin.test/test/, plus exercises in the compiler's coreLibsTest Gradle task.

Where to start

For a new common assertion: add it to libraries/kotlin.test/common/.../Assertions.kt with a corresponding Asserter method, then ensure each adapter implements the new method. For a new adapter: model it on kotlin-test-junit/.