@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/workflows/kotlin-test.md

@@ -1,312 +1,312 @@
----
-description: Enforce TDD workflow for Kotlin. Write Kotest tests first, then implement. Verify 80%+ coverage with Kover.
----
-
-# Kotlin TDD Command
-
-This command enforces test-driven development methodology for Kotlin code using Kotest, MockK, and Kover.
-
-## What This Command Does
-
-1. **Define Types/Interfaces**: Scaffold function signatures first
-2. **Write Kotest Tests**: Create comprehensive test specs (RED)
-3. **Run Tests**: Verify tests fail for the right reason
-4. **Implement Code**: Write minimal code to pass (GREEN)
-5. **Refactor**: Improve while keeping tests green
-6. **Check Coverage**: Ensure 80%+ coverage with Kover
-
-## When to Use
-
-Use `/kotlin-test` when:
-- Implementing new Kotlin functions or classes
-- Adding test coverage to existing Kotlin code
-- Fixing bugs (write failing test first)
-- Building critical business logic
-- Learning TDD workflow in Kotlin
-
-## TDD Cycle
-
-```
-RED     -> Write failing Kotest test
-GREEN   -> Implement minimal code to pass
-REFACTOR -> Improve code, tests stay green
-REPEAT  -> Next test case
-```
-
-## Example Session
-
-````text
-User: /kotlin-test I need a function to validate user registration requests
-
-Agent:
-# TDD Session: Registration Validator
-
-## Step 1: Define Interface
-
-```kotlin
-// validator/RegistrationValidator.kt
-package com.example.validator
-
-data class RegistrationRequest(
-    val name: String,
-    val email: String,
-    val password: String,
-)
-
-sealed class ValidationResult {
-    data object Valid : ValidationResult()
-    data class Invalid(val errors: List<String>) : ValidationResult()
-}
-
-fun validateRegistration(request: RegistrationRequest): ValidationResult {
-    TODO("not implemented")
-}
-```
-
-## Step 2: Write Kotest Tests (RED)
-
-```kotlin
-// validator/RegistrationValidatorTest.kt
-package com.example.validator
-
-import io.kotest.core.spec.style.FunSpec
-import io.kotest.matchers.shouldBe
-import io.kotest.matchers.types.shouldBeInstanceOf
-
-class RegistrationValidatorTest : FunSpec({
-    test("valid registration returns Valid") {
-        val request = RegistrationRequest(
-            name = "Alice",
-            email = "alice@example.com",
-            password = "SecureP@ss1",
-        )
-
-        val result = validateRegistration(request)
-
-        result.shouldBeInstanceOf<ValidationResult.Valid>()
-    }
-
-    test("blank name returns Invalid") {
-        val request = RegistrationRequest(
-            name = "",
-            email = "alice@example.com",
-            password = "SecureP@ss1",
-        )
-
-        val result = validateRegistration(request)
-
-        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
-        invalid.errors shouldBe listOf("Name is required")
-    }
-
-    test("invalid email returns Invalid") {
-        val request = RegistrationRequest(
-            name = "Alice",
-            email = "not-an-email",
-            password = "SecureP@ss1",
-        )
-
-        val result = validateRegistration(request)
-
-        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
-        invalid.errors shouldBe listOf("Invalid email format")
-    }
-
-    test("short password returns Invalid") {
-        val request = RegistrationRequest(
-            name = "Alice",
-            email = "alice@example.com",
-            password = "short",
-        )
-
-        val result = validateRegistration(request)
-
-        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
-        invalid.errors shouldBe listOf("Password must be at least 8 characters")
-    }
-
-    test("multiple errors returns all errors") {
-        val request = RegistrationRequest(
-            name = "",
-            email = "bad",
-            password = "short",
-        )
-
-        val result = validateRegistration(request)
-
-        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
-        invalid.errors.size shouldBe 3
-    }
-})
-```
-
-## Step 3: Run Tests - Verify FAIL
-
-```bash
-$ ./gradlew test
-
-RegistrationValidatorTest > valid registration returns Valid FAILED
-  kotlin.NotImplementedError: An operation is not implemented
-
-FAILED (5 tests, 0 passed, 5 failed)
-```
-
-✓ Tests fail as expected (NotImplementedError).
-
-## Step 4: Implement Minimal Code (GREEN)
-
-```kotlin
-// validator/RegistrationValidator.kt
-package com.example.validator
-
-private val EMAIL_REGEX = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")
-private const val MIN_PASSWORD_LENGTH = 8
-
-fun validateRegistration(request: RegistrationRequest): ValidationResult {
-    val errors = buildList {
-        if (request.name.isBlank()) add("Name is required")
-        if (!EMAIL_REGEX.matches(request.email)) add("Invalid email format")
-        if (request.password.length < MIN_PASSWORD_LENGTH) add("Password must be at least $MIN_PASSWORD_LENGTH characters")
-    }
-
-    return if (errors.isEmpty()) ValidationResult.Valid
-    else ValidationResult.Invalid(errors)
-}
-```
-
-## Step 5: Run Tests - Verify PASS
-
-```bash
-$ ./gradlew test
-
-RegistrationValidatorTest > valid registration returns Valid PASSED
-RegistrationValidatorTest > blank name returns Invalid PASSED
-RegistrationValidatorTest > invalid email returns Invalid PASSED
-RegistrationValidatorTest > short password returns Invalid PASSED
-RegistrationValidatorTest > multiple errors returns all errors PASSED
-
-PASSED (5 tests, 5 passed, 0 failed)
-```
-
-✓ All tests passing!
-
-## Step 6: Check Coverage
-
-```bash
-$ ./gradlew koverHtmlReport
-
-Coverage: 100.0% of statements
-```
-
-✓ Coverage: 100%
-
-## TDD Complete!
-````
-
-## Test Patterns
-
-### StringSpec (Simplest)
-
-```kotlin
-class CalculatorTest : StringSpec({
-    "add two positive numbers" {
-        Calculator.add(2, 3) shouldBe 5
-    }
-})
-```
-
-### BehaviorSpec (BDD)
-
-```kotlin
-class OrderServiceTest : BehaviorSpec({
-    Given("a valid order") {
-        When("placed") {
-            Then("should be confirmed") { /* ... */ }
-        }
-    }
-})
-```
-
-### Data-Driven Tests
-
-```kotlin
-class ParserTest : FunSpec({
-    context("valid inputs") {
-        withData("2026-01-15", "2026-12-31", "2000-01-01") { input ->
-            parseDate(input).shouldNotBeNull()
-        }
-    }
-})
-```
-
-### Coroutine Testing
-
-```kotlin
-class AsyncServiceTest : FunSpec({
-    test("concurrent fetch completes") {
-        runTest {
-            val result = service.fetchAll()
-            result.shouldNotBeEmpty()
-        }
-    }
-})
-```
-
-## Coverage Commands
-
-```bash
-# Run tests with coverage
-./gradlew koverHtmlReport
-
-# Verify coverage thresholds
-./gradlew koverVerify
-
-# XML report for CI
-./gradlew koverXmlReport
-
-# Open HTML report
-open build/reports/kover/html/index.html
-
-# Run specific test class
-./gradlew test --tests "com.example.UserServiceTest"
-
-# Run with verbose output
-./gradlew test --info
-```
-
-## Coverage Targets
-
-| Code Type | Target |
-|-----------|--------|
-| Critical business logic | 100% |
-| Public APIs | 90%+ |
-| General code | 80%+ |
-| Generated code | Exclude |
-
-## TDD Best Practices
-
-**DO:**
-- Write test FIRST, before any implementation
-- Run tests after each change
-- Use Kotest matchers for expressive assertions
-- Use MockK's `coEvery`/`coVerify` for suspend functions
-- Test behavior, not implementation details
-- Include edge cases (empty, null, max values)
-
-**DON'T:**
-- Write implementation before tests
-- Skip the RED phase
-- Test private functions directly
-- Use `Thread.sleep()` in coroutine tests
-- Ignore flaky tests
-
-## Related Commands
-
-- `/kotlin-build` - Fix build errors
-- `/kotlin-review` - Review code after implementation
-- `/verify` - Run full verification loop
-
-## Related
-
-- Skill: `skills/kotlin-testing/`
-- Skill: `skills/tdd-workflow/`
+---
+description: Enforce TDD workflow for Kotlin. Write Kotest tests first, then implement. Verify 80%+ coverage with Kover.
+---
+
+# Kotlin TDD Command
+
+This command enforces test-driven development methodology for Kotlin code using Kotest, MockK, and Kover.
+
+## What This Command Does
+
+1. **Define Types/Interfaces**: Scaffold function signatures first
+2. **Write Kotest Tests**: Create comprehensive test specs (RED)
+3. **Run Tests**: Verify tests fail for the right reason
+4. **Implement Code**: Write minimal code to pass (GREEN)
+5. **Refactor**: Improve while keeping tests green
+6. **Check Coverage**: Ensure 80%+ coverage with Kover
+
+## When to Use
+
+Use `/kotlin-test` when:
+- Implementing new Kotlin functions or classes
+- Adding test coverage to existing Kotlin code
+- Fixing bugs (write failing test first)
+- Building critical business logic
+- Learning TDD workflow in Kotlin
+
+## TDD Cycle
+
+```
+RED     -> Write failing Kotest test
+GREEN   -> Implement minimal code to pass
+REFACTOR -> Improve code, tests stay green
+REPEAT  -> Next test case
+```
+
+## Example Session
+
+````text
+User: /kotlin-test I need a function to validate user registration requests
+
+Agent:
+# TDD Session: Registration Validator
+
+## Step 1: Define Interface
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+data class RegistrationRequest(
+    val name: String,
+    val email: String,
+    val password: String,
+)
+
+sealed class ValidationResult {
+    data object Valid : ValidationResult()
+    data class Invalid(val errors: List<String>) : ValidationResult()
+}
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    TODO("not implemented")
+}
+```
+
+## Step 2: Write Kotest Tests (RED)
+
+```kotlin
+// validator/RegistrationValidatorTest.kt
+package com.example.validator
+
+import io.kotest.core.spec.style.FunSpec
+import io.kotest.matchers.shouldBe
+import io.kotest.matchers.types.shouldBeInstanceOf
+
+class RegistrationValidatorTest : FunSpec({
+    test("valid registration returns Valid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        result.shouldBeInstanceOf<ValidationResult.Valid>()
+    }
+
+    test("blank name returns Invalid") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "alice@example.com",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Name is required")
+    }
+
+    test("invalid email returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "not-an-email",
+            password = "SecureP@ss1",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Invalid email format")
+    }
+
+    test("short password returns Invalid") {
+        val request = RegistrationRequest(
+            name = "Alice",
+            email = "alice@example.com",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors shouldBe listOf("Password must be at least 8 characters")
+    }
+
+    test("multiple errors returns all errors") {
+        val request = RegistrationRequest(
+            name = "",
+            email = "bad",
+            password = "short",
+        )
+
+        val result = validateRegistration(request)
+
+        val invalid = result.shouldBeInstanceOf<ValidationResult.Invalid>()
+        invalid.errors.size shouldBe 3
+    }
+})
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid FAILED
+  kotlin.NotImplementedError: An operation is not implemented
+
+FAILED (5 tests, 0 passed, 5 failed)
+```
+
+✓ Tests fail as expected (NotImplementedError).
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```kotlin
+// validator/RegistrationValidator.kt
+package com.example.validator
+
+private val EMAIL_REGEX = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")
+private const val MIN_PASSWORD_LENGTH = 8
+
+fun validateRegistration(request: RegistrationRequest): ValidationResult {
+    val errors = buildList {
+        if (request.name.isBlank()) add("Name is required")
+        if (!EMAIL_REGEX.matches(request.email)) add("Invalid email format")
+        if (request.password.length < MIN_PASSWORD_LENGTH) add("Password must be at least $MIN_PASSWORD_LENGTH characters")
+    }
+
+    return if (errors.isEmpty()) ValidationResult.Valid
+    else ValidationResult.Invalid(errors)
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+$ ./gradlew test
+
+RegistrationValidatorTest > valid registration returns Valid PASSED
+RegistrationValidatorTest > blank name returns Invalid PASSED
+RegistrationValidatorTest > invalid email returns Invalid PASSED
+RegistrationValidatorTest > short password returns Invalid PASSED
+RegistrationValidatorTest > multiple errors returns all errors PASSED
+
+PASSED (5 tests, 5 passed, 0 failed)
+```
+
+✓ All tests passing!
+
+## Step 6: Check Coverage
+
+```bash
+$ ./gradlew koverHtmlReport
+
+Coverage: 100.0% of statements
+```
+
+✓ Coverage: 100%
+
+## TDD Complete!
+````
+
+## Test Patterns
+
+### StringSpec (Simplest)
+
+```kotlin
+class CalculatorTest : StringSpec({
+    "add two positive numbers" {
+        Calculator.add(2, 3) shouldBe 5
+    }
+})
+```
+
+### BehaviorSpec (BDD)
+
+```kotlin
+class OrderServiceTest : BehaviorSpec({
+    Given("a valid order") {
+        When("placed") {
+            Then("should be confirmed") { /* ... */ }
+        }
+    }
+})
+```
+
+### Data-Driven Tests
+
+```kotlin
+class ParserTest : FunSpec({
+    context("valid inputs") {
+        withData("2026-01-15", "2026-12-31", "2000-01-01") { input ->
+            parseDate(input).shouldNotBeNull()
+        }
+    }
+})
+```
+
+### Coroutine Testing
+
+```kotlin
+class AsyncServiceTest : FunSpec({
+    test("concurrent fetch completes") {
+        runTest {
+            val result = service.fetchAll()
+            result.shouldNotBeEmpty()
+        }
+    }
+})
+```
+
+## Coverage Commands
+
+```bash
+# Run tests with coverage
+./gradlew koverHtmlReport
+
+# Verify coverage thresholds
+./gradlew koverVerify
+
+# XML report for CI
+./gradlew koverXmlReport
+
+# Open HTML report
+open build/reports/kover/html/index.html
+
+# Run specific test class
+./gradlew test --tests "com.example.UserServiceTest"
+
+# Run with verbose output
+./gradlew test --info
+```
+
+## Coverage Targets
+
+| Code Type | Target |
+|-----------|--------|
+| Critical business logic | 100% |
+| Public APIs | 90%+ |
+| General code | 80%+ |
+| Generated code | Exclude |
+
+## TDD Best Practices
+
+**DO:**
+- Write test FIRST, before any implementation
+- Run tests after each change
+- Use Kotest matchers for expressive assertions
+- Use MockK's `coEvery`/`coVerify` for suspend functions
+- Test behavior, not implementation details
+- Include edge cases (empty, null, max values)
+
+**DON'T:**
+- Write implementation before tests
+- Skip the RED phase
+- Test private functions directly
+- Use `Thread.sleep()` in coroutine tests
+- Ignore flaky tests
+
+## Related Commands
+
+- `/kotlin-build` - Fix build errors
+- `/kotlin-review` - Review code after implementation
+- `/verify` - Run full verification loop
+
+## Related
+
+- Skill: `skills/kotlin-testing/`
+- Skill: `skills/tdd-workflow/`