Ir al contenido principal
Versión: 6.2 🚧

Configuración a nivel de proyecto

Traducción Beta No Oficial

Esta página fue traducida por PageTurner AI (beta). No está respaldada oficialmente por el proyecto. ¿Encontraste un error? Reportar problema →

advertencia

Este documento describe la configuración a nivel de proyecto en Kotest 6.0. Si estabas usando configuración a nivel de proyecto en Kotest 5.x, ten en cuenta que el comportamiento ha cambiado. Lee estos documentos atentamente para asegurar que las clases de configuración sean detectadas por el framework.

Kotest es flexible y ofrece múltiples formas de configurar pruebas, como definir el orden de los tests dentro de un spec o cómo se crean las clases de prueba. A veces querrás establecer esto a nivel global, y para eso necesitas usar configuración de proyecto.

La configuración de proyecto se puede usar creando una clase que extienda de AbstractProjectConfig. En plataformas JVM y JS, también se admite usar un object si prefieres usarlo en lugar de una clase.

Cualquier configuración establecida a nivel de spec o directamente en un test sobrescribirá la configuración especificada a nivel de proyecto. Algunas opciones de configuración solo están disponibles a nivel de proyecto porque cambian cómo el motor de pruebas ejecuta todo el conjunto de pruebas (por ejemplo, el número máximo de specs concurrentes a ejecutar no tendría sentido especificarlo a nivel de spec).

Algunas opciones de configuración disponibles en AbstractProjectConfig incluyen modos de aserción, timeouts, fallar specs con pruebas ignoradas, AssertSoftly global, y listeners o extensiones reutilizables, entre otros.

Configuración​

El comportamiento difiere dependiendo de si usas Kotest en JVM o en plataformas no JVM como Kotlin Native o JS. Siempre la clase debe extender AbstractProjectConfig.

Para JVM​

En JVM, Kotest inspeccionará tres ubicaciones buscando una clase de configuración. Estas son:

  • Una clase con el nombre completo io.kotest.provided.ProjectConfig

  • Una clase con un nombre completo especificado por la propiedad del sistema kotest.framework.config.fqn

  • Una clase llamada ProjectConfig que exista en cualquier paquete común de todas las pruebas.

Primero, Kotest inspeccionará el classpath buscando una clase en io.kotest.provided.ProjectConfig. Si esa clase existe, se instanciará y usará.

Segundo, si la propiedad del sistema kotest.framework.config.fqn está definida, su valor se usará para localizar una clase con ese nombre completo. Si existe, se instanciará y usará. Ten en cuenta que en Gradle, debes propagar la propiedad del sistema al proceso JVM estableciendo la propiedad systemProperty en la tarea test de Gradle. Por ejemplo:

tests.task {
  useJunitPlatform()
  systemProperty("kotest.framework.config.fqn", "com.sksamuel.mypackage.MyConfigClass")
}

Finalmente, puedes colocar tu clase de configuración en cualquier paquete común a todas las pruebas. Por ejemplo, si tienes pruebas ubicadas en com.sksamuel.myproject.services, com.sksamuel.myproject.common, y com.sksamuel.myproject.data, puedes colocar tu clase de configuración en cualquiera de com.sksamuel.myproject, com.sksamuel, o com.

nota

La búsqueda por paquete común solo está disponible en Kotest 6.2+

Para no JVM​

En plataformas Kotlin Native y JS, la clase de configuración puede ubicarse en cualquier lugar pero debe seguir extendiendo AbstractProjectConfig.

precaución

Solo debes crear una única clase de configuración de proyecto, de lo contrario el comportamiento será indefinido. Si deseas tener diferentes configuraciones por paquete, consulta configuración a nivel de paquete.

Ejemplos​

Modo de aserción​

Puedes configurar Kotest para que falle el build o muestre una advertencia en stderr si se ejecuta una prueba que no usa aserciones de Kotest.

Para hacer esto, establece assertionMode en AssertionMode.Error o AssertionMode.Warn dentro de tu configuración. Por ejemplo. Una forma alternativa de activar esto es mediante la propiedad del sistema kotest.framework.assertion.mode, que siempre (si está definida) tendrá prioridad sobre el valor establecido aquí.

object KotestProjectConfig : AbstractProjectConfig() {
  override val assertionMode = AssertionMode.Error
}
precaución

El modo de aserción solo funciona con aserciones de Kotest y no con otras bibliotecas de aserciones. Esto se debe a que las aserciones necesitan ser conscientes del marco de detección de aserciones que proporciona Kotest.

Assert Softly global​

Assert Softly es muy útil para agrupar errores en un único fallo. Si queremos activar esto automáticamente para todas las pruebas, podemos hacerlo en la configuración. Una forma alternativa de activarlo es estableciendo la propiedad del sistema kotest.framework.assertion.globalassertsoftly a true, que siempre (si está definida) tendrá prioridad sobre el valor aquí establecido.

object KotestProjectConfig : AbstractProjectConfig() {
  override val globalAssertSoftly = true
}

Tiempos de espera​

Puedes establecer un timeout predeterminado para todas las pruebas de tu proyecto configurando la propiedad timeout en tu configuración de proyecto.

object KotestProjectConfig : AbstractProjectConfig() {
  override val timeout = 5.seconds
}

Manejo de nombres de prueba duplicados​

De forma predeterminada, Kotest renombrará una prueba si tiene el mismo nombre que otra prueba en el mismo ámbito. Añadirá _1, _2, etc. al nombre de la prueba. Esto es útil para pruebas generadas automáticamente.

Puedes cambiar este comportamiento globalmente estableciendo duplicateTestNameMode en DuplicateTestNameMode.Error o DuplicateTestNameMode.Warn.

Error hará que falle el conjunto de pruebas con un nombre repetido, mientras que warn lo renombrará pero mostrará una advertencia.

Fallar en pruebas ignoradas​

Puedes considerar una prueba ignorada como un fallo. Para activar esta funcionalidad, establece failOnIgnoredTests a true en tu configuración de proyecto. Por ejemplo:

object KotestProjectConfig : AbstractProjectConfig() {
  override val failOnIgnoredTests = true
}

Ordenación​

Kotest admite ordenar tanto las especificaciones (specs) como las pruebas de forma independiente.

Orden de los tests​

Al ejecutar múltiples pruebas desde una Spec, existe un orden determinado para su ejecución.

Por defecto se utiliza un orden secuencial (el orden en que los tests están definidos en el spec), pero esto se puede cambiar. Para ver las opciones disponibles, consulta orden de los tests.

Orden de los specs​

Por defecto, el orden de las clases Spec no está definido. Esto suele ser suficiente cuando no tenemos preferencia, pero si necesitamos controlar el orden de ejecución de las specs, podemos usar orden de especificaciones.

Nomenclatura de tests​

Los nombres de las pruebas se pueden ajustar de varias formas.

Mayúsculas y minúsculas​

El uso de mayúsculas/minúsculas en los nombres de prueba se puede controlar cambiando el valor de testNameCase.

Por defecto, el valor es TestNameCase.AsIs, que no realiza ningún cambio.

Al establecerlo en TestNameCase.Lowercase, el nombre de la prueba aparecerá en minúsculas en los resultados.

Si usas una spec que añade prefijos a los nombres de prueba (como WordSpec o BehaviorSpec), los valores TestNameCase.Sentence y TestNameCase.InitialLowercase pueden ser útiles.

Etiquetas en los nombres​

Otra opción es testNameAppendTags, que cuando se establece en true incluirá cualquier etiqueta aplicable en el nombre de la prueba. Por ejemplo, si una prueba foo se define en una spec con las etiquetas linux y spark, el nombre de prueba se ajustaría a foo [linux, spark].

Esta configuración también se puede establecer mediante una propiedad del sistema o variable de entorno kotest.framework.testname.append.tags con valor true.

Espacios en blanco en los nombres​

Si defines nombres de prueba en varias líneas, removeTestNameWhitespace puede ser útil. Considera este ejemplo:

"""this is
   my test case""" {
  // test here
}

Entonces el nombre del test en la salida será this is _ _ _ my test case (nota: los guiones bajos se añaden para énfasis). Al establecer removeTestNameWhitespace en true, este nombre se recortará a this is my test case.

Una forma alternativa de activar esto es estableciendo la propiedad del sistema kotest.framework.testname.multiline en true, que siempre (si está definida) tendrá prioridad sobre el valor aquí establecido.

object KotestProjectConfig : AbstractProjectConfig() {
  override val testNameRemoveWhitespace = true
}

Fábrica de Coroutine Dispatcher​

Puedes especificar una fábrica personalizada de coroutine dispatcher para controlar cómo se ejecutan las corrutinas en tus tests.

object KotestProjectConfig : AbstractProjectConfig() {
  override val coroutineDispatcherFactory = ThreadPerSpecCoroutineContextFactory
}

Para más detalles sobre esta característica, consulta la documentación sobre concurrencia.

Compartir configuración entre módulos​

En proyectos multi-módulo, puede que quieras compartir una configuración de proyecto común entre varios módulos de prueba en lugar de duplicarla en cada uno.

El enfoque recomendado es definir una clase base de configuración open en un módulo compartido, y luego crear una subclase mínima en cada módulo de prueba que lo necesite.

Módulo compartido​

En el módulo compartido (publicado en tu classpath, por ejemplo como conjunto de fuentes jvmMain), define una clase base de configuración abierta:

// shared-module/src/jvmMain/kotlin/com/example/shared/BaseProjectConfig.kt
package com.example.shared

import io.kotest.core.config.AbstractProjectConfig
import kotlin.time.Duration.Companion.seconds

open class BaseProjectConfig : AbstractProjectConfig() {
   override val timeout = 10.seconds
   override val coroutineTestScope = true
   // ... other shared settings
}

Cada módulo de prueba​

En cada módulo de prueba que deba usar la configuración compartida, crea una subclase ligera. No son necesarias sobreescrituras a menos que quieras personalizar el comportamiento para ese módulo:

// my-service/src/jvmTest/kotlin/io/kotest/provided/ProjectConfig.kt
package io.kotest.provided

import com.example.shared.BaseProjectConfig

class ProjectConfig : BaseProjectConfig()
nota

En proyectos multiplataforma, Kotest usa KSP para detectar clases de configuración, que se basa en código fuente y no escanea a través de los límites de los módulos. Por lo tanto, la herencia es el patrón recomendado para compartir configuración en proyectos KMP.

Este patrón mantiene el código repetitivo por módulo en una sola clase vacía, mientras que todos los ajustes compartidos se mantienen en un único lugar.