or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

boolean-assertions.mdcollection-assertions.mdequality-assertions.mdexception-testing.mdframework-integration.mdindex.mdtest-annotations.mdtest-utilities.mdtype-null-assertions.md
tile.json

tessl/maven-org-jetbrains-kotlin--kotlin-test-common

Common test assertions and utilities for Kotlin multiplatform projects

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.jetbrains.kotlin/kotlin-test-common@2.2.x

To install, run

npx @tessl/cli install tessl/maven-org-jetbrains-kotlin--kotlin-test-common@2.2.0

index.mddocs/

Kotlin Test Common

Kotlin Test Common provides a comprehensive set of platform-agnostic test assertions and utilities for Kotlin multiplatform projects. This module enables developers to write tests that work consistently across JVM, JavaScript, Native, and other Kotlin compilation targets with a unified API for assertions, test annotations, and testing framework integration.

Package Information

  • Package Name: org.jetbrains.kotlin:kotlin-test-common
  • Package Type: maven
  • Language: Kotlin
  • Installation: Add to your build.gradle.kts: 
    dependencies {
    testImplementation("org.jetbrains.kotlin:kotlin-test-common:2.2.0")
}

Core Imports

import kotlin.test.*

For specific functions:

import kotlin.test.assertEquals
import kotlin.test.assertTrue
import kotlin.test.assertNotNull
import kotlin.test.assertFails

Basic Usage

import kotlin.test.*

class MyTest {
    @Test
    fun testBasicAssertions() {
        // Boolean assertions
        assertTrue(5 > 3)
        assertFalse(2 > 5)
        
        // Equality assertions
        assertEquals(10, 5 + 5)
        assertNotEquals(10, 3 + 3)
        
        // Null assertions
        val result: String? = computeSomething()
        assertNotNull(result)
        assertEquals("expected", result)
    }
    
    @Test
    fun testExceptionHandling() {
        // Assert that a block throws an exception
        assertFails {
            throw IllegalArgumentException("Invalid input")
        }
        
        // Assert specific exception type
        assertFailsWith<IllegalArgumentException> {
            validateInput(null)
        }
    }
    
    @Test
    fun testCollections() {
        val numbers = listOf(1, 2, 3, 4, 5)
        
        // Collection content equality
        assertContentEquals(numbers, listOf(1, 2, 3, 4, 5))
        
        // Collection contains
        assertContains(numbers, 3)
        assertContains(1..10, 5)
    }
}

Architecture

Kotlin Test Common is built around several key components:

  • Assertion Functions: Comprehensive set of type-safe assertion functions covering equality, null checks, type checks, and collection operations
  • Asserter Interface: Pluggable assertion backend that allows integration with different testing frameworks (JUnit, TestNG, etc.)
  • Test Annotations: Platform-agnostic test annotations (@Test, @BeforeTest, @AfterTest, @Ignore) that map to appropriate platform-specific frameworks
  • Multiplatform Support: Expect/actual declarations enable consistent behavior across all Kotlin compilation targets
  • Error Reporting: Structured error messages with optional custom messages for failed assertions

Capabilities

Boolean Assertions

Core boolean assertion functions for testing true/false conditions with optional custom messages.

fun assertTrue(actual: Boolean, message: String? = null)
fun assertTrue(message: String? = null, block: () -> Boolean)
fun assertFalse(actual: Boolean, message: String? = null)
fun assertFalse(message: String? = null, block: () -> Boolean)

Boolean Assertions

Equality Assertions

Equality and inequality assertions with support for tolerance-based floating point comparisons and instance reference checks.

fun <T> assertEquals(expected: T, actual: T, message: String? = null)
fun assertEquals(expected: Double, actual: Double, absoluteTolerance: Double, message: String? = null)
fun assertEquals(expected: Float, actual: Float, absoluteTolerance: Float, message: String? = null)
fun <T> assertNotEquals(illegal: T, actual: T, message: String? = null)
fun <T> assertSame(expected: T, actual: T, message: String? = null)
fun <T> assertNotSame(illegal: T, actual: T, message: String? = null)

Equality Assertions

Type and Null Assertions

Type checking and null safety assertions with smart cast support and contract-based APIs.

inline fun <reified T> assertIs(value: Any?, message: String? = null): T
inline fun <reified T> assertIsNot(value: Any?, message: String? = null)
fun <T : Any> assertNotNull(actual: T?, message: String? = null): T
fun <T : Any, R> assertNotNull(actual: T?, message: String? = null, block: (T) -> R): R
fun assertNull(actual: Any?, message: String? = null)

Type and Null Assertions

Collection and Array Assertions

Content equality and membership testing for collections, arrays, ranges, maps, and strings with support for all Kotlin types.

fun <T> assertContains(iterable: Iterable<T>, element: T, message: String? = null)
fun <T> assertContains(array: Array<T>, element: T, message: String? = null)
fun <T> assertContentEquals(expected: Iterable<T>?, actual: Iterable<T>?, message: String? = null)
fun <T> assertContentEquals(expected: Array<T>?, actual: Array<T>?, message: String? = null)
fun assertContains(range: IntRange, value: Int, message: String? = null)
fun <K, V> assertContains(map: Map<K, V>, key: K, message: String? = null)

Collection and Array Assertions

Exception Testing

Exception assertion functions for testing error conditions with support for specific exception types and cause chains.

fun assertFails(block: () -> Unit): Throwable
fun assertFails(message: String?, block: () -> Unit): Throwable
inline fun <reified T : Throwable> assertFailsWith(message: String? = null, block: () -> Unit): T
fun <T : Throwable> assertFailsWith(exceptionClass: KClass<T>, block: () -> Unit): T

Exception Testing

Test Utilities

Core utility functions for test execution and expectation validation.

fun <T> expect(expected: T, block: () -> T)
fun <T> expect(expected: T, message: String?, block: () -> T)
fun fail(message: String? = null): Nothing
fun fail(message: String? = null, cause: Throwable? = null): Nothing
fun todo(block: () -> Unit)

Test Utilities

Test Framework Integration

Core interfaces and utilities for integrating with different testing frameworks across platforms.

interface Asserter {
    fun fail(message: String?): Nothing
    fun fail(message: String?, cause: Throwable?): Nothing
    fun assertTrue(message: String?, actual: Boolean)
    fun assertEquals(message: String?, expected: Any?, actual: Any?)
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
    fun assertSame(message: String?, expected: Any?, actual: Any?)
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
    fun assertNull(message: String?, actual: Any?)
    fun assertNotNull(message: String?, actual: Any?)
}

var asserter: Asserter

Framework Integration

Test Annotations

Platform-agnostic test annotations that map to appropriate testing frameworks on each Kotlin compilation target.

@Target(AnnotationTarget.FUNCTION)
annotation class Test

@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
annotation class Ignore

@Target(AnnotationTarget.FUNCTION)
annotation class BeforeTest

@Target(AnnotationTarget.FUNCTION)
annotation class AfterTest

Test Annotations