Kotlin Test JUnit

Kotlin Test JUnit is a JUnit adapter library that bridges Kotlin's platform-agnostic kotlin.test library with JUnit 4. It provides seamless integration between Kotlin's multiplatform testing framework and JUnit, enabling developers to write platform-independent test code that runs on the JVM using JUnit's mature testing infrastructure.

Package Information

• Package Name: kotlin-test-junit
• Package Type: maven
• Language: Kotlin
• Installation:

  dependencies {
      testImplementation("org.jetbrains.kotlin:kotlin-test-junit:2.2.0")
  }

Core Imports

The library provides automatic integration through Kotlin's service loader mechanism, but you can also access components directly:

// For using kotlin.test assertions (automatically uses JUnit when available)
import kotlin.test.*

// For direct access to JUnit integration classes (usually not needed)
import kotlin.test.junit.JUnitAsserter
import kotlin.test.junit.JUnitContributor

Basic Usage

The library works transparently with kotlin.test assertions when JUnit is in the classpath:

import kotlin.test.*
import org.junit.Test

class MyTest {
    @Test
    fun testExample() {
        // These kotlin.test assertions automatically delegate to JUnit
        assertEquals("expected", "expected")
        assertTrue(true)
        assertNotNull("not null")
    }
    
    @BeforeTest
    fun setup() {
        // Setup code - maps to JUnit @Before
    }
    
    @AfterTest  
    fun teardown() {
        // Teardown code - maps to JUnit @After
    }
}

Architecture

The library uses a contributor pattern to automatically register the JUnit asserter when JUnit is available in the classpath. The JUnitContributor class implements AsserterContributor and provides the JUnitAsserter implementation when JUnit is detected.

Capabilities

Test Annotations

Maps kotlin.test annotations to their JUnit equivalents for seamless multiplatform testing.

public actual typealias Test = org.junit.Test
public actual typealias Ignore = org.junit.Ignore
public actual typealias BeforeTest = org.junit.Before
public actual typealias AfterTest = org.junit.After

JUnit Integration

Provides automatic JUnit asserter registration and detection.

public class JUnitContributor : AsserterContributor {
    override fun contribute(): Asserter?
}

The JUnitContributor automatically detects if JUnit is available in the classpath and provides the JUnitAsserter implementation if found. It uses Class.forName("org.junit.Assert") to check for JUnit availability.

Assertion Implementation

Implements kotlin.test assertions by delegating to JUnit's Assert class.

public object JUnitAsserter : Asserter {
    override fun assertEquals(message: String?, expected: Any?, actual: Any?)
    override fun assertNotEquals(message: String?, illegal: Any?, actual: Any?)
    override fun assertSame(message: String?, expected: Any?, actual: Any?)
    override fun assertNotSame(message: String?, illegal: Any?, actual: Any?)
    override fun assertNotNull(message: String?, actual: Any?)
    override fun assertNull(message: String?, actual: Any?)
    override fun fail(message: String?): Nothing
    @SinceKotlin("1.4")
    override fun fail(message: String?, cause: Throwable?): Nothing
    
    // Note: assertTrue methods are inherited from Asserter interface with default implementations
    // that delegate to fail() - no override needed since JUnit does not provide assertTrue directly
}

assertEquals: Asserts that two objects are equal, delegating to org.junit.Assert.assertEquals

• message - Optional assertion failure message
• expected - Expected value
• actual - Actual value to compare

assertNotEquals: Asserts that two objects are not equal, delegating to org.junit.Assert.assertNotEquals

• message - Optional assertion failure message
• illegal - Value that should not match
• actual - Actual value to compare

assertSame: Asserts that two objects refer to the same object, delegating to org.junit.Assert.assertSame

• message - Optional assertion failure message
• expected - Expected object reference
• actual - Actual object reference to compare

assertNotSame: Asserts that two objects do not refer to the same object, delegating to org.junit.Assert.assertNotSame

• message - Optional assertion failure message
• illegal - Object reference that should not match
• actual - Actual object reference to compare

assertNotNull: Asserts that an object is not null, delegating to org.junit.Assert.assertNotNull

• message - Optional assertion failure message (if null, defaults to "actual value is null")
• actual - Object to check for non-null
• Note: When message is null, the implementation provides the default message "actual value is null"

assertNull: Asserts that an object is null, delegating to org.junit.Assert.assertNull

• message - Optional assertion failure message (if null, defaults to "actual value is not null")
• actual - Object to check for null
• Note: When message is null, the implementation provides the default message "actual value is not null"

fail: Fails a test with an optional message, delegating to org.junit.Assert.fail

• message - Optional failure message
• Returns: Nothing (always throws AssertionError)
• Implementation: Calls Assert.fail(message) and includes fallback throw if needed

fail: Fails a test with an optional message and cause, delegating to org.junit.Assert.fail (available since Kotlin 1.4)

• message - Optional failure message
• cause - Optional exception cause
• Returns: Nothing (always throws AssertionError with cause)
• Implementation: Calls Assert.fail(message), catches AssertionError, calls initCause(cause), then rethrows

Types

/**
 * Checks applicability and provides Asserter instance
 */
interface AsserterContributor {
    /**
     * Provides [Asserter] instance or `null` depends on the current context.
     * @return asserter instance or null if it is not applicable now
     */
    fun contribute(): Asserter?
}

/**
 * Platform-specific assertion implementation interface from kotlin.test
 */
interface Asserter {
    /** Fails the current test with the specified message */
    fun fail(message: String?): Nothing
    
    /** Fails the current test with the specified message and cause exception (since Kotlin 1.4) */
    fun fail(message: String?, cause: Throwable?): Nothing
    
    /** Asserts that the specified value is `true` (has default implementation that calls fail) */
    fun assertTrue(lazyMessage: () -> String?, actual: Boolean): Unit
    
    /** Asserts that the specified value is `true` (has default implementation) */
    fun assertTrue(message: String?, actual: Boolean): Unit
    
    /** Asserts that the specified values are equal (has default implementation using assertTrue) */
    fun assertEquals(message: String?, expected: Any?, actual: Any?): Unit
    
    /** Asserts that the specified values are not equal (has default implementation using assertTrue) */
    fun assertNotEquals(message: String?, illegal: Any?, actual: Any?): Unit
    
    /** Asserts that the specified values are the same instance (has default implementation using assertTrue) */
    fun assertSame(message: String?, expected: Any?, actual: Any?): Unit
    
    /** Asserts that the specified values are not the same instance (has default implementation using assertTrue) */
    fun assertNotSame(message: String?, illegal: Any?, actual: Any?): Unit
    
    /** Asserts that the specified value is `null` (has default implementation using assertTrue) */
    fun assertNull(message: String?, actual: Any?): Unit
    
    /** Asserts that the specified value is not `null` (has default implementation using assertTrue) */
    fun assertNotNull(message: String?, actual: Any?): Unit
}

Note: These interfaces are defined in the kotlin.test module, which this library depends on and extends.

Integration Details

The library integrates with kotlin.test through the Java Service Provider Interface (SPI). The JUnitContributor is automatically discovered and registered via the META-INF/services/kotlin.test.AsserterContributor file, enabling automatic JUnit support when both kotlin-test-junit and JUnit are present in the classpath.

When JUnit is detected, all kotlin.test assertion functions (assertEquals, assertTrue, etc.) automatically delegate to the corresponding JUnit assertions, providing seamless integration between Kotlin's multiplatform test APIs and JUnit's JVM-specific testing infrastructure.

Module Structure

The library provides two main packages through its module exports:

• kotlin.test.junit - Contains the main integration classes (JUnitContributor, JUnitAsserter)
• kotlin.test.junit.annotations - Contains the annotation type aliases (physically defined in kotlin.test package but exported to this package via @JvmPackageName("kotlin.test.junit.annotations"))

The module declares transitive dependencies on kotlin.stdlib, kotlin.test, and junit, and provides the AsserterContributor service implementation.