theus-cli 0.2.82 → 0.2.84

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

@@ -1,829 +0,0 @@
----
-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