kotlin.test: una fachada común sobre cuatro runners

Casi todo el mundo llega a kotlin.test esperando encontrar un framework de pruebas y se marcha decepcionado: no hay ejecución en paralelo, no hay parámetros, no hay ciclo de vida configurable, no hay extensiones. Esa pobreza es el diseño. kotlin.test es una capa de compatibilidad cuyo único cometido es ofrecer un vocabulario común —seis anotaciones y dos docenas de aserciones— que cada plataforma pueda traducir a su propia infraestructura sin coste en tiempo de ejecución. Entender que las anotaciones no son anotaciones sino alias de tipo declarados como actual cambia por completo la forma de leer los errores que aparecen cuando un test compila en la JVM y no en Native.

Una fachada de anotaciones, no un framework

El artefacto que declaras como kotlin("test") expone en el conjunto de fuentes común un puñado de declaraciones marcadas con expect: las anotaciones Test, BeforeTest, AfterTest, Ignore y las funciones de aserción. Ninguna de ellas contiene lógica. La anotación común se declara así, y la variante de la JVM la resuelve con un alias hacia la anotación del framework real.

// En el conjunto común de la biblioteca
public expect annotation class Test()

// En la variante para JUnit 4
public actual typealias Test = org.junit.Test

// En la variante para JUnit 5
public actual typealias Test = org.junit.jupiter.api.Test

La consecuencia es más profunda de lo que parece. Al ser un alias, la anotación que acaba en el bytecode es literalmente la del framework anfitrión: JUnit no ve una capa de adaptación, ve sus propias anotaciones, y por tanto todo el ecosistema de informes, integración con el IDE y filtrado por etiquetas funciona sin que nadie haya escrito un puente. No hay indirección, no hay reflexión adicional, no hay penalización.

Las aserciones siguen la misma filosofía de mínimo común denominador, pero con dos refinamientos que conviene conocer porque ahorran código. assertNotNull devuelve el valor no nulo, de modo que sirve simultáneamente de comprobación y de estrechamiento de tipo; assertIs está marcada como reified y también devuelve el valor ya convertido.

import kotlin.test.*

class PedidoTest {
    @Test
    fun aceptaUnPedidoValido() {
        val resultado = procesar(Pedido(unidades = 3))
        val exito = assertIs<Resultado.Exito>(resultado)  // devuelve el tipo estrecho
        assertEquals(3, exito.confirmadas)
    }

    @Test
    fun rechazaCantidadesNegativas() {
        assertFailsWith<IllegalArgumentException> { Pedido(unidades = -1) }
    }
}

Cómo se resuelve el runner en cada objetivo

En la JVM la biblioteca se publica en varias variantes —test-junit, test-junit5, test-testng— y desde hace varias versiones no necesitas nombrarlas: al declarar kotlin("test") a secas, el plugin de Gradle inspecciona el framework configurado en el task de pruebas y selecciona la variante correspondiente mediante atributos de resolución de dependencias. Eso significa que la línea que decide qué anotación acaba en tu bytecode no está en tu código de test sino en la configuración del build.

kotlin {
    sourceSets {
        commonTest.dependencies {
            implementation(kotlin("test"))
        }
    }
}

// Esta línea es la que elige JUnit 5 en lugar de JUnit 4
tasks.withType<Test>().configureEach { useJUnitPlatform() }

Fuera de la JVM el panorama es distinto y más interesante. En Kotlin/Native no hay reflexión ni carga dinámica de clases, así que descubrir tests en tiempo de ejecución es imposible: el compilador recorre el árbol de declaraciones durante la compilación, recoge todo lo anotado y genera un ejecutable con un main sintético que las invoca en un orden fijo. En JS y en Wasm la biblioteca se adapta al runner del host —Mocha, Jasmine o Karma según la configuración— traduciendo cada clase de test a bloques del estilo de describe e it.

flowchart TD
A[commonTest escrito una sola vez] --> B[Compilacion por objetivo]
B -->|JVM| C[Alias de tipo hacia JUnit o TestNG]
B -->|JS| D[Adaptador hacia Mocha o Jasmine]
B -->|Native| E[Runner generado en el binario sin reflexion]
B -->|Wasm| F[Runner sobre el host de JavaScript]
C --> G[Mismo fuente y mismas aserciones]
D --> G
E --> G
F --> G

La disciplina de escribir para cuatro backends

La regla operativa es sencilla de enunciar y difícil de sostener: todo lo que no sea kotlin.test, la biblioteca estándar y kotlinx-coroutines-test pertenece a un conjunto de fuentes específico de plataforma. Si necesitas una comprobación que solo tiene sentido en la JVM —comparar bytecode, verificar una anotación por reflexión, medir un tamaño de objeto— vive en jvmTest, no en commonTest con un expect improvisado.

El segundo hábito es tratar el estado global como veneno. Un object con un contador, un companion object con una caché o una variable de nivel superior mutable sobreviven entre tests dentro del mismo proceso, y como el orden de ejecución no está garantizado ni es el mismo en los cuatro runners, el fallo aparecerá en una plataforma y no en otra. La misma lógica se aplica a @BeforeTest: garantiza que se ejecuta antes de cada test, no que reconstruya lo que otro test rompió.

// commonTest: correcto en los cuatro objetivos
class TarifaTest {
    private lateinit var tarifa: Tarifa

    @BeforeTest
    fun preparar() {
        tarifa = Tarifa(base = 100, recargo = 20)   // estado nuevo por test
    }

    @Test
    fun aplicaElRecargo() = assertEquals(120, tarifa.para(Cliente.Estandar))

    @Test
    @Ignore   // se salta en los cuatro runners, con motivo documentado aparte
    fun tarifaNocturnaPendienteDeEspecificacion() = fail("sin especificar")
}