theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/testing-kotlin/SKILL.md

@@ -0,0 +1,829 @@
+---
+name: testing-kotlin
+description: Patrones de testing en Kotlin con Kotest, MockK, testing de corrutinas, testing basado en propiedades y cobertura con Kover, siguiendo la metodología TDD.
+---
+
+# Patrones de testing en Kotlin
+
+Patrones completos de testing en Kotlin para escribir pruebas fiables y mantenibles siguiendo la metodología TDD con Kotest y MockK.
+
+## Cuándo usarla
+
+- Al escribir nuevas funciones o clases en Kotlin
+- Al añadir cobertura de pruebas a código Kotlin existente
+- Al implementar pruebas basadas en propiedades
+- Al seguir el flujo TDD en proyectos Kotlin
+- Al configurar Kover para cobertura de código
+
+## Cómo funciona
+
+1. **Identifica el código objetivo** — encuentra la función, clase o módulo a probar
+2. **Escribe una spec de Kotest** — elige un estilo de spec (StringSpec, FunSpec, BehaviorSpec) acorde al alcance de la prueba
+3. **Mockea las dependencias** — usa MockK para aislar la unidad bajo prueba
+4. **Ejecuta las pruebas (ROJO)** — verifica que la prueba falla con el error esperado
+5. **Implementa el código (VERDE)** — escribe el código mínimo para pasar la prueba
+6. **Refactoriza** — mejora la implementación manteniendo las pruebas en verde
+7. **Comprueba la cobertura** — ejecuta `./gradlew koverHtmlReport` y verifica una cobertura de 80 % o más
+
+## Ejemplos
+
+Las siguientes secciones contienen ejemplos detallados y ejecutables de cada patrón de testing:
+
+### Referencia rápida
+
+- **Specs de Kotest** — ejemplos de StringSpec, FunSpec, BehaviorSpec, DescribeSpec en [Estilos de spec de Kotest](#estilos-de-spec-de-kotest)
+- **Mocking** — configuración de MockK, mocking de corrutinas, captura de argumentos en [MockK](#mockk)
+- **Recorrido TDD** — ciclo ROJO/VERDE/REFACTOR completo con EmailValidator en [Flujo TDD para Kotlin](#flujo-tdd-para-kotlin)
+- **Cobertura** — configuración y comandos de Kover en [Cobertura con Kover](#cobertura-con-kover)
+- **Testing de Ktor** — configuración de testApplication en [Testing con testApplication de Ktor](#testing-con-testapplication-de-ktor)
+
+### Flujo TDD para Kotlin
+
+#### El ciclo ROJO-VERDE-REFACTOR
+
+```
+ROJO      -> Escribe primero una prueba que falle
+VERDE     -> Escribe el código mínimo para pasar la prueba
+REFACTOR  -> Mejora el código manteniendo las pruebas en verde
+REPITE    -> Continúa con el siguiente requisito
+```
+
+#### TDD paso a paso en Kotlin
+
+```kotlin
+// Paso 1: define la interfaz/firma
+// EmailValidator.kt
+package com.example.validator
+
+fun validateEmail(email: String): Result<String> {
+    TODO("sin implementar")
+}
+
+// Paso 2: escribe la prueba que falla (ROJO)
+// EmailValidatorTest.kt
+package com.example.validator
+
+import io.kotest.core.spec.style.StringSpec
+import io.kotest.matchers.result.shouldBeFailure
+import io.kotest.matchers.result.shouldBeSuccess
+
+class EmailValidatorTest : StringSpec({
+    "un email válido devuelve success" {
+        validateEmail("user@example.com").shouldBeSuccess("user@example.com")
+    }
+
+    "un email vacío devuelve failure" {
+        validateEmail("").shouldBeFailure()
+    }
+
+    "un email sin @ devuelve failure" {
+        validateEmail("userexample.com").shouldBeFailure()
+    }
+})
+
+// Paso 3: ejecuta las pruebas - verifica que FALLAN
+// $ ./gradlew test
+// EmailValidatorTest > un email válido devuelve success FAILED
+//   kotlin.NotImplementedError: An operation is not implemented
+
+// Paso 4: implementa el código mínimo (VERDE)
+fun validateEmail(email: String): Result<String> {
+    if (email.isBlank()) return Result.failure(IllegalArgumentException("El email no puede estar en blanco"))
+    if ('@' !in email) return Result.failure(IllegalArgumentException("El email debe contener @"))
+    val regex = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")
+    if (!regex.matches(email)) return Result.failure(IllegalArgumentException("Formato de email inválido"))
+    return Result.success(email)
+}
+
+// Paso 5: ejecuta las pruebas - verifica que PASAN
+// $ ./gradlew test
+// EmailValidatorTest > un email válido devuelve success PASSED
+// EmailValidatorTest > un email vacío devuelve failure PASSED
+// EmailValidatorTest > un email sin @ devuelve failure PASSED
+
+// Paso 6: refactoriza si hace falta y verifica que las pruebas siguen pasando
+```
+
+### Estilos de spec de Kotest
+
+#### StringSpec (el más simple)
+
+```kotlin
+class CalculatorTest : StringSpec({
+    "suma dos números positivos" {
+        Calculator.add(2, 3) shouldBe 5
+    }
+
+    "suma números negativos" {
+        Calculator.add(-1, -2) shouldBe -3
+    }
+
+    "suma cero" {
+        Calculator.add(0, 5) shouldBe 5
+    }
+})
+```
+
+#### FunSpec (estilo JUnit)
+
+```kotlin
+class UserServiceTest : FunSpec({
+    val repository = mockk<UserRepository>()
+    val service = UserService(repository)
+
+    test("getUser devuelve el usuario cuando existe") {
+        val expected = User(id = "1", name = "Alice")
+        coEvery { repository.findById("1") } returns expected
+
+        val result = service.getUser("1")
+
+        result shouldBe expected
+    }
+
+    test("getUser lanza excepción cuando no existe") {
+        coEvery { repository.findById("999") } returns null
+
+        shouldThrow<UserNotFoundException> {
+            service.getUser("999")
+        }
+    }
+})
+```
+
+#### BehaviorSpec (estilo BDD)
+
+```kotlin
+class OrderServiceTest : BehaviorSpec({
+    val repository = mockk<OrderRepository>()
+    val paymentService = mockk<PaymentService>()
+    val service = OrderService(repository, paymentService)
+
+    Given("una solicitud de pedido válida") {
+        val request = CreateOrderRequest(
+            userId = "user-1",
+            items = listOf(OrderItem("product-1", quantity = 2)),
+        )
+
+        When("se realiza el pedido") {
+            coEvery { paymentService.charge(any()) } returns PaymentResult.Success
+            coEvery { repository.save(any()) } answers { firstArg() }
+
+            val result = service.placeOrder(request)
+
+            Then("debe devolver un pedido confirmado") {
+                result.status shouldBe OrderStatus.CONFIRMED
+            }
+
+            Then("debe cobrar el pago") {
+                coVerify(exactly = 1) { paymentService.charge(any()) }
+            }
+        }
+
+        When("el pago falla") {
+            coEvery { paymentService.charge(any()) } returns PaymentResult.Declined
+
+            Then("debe lanzar PaymentException") {
+                shouldThrow<PaymentException> {
+                    service.placeOrder(request)
+                }
+            }
+        }
+    }
+})
+```
+
+#### DescribeSpec (estilo RSpec)
+
+```kotlin
+class UserValidatorTest : DescribeSpec({
+    describe("validateUser") {
+        val validator = UserValidator()
+
+        context("con entrada válida") {
+            it("acepta un usuario normal") {
+                val user = CreateUserRequest("Alice", "alice@example.com")
+                validator.validate(user).shouldBeValid()
+            }
+        }
+
+        context("con nombre inválido") {
+            it("rechaza un nombre en blanco") {
+                val user = CreateUserRequest("", "alice@example.com")
+                validator.validate(user).shouldBeInvalid()
+            }
+
+            it("rechaza un nombre que excede la longitud máxima") {
+                val user = CreateUserRequest("A".repeat(256), "alice@example.com")
+                validator.validate(user).shouldBeInvalid()
+            }
+        }
+    }
+})
+```
+
+### Matchers de Kotest
+
+#### Matchers básicos
+
+```kotlin
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.shouldNotBe
+import io.kotest.matchers.string.*
+import io.kotest.matchers.collections.*
+import io.kotest.matchers.nulls.*
+
+// Igualdad
+result shouldBe expected
+result shouldNotBe unexpected
+
+// Strings
+name shouldStartWith "Al"
+name shouldEndWith "ice"
+name shouldContain "lic"
+name shouldMatch Regex("[A-Z][a-z]+")
+name.shouldBeBlank()
+
+// Colecciones
+list shouldContain "item"
+list shouldHaveSize 3
+list.shouldBeSorted()
+list.shouldContainAll("a", "b", "c")
+list.shouldBeEmpty()
+
+// Nulls
+result.shouldNotBeNull()
+result.shouldBeNull()
+
+// Tipos
+result.shouldBeInstanceOf<User>()
+
+// Números
+count shouldBeGreaterThan 0
+price shouldBeInRange 1.0..100.0
+
+// Excepciones
+shouldThrow<IllegalArgumentException> {
+    validateAge(-1)
+}.message shouldBe "La edad debe ser positiva"
+
+shouldNotThrow<Exception> {
+    validateAge(25)
+}
+```
+
+#### Matchers personalizados
+
+```kotlin
+fun beActiveUser() = object : Matcher<User> {
+    override fun test(value: User) = MatcherResult(
+        value.isActive && value.lastLogin != null,
+        { "El usuario ${value.id} debería estar activo con un último login" },
+        { "El usuario ${value.id} no debería estar activo" },
+    )
+}
+
+// Uso
+user should beActiveUser()
+```
+
+### MockK
+
+#### Mocking básico
+
+```kotlin
+class UserServiceTest : FunSpec({
+    val repository = mockk<UserRepository>()
+    val logger = mockk<Logger>(relaxed = true) // Relaxed: devuelve valores por defecto
+    val service = UserService(repository, logger)
+
+    beforeTest {
+        clearMocks(repository, logger)
+    }
+
+    test("findUser delega en el repositorio") {
+        val expected = User(id = "1", name = "Alice")
+        every { repository.findById("1") } returns expected
+
+        val result = service.findUser("1")
+
+        result shouldBe expected
+        verify(exactly = 1) { repository.findById("1") }
+    }
+
+    test("findUser devuelve null para un id desconocido") {
+        every { repository.findById(any()) } returns null
+
+        val result = service.findUser("desconocido")
+
+        result.shouldBeNull()
+    }
+})
+```
+
+#### Mocking de corrutinas
+
+```kotlin
+class AsyncUserServiceTest : FunSpec({
+    val repository = mockk<UserRepository>()
+    val service = UserService(repository)
+
+    test("getUser como función suspendida") {
+        coEvery { repository.findById("1") } returns User(id = "1", name = "Alice")
+
+        val result = service.getUser("1")
+
+        result.name shouldBe "Alice"
+        coVerify { repository.findById("1") }
+    }
+
+    test("getUser con retardo") {
+        coEvery { repository.findById("1") } coAnswers {
+            delay(100) // Simula trabajo asíncrono
+            User(id = "1", name = "Alice")
+        }
+
+        val result = service.getUser("1")
+        result.name shouldBe "Alice"
+    }
+})
+```
+
+#### Captura de argumentos
+
+```kotlin
+test("save captura el argumento user") {
+    val slot = slot<User>()
+    coEvery { repository.save(capture(slot)) } returns Unit
+
+    service.createUser(CreateUserRequest("Alice", "alice@example.com"))
+
+    slot.captured.name shouldBe "Alice"
+    slot.captured.email shouldBe "alice@example.com"
+    slot.captured.id.shouldNotBeNull()
+}
+```
+
+#### Spy y mocking parcial
+
+```kotlin
+test("spy sobre un objeto real") {
+    val realService = UserService(repository)
+    val spy = spyk(realService)
+
+    every { spy.generateId() } returns "id-fijo"
+
+    spy.createUser(request)
+
+    verify { spy.generateId() } // Sobrescrito
+    // El resto de métodos usa la implementación real
+}
+```
+
+### Testing de corrutinas
+
+#### runTest para funciones suspendidas
+
+```kotlin
+import kotlinx.coroutines.test.runTest
+
+class CoroutineServiceTest : FunSpec({
+    test("las descargas concurrentes terminan juntas") {
+        runTest {
+            val service = DataService(testScope = this)
+
+            val result = service.fetchAllData()
+
+            result.users.shouldNotBeEmpty()
+            result.products.shouldNotBeEmpty()
+        }
+    }
+
+    test("timeout tras el retardo") {
+        runTest {
+            val service = SlowService()
+
+            shouldThrow<TimeoutCancellationException> {
+                withTimeout(100) {
+                    service.slowOperation() // Tarda > 100 ms
+                }
+            }
+        }
+    }
+})
+```
+
+#### Testing de Flows
+
+```kotlin
+import io.kotest.matchers.collections.shouldContainInOrder
+import kotlinx.coroutines.flow.MutableSharedFlow
+import kotlinx.coroutines.flow.toList
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.test.advanceTimeBy
+import kotlinx.coroutines.test.runTest
+
+class FlowServiceTest : FunSpec({
+    test("observeUsers emite actualizaciones") {
+        runTest {
+            val service = UserFlowService()
+
+            val emissions = service.observeUsers()
+                .take(3)
+                .toList()
+
+            emissions shouldHaveSize 3
+            emissions.last().shouldNotBeEmpty()
+        }
+    }
+
+    test("searchUsers aplica debounce a la entrada") {
+        runTest {
+            val service = SearchService()
+            val queries = MutableSharedFlow<String>()
+
+            val results = mutableListOf<List<User>>()
+            val job = launch {
+                service.searchUsers(queries).collect { results.add(it) }
+            }
+
+            queries.emit("a")
+            queries.emit("ab")
+            queries.emit("abc") // Solo esta debería disparar la búsqueda
+            advanceTimeBy(500)
+
+            results shouldHaveSize 1
+            job.cancel()
+        }
+    }
+})
+```
+
+#### TestDispatcher
+
+```kotlin
+import kotlinx.coroutines.test.StandardTestDispatcher
+import kotlinx.coroutines.test.advanceUntilIdle
+
+class DispatcherTest : FunSpec({
+    test("usa un test dispatcher para ejecución controlada") {
+        val dispatcher = StandardTestDispatcher()
+
+        runTest(dispatcher) {
+            var completed = false
+
+            launch {
+                delay(1000)
+                completed = true
+            }
+
+            completed shouldBe false
+            advanceTimeBy(1000)
+            completed shouldBe true
+        }
+    }
+})
+```
+
+### Testing basado en propiedades
+
+#### Property testing con Kotest
+
+```kotlin
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.property.Arb
+import io.kotest.property.arbitrary.*
+import io.kotest.property.forAll
+import io.kotest.property.checkAll
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.encodeToString
+import kotlinx.serialization.decodeFromString
+
+// Nota: la prueba de ida y vuelta de serialización de abajo requiere que la data class User
+// esté anotada con @Serializable (de kotlinx.serialization).
+
+class PropertyTest : FunSpec({
+    test("invertir un string es involutivo") {
+        forAll<String> { s ->
+            s.reversed().reversed() == s
+        }
+    }
+
+    test("ordenar una lista es idempotente") {
+        forAll(Arb.list(Arb.int())) { list ->
+            list.sorted() == list.sorted().sorted()
+        }
+    }
+
+    test("la ida y vuelta de serialización preserva los datos") {
+        checkAll(Arb.bind(Arb.string(1..50), Arb.string(5..100)) { name, email ->
+            User(name = name, email = "$email@test.com")
+        }) { user ->
+            val json = Json.encodeToString(user)
+            val decoded = Json.decodeFromString<User>(json)
+            decoded shouldBe user
+        }
+    }
+})
+```
+
+#### Generadores personalizados
+
+```kotlin
+val userArb: Arb<User> = Arb.bind(
+    Arb.string(minSize = 1, maxSize = 50),
+    Arb.email(),
+    Arb.enum<Role>(),
+) { name, email, role ->
+    User(
+        id = UserId(UUID.randomUUID().toString()),
+        name = name,
+        email = Email(email),
+        role = role,
+    )
+}
+
+val moneyArb: Arb<Money> = Arb.bind(
+    Arb.long(1L..1_000_000L),
+    Arb.enum<Currency>(),
+) { amount, currency ->
+    Money(amount, currency)
+}
+```
+
+### Testing dirigido por datos
+
+#### withData en Kotest
+
+```kotlin
+class ParserTest : FunSpec({
+    context("parseo de fechas válidas") {
+        withData(
+            "2026-01-15" to LocalDate(2026, 1, 15),
+            "2026-12-31" to LocalDate(2026, 12, 31),
+            "2000-01-01" to LocalDate(2000, 1, 1),
+        ) { (input, expected) ->
+            parseDate(input) shouldBe expected
+        }
+    }
+
+    context("rechazo de fechas inválidas") {
+        withData(
+            nameFn = { "rechaza '$it'" },
+            "no-es-fecha",
+            "2026-13-01",
+            "2026-00-15",
+            "",
+        ) { input ->
+            shouldThrow<DateParseException> {
+                parseDate(input)
+            }
+        }
+    }
+})
+```
+
+### Ciclo de vida de las pruebas y fixtures
+
+#### BeforeTest / AfterTest
+
+```kotlin
+class DatabaseTest : FunSpec({
+    lateinit var db: Database
+
+    beforeSpec {
+        db = Database.connect("jdbc:h2:mem:test;DB_CLOSE_DELAY=-1")
+        transaction(db) {
+            SchemaUtils.create(UsersTable)
+        }
+    }
+
+    afterSpec {
+        transaction(db) {
+            SchemaUtils.drop(UsersTable)
+        }
+    }
+
+    beforeTest {
+        transaction(db) {
+            UsersTable.deleteAll()
+        }
+    }
+
+    test("insertar y recuperar un usuario") {
+        transaction(db) {
+            UsersTable.insert {
+                it[name] = "Alice"
+                it[email] = "alice@example.com"
+            }
+        }
+
+        val users = transaction(db) {
+            UsersTable.selectAll().map { it[UsersTable.name] }
+        }
+
+        users shouldContain "Alice"
+    }
+})
+```
+
+#### Extensiones de Kotest
+
+```kotlin
+// Extensión de prueba reutilizable
+class DatabaseExtension : BeforeSpecListener, AfterSpecListener {
+    lateinit var db: Database
+
+    override suspend fun beforeSpec(spec: Spec) {
+        db = Database.connect("jdbc:h2:mem:test;DB_CLOSE_DELAY=-1")
+    }
+
+    override suspend fun afterSpec(spec: Spec) {
+        // limpieza
+    }
+}
+
+class UserRepositoryTest : FunSpec({
+    val dbExt = DatabaseExtension()
+    register(dbExt)
+
+    test("guardar y encontrar un usuario") {
+        val repo = UserRepository(dbExt.db)
+        // ...
+    }
+})
+```
+
+### Cobertura con Kover
+
+#### Configuración de Gradle
+
+```kotlin
+// build.gradle.kts
+plugins {
+    id("org.jetbrains.kotlinx.kover") version "0.9.7"
+}
+
+kover {
+    reports {
+        total {
+            html { onCheck = true }
+            xml { onCheck = true }
+        }
+        filters {
+            excludes {
+                classes("*.generated.*", "*.config.*")
+            }
+        }
+        verify {
+            rule {
+                minBound(80) // Falla el build por debajo del 80 % de cobertura
+            }
+        }
+    }
+}
+```
+
+#### Comandos de cobertura
+
+```bash
+# Ejecutar pruebas con cobertura
+./gradlew koverHtmlReport
+
+# Verificar umbrales de cobertura
+./gradlew koverVerify
+
+# Informe XML para CI
+./gradlew koverXmlReport
+
+# Ver el informe HTML (usa el comando de tu sistema)
+# macOS:   open build/reports/kover/html/index.html
+# Linux:   xdg-open build/reports/kover/html/index.html
+# Windows: start build/reports/kover/html/index.html
+```
+
+#### Objetivos de cobertura
+
+| Tipo de código | Objetivo |
+|-----------|--------|
+| Lógica de negocio crítica | 100 % |
+| APIs públicas | 90 %+ |
+| Código general | 80 %+ |
+| Código generado / de configuración | Excluir |
+
+### Testing con testApplication de Ktor
+
+```kotlin
+class ApiRoutesTest : FunSpec({
+    test("GET /users devuelve la lista") {
+        testApplication {
+            application {
+                configureRouting()
+                configureSerialization()
+            }
+
+            val response = client.get("/users")
+
+            response.status shouldBe HttpStatusCode.OK
+            val users = response.body<List<UserResponse>>()
+            users.shouldNotBeEmpty()
+        }
+    }
+
+    test("POST /users crea un usuario") {
+        testApplication {
+            application {
+                configureRouting()
+                configureSerialization()
+            }
+
+            val response = client.post("/users") {
+                contentType(ContentType.Application.Json)
+                setBody(CreateUserRequest("Alice", "alice@example.com"))
+            }
+
+            response.status shouldBe HttpStatusCode.Created
+        }
+    }
+})
+```
+
+### Comandos de testing
+
+```bash
+# Ejecutar todas las pruebas
+./gradlew test
+
+# Ejecutar una clase de prueba concreta
+./gradlew test --tests "com.example.UserServiceTest"
+
+# Ejecutar una prueba concreta
+./gradlew test --tests "com.example.UserServiceTest.getUser devuelve el usuario cuando existe"
+
+# Ejecutar con salida detallada
+./gradlew test --info
+
+# Ejecutar con cobertura
+./gradlew koverHtmlReport
+
+# Ejecutar detekt (análisis estático)
+./gradlew detekt
+
+# Ejecutar ktlint (comprobación de formato)
+./gradlew ktlintCheck
+
+# Testing continuo
+./gradlew test --continuous
+```
+
+### Buenas prácticas
+
+**SÍ:**
+- Escribe las pruebas PRIMERO (TDD)
+- Usa los estilos de spec de Kotest de forma consistente en todo el proyecto
+- Usa `coEvery`/`coVerify` de MockK para funciones suspendidas
+- Usa `runTest` para el testing de corrutinas
+- Prueba el comportamiento, no la implementación
+- Usa testing basado en propiedades para funciones puras
+- Usa fixtures de prueba con `data class` para mayor claridad
+
+**NO:**
+- No mezcles frameworks de testing (elige Kotest y mantente en él)
+- No mockees data classes (usa instancias reales)
+- No uses `Thread.sleep()` en pruebas de corrutinas (usa `advanceTimeBy`)
+- No te saltes la fase ROJA del TDD
+- No pruebes funciones privadas directamente
+- No ignores las pruebas inestables (flaky)
+
+### Integración con CI/CD
+
+```yaml
+# Ejemplo con GitHub Actions
+test:
+  runs-on: ubuntu-latest
+  steps:
+    - uses: actions/checkout@v4
+    - uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version: '21'
+
+    - name: Ejecutar pruebas con cobertura
+      run: ./gradlew test koverXmlReport
+
+    - name: Verificar cobertura
+      run: ./gradlew koverVerify
+
+    - name: Subir cobertura
+      uses: codecov/codecov-action@v5
+      with:
+        files: build/reports/kover/report.xml
+        token: ${{ secrets.CODECOV_TOKEN }}
+```
+
+**Recuerda**: las pruebas son documentación. Muestran cómo se pretende usar tu código Kotlin. Usa los matchers expresivos de Kotest para que las pruebas sean legibles y MockK para un mocking limpio de las dependencias.
+
+## Skills relacionadas
+
+- `patrones-kotlin` — patrones idiomáticos de Kotlin
+- `corrutinas-flows-kotlin` — corrutinas y Flow en profundidad
+- `flujo-tdd` — el ciclo ROJO -> VERDE -> REFACTOR a nivel de repositorio