The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat: add kotlin commands and skill pack
Affaan Mustafa135eb4c98d3a
diff --git a/.cursor/rules/kotlin-coding-style.md b/.cursor/rules/kotlin-coding-style.mdnew file mode 100644index 000000000..e63a1bc70--- /dev/null+++ b/.cursor/rules/kotlin-coding-style.md@@ -0,0 +1,36 @@+---+description: "Kotlin coding style extending common rules"+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]+alwaysApply: false+---+# Kotlin Coding Style++> This file extends the common coding style rule with Kotlin-specific content.++## Formatting++- **ktfmt** or **ktlint** are mandatory for consistent formatting+- Use trailing commas in multiline declarations++## Immutability++- `val` over `var` always+- Immutable collections by default (`List`, `Map`, `Set`)+- Use `data class` with `copy()` for immutable updates++## Null Safety++- Avoid `!!` -- use `?.`, `?:`, `require`, or `checkNotNull`+- Handle platform types explicitly at Java interop boundaries++## Expression Bodies++Prefer expression bodies for single-expression functions:++```kotlin+fun isAdult(age: Int): Boolean = age >= 18+```++## Reference++See skill: `kotlin-patterns` for comprehensive Kotlin idioms and patterns.diff --git a/.cursor/rules/kotlin-hooks.md b/.cursor/rules/kotlin-hooks.mdnew file mode 100644index 000000000..8ed503d44--- /dev/null+++ b/.cursor/rules/kotlin-hooks.md@@ -0,0 +1,16 @@+---+description: "Kotlin hooks extending common rules"+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]+alwaysApply: false+---+# Kotlin Hooks++> This file extends the common hooks rule with Kotlin-specific content.++## PostToolUse Hooks++Configure in `~/.claude/settings.json`:++- **ktfmt/ktlint**: Auto-format `.kt` and `.kts` files after edit+- **detekt**: Run static analysis after editing Kotlin files+- **./gradlew build**: Verify compilation after changesdiff --git a/.cursor/rules/kotlin-patterns.md b/.cursor/rules/kotlin-patterns.mdnew file mode 100644index 000000000..c5958da26--- /dev/null+++ b/.cursor/rules/kotlin-patterns.md@@ -0,0 +1,50 @@+---+description: "Kotlin patterns extending common rules"+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]+alwaysApply: false+---+# Kotlin Patterns++> This file extends the common patterns rule with Kotlin-specific content.++## Sealed Classes++Use sealed classes/interfaces for exhaustive type hierarchies:++```kotlin+sealed class Result<out T> {+ data class Success<T>(val data: T) : Result<T>()+ data class Failure(val error: AppError) : Result<Nothing>()+}+```++## Extension Functions++Add behavior without inheritance, scoped to where they're used:++```kotlin+fun String.toSlug(): String =+ lowercase().replace(Regex("[^a-z0-9\\s-]"), "").replace(Regex("\\s+"), "-")+```++## Scope Functions++- `let`: Transform nullable or scoped result+- `apply`: Configure an object+- `also`: Side effects+- Avoid nesting scope functions++## Dependency Injection++Use Koin for DI in Ktor projects:++```kotlin+val appModule = module {+ single<UserRepository> { ExposedUserRepository(get()) }+ single { UserService(get()) }+}+```++## Reference++See skill: `kotlin-patterns` for comprehensive Kotlin patterns including coroutines, DSL builders, and delegation.diff --git a/.cursor/rules/kotlin-security.md b/.cursor/rules/kotlin-security.mdnew file mode 100644index 000000000..43ad7cc5a--- /dev/null+++ b/.cursor/rules/kotlin-security.md@@ -0,0 +1,58 @@+---+description: "Kotlin security extending common rules"+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]+alwaysApply: false+---+# Kotlin Security++> This file extends the common security rule with Kotlin-specific content.++## Secret Management++```kotlin+val apiKey = System.getenv("API_KEY")+ ?: throw IllegalStateException("API_KEY not configured")+```++## SQL Injection Prevention++Always use Exposed's parameterized queries:++```kotlin+// Good: Parameterized via Exposed DSL+UsersTable.selectAll().where { UsersTable.email eq email }++// Bad: String interpolation in raw SQL+exec("SELECT * FROM users WHERE email = '$email'")+```++## Authentication++Use Ktor's Auth plugin with JWT:++```kotlin+install(Authentication) {+ jwt("jwt") {+ verifier(+ JWT.require(Algorithm.HMAC256(secret))+ .withAudience(audience)+ .withIssuer(issuer)+ .build()+ )+ validate { credential ->+ val payload = credential.payload+ if (payload.audience.contains(audience) &&+ payload.issuer == issuer &&+ payload.subject != null) {+ JWTPrincipal(payload)+ } else {+ null+ }+ }+ }+}+```++## Null Safety as Security++Kotlin's type system prevents null-related vulnerabilities -- avoid `!!` to maintain this guarantee.diff --git a/.cursor/rules/kotlin-testing.md b/.cursor/rules/kotlin-testing.mdnew file mode 100644index 000000000..bf749043e--- /dev/null+++ b/.cursor/rules/kotlin-testing.md@@ -0,0 +1,38 @@+---+description: "Kotlin testing extending common rules"+globs: ["**/*.kt", "**/*.kts", "**/build.gradle.kts"]+alwaysApply: false+---+# Kotlin Testing++> This file extends the common testing rule with Kotlin-specific content.++## Framework++Use **Kotest** with spec styles (StringSpec, FunSpec, BehaviorSpec) and **MockK** for mocking.++## Coroutine Testing++Use `runTest` from `kotlinx-coroutines-test`:++```kotlin+test("async operation completes") {+ runTest {+ val result = service.fetchData()+ result.shouldNotBeEmpty()+ }+}+```++## Coverage++Use **Kover** for coverage reporting:++```bash+./gradlew koverHtmlReport+./gradlew koverVerify+```++## Reference++See skill: `kotlin-testing` for detailed Kotest patterns, MockK usage, and property-based testing.diff --git a/agents/kotlin-build-resolver.md b/agents/kotlin-build-resolver.mdnew file mode 100644index 000000000..705afd32a--- /dev/null+++ b/agents/kotlin-build-resolver.md@@ -0,0 +1,118 @@+---+name: kotlin-build-resolver+description: Kotlin/Gradle build, compilation, and dependency error resolution specialist. Fixes build errors, Kotlin compiler errors, and Gradle issues with minimal changes. Use when Kotlin builds fail.+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]+model: sonnet+---++# Kotlin Build Error Resolver++You are an expert Kotlin/Gradle build error resolution specialist. Your mission is to fix Kotlin build errors, Gradle configuration issues, and dependency resolution failures with **minimal, surgical changes**.++## Core Responsibilities++1. Diagnose Kotlin compilation errors+2. Fix Gradle build configuration issues+3. Resolve dependency conflicts and version mismatches+4. Handle Kotlin compiler errors and warnings+5. Fix detekt and ktlint violations++## Diagnostic Commands++Run these in order:++```bash+./gradlew build 2>&1+./gradlew detekt 2>&1 || echo "detekt not configured"+./gradlew ktlintCheck 2>&1 || echo "ktlint not configured"+./gradlew dependencies --configuration runtimeClasspath 2>/dev/null | head -100+```++## Resolution Workflow++```text+1. ./gradlew build -> Parse error message+2. Read affected file -> Understand context+3. Apply minimal fix -> Only what's needed+4. ./gradlew build -> Verify fix+5. ./gradlew test -> Ensure nothing broke+```++## Common Fix Patterns++| Error | Cause | Fix |+|-------|-------|-----|+| `Unresolved reference: X` | Missing import, typo, missing dependency | Add import or dependency |+| `Type mismatch: Required X, Found Y` | Wrong type, missing conversion | Add conversion or fix type |+| `None of the following candidates is applicable` | Wrong overload, wrong argument types | Fix argument types or add explicit cast |+| `Smart cast impossible` | Mutable property or concurrent access | Use local `val` copy or `let` |+| `'when' expression must be exhaustive` | Missing branch in sealed class `when` | Add missing branches or `else` |+| `Suspend function can only be called from coroutine` | Missing `suspend` or coroutine scope | Add `suspend` modifier or launch coroutine |+| `Cannot access 'X': it is internal in 'Y'` | Visibility issue | Change visibility or use public API |+| `Conflicting declarations` | Duplicate definitions | Remove duplicate or rename |+| `Could not resolve: group:artifact:version` | Missing repository or wrong version | Add repository or fix version |+| `Execution failed for task ':detekt'` | Code style violations | Fix detekt findings |++## Gradle Troubleshooting++```bash+# Check dependency tree for conflicts+./gradlew dependencies --configuration runtimeClasspath++# Force refresh dependencies+./gradlew build --refresh-dependencies++# Clear project-local Gradle build cache+./gradlew clean && rm -rf .gradle/build-cache/++# Check Gradle version compatibility+./gradlew --version++# Run with debug output+./gradlew build --debug 2>&1 | tail -50++# Check for dependency conflicts+./gradlew dependencyInsight --dependency <name> --configuration runtimeClasspath+```++## Kotlin Compiler Flags++```kotlin+// build.gradle.kts - Common compiler options+kotlin {+ compilerOptions {+ freeCompilerArgs.add("-Xjsr305=strict") // Strict Java null safety+ allWarningsAsErrors = true+ }+}+```++## Key Principles++- **Surgical fixes only** -- don't refactor, just fix the error+- **Never** suppress warnings without explicit approval+- **Never** change function signatures unless necessary+- **Always** run `./gradlew build` after each fix to verify+- Fix root cause over suppressing symptoms+- Prefer adding missing imports over wildcard imports++## Stop Conditions++Stop and report if:+- Same error persists after 3 fix attempts+- Fix introduces more errors than it resolves+- Error requires architectural changes beyond scope+- Missing external dependencies that need user decision++## Output Format++```text+[FIXED] src/main/kotlin/com/example/service/UserService.kt:42+Error: Unresolved reference: UserRepository+Fix: Added import com.example.repository.UserRepository+Remaining errors: 2+```++Final: `Build Status: SUCCESS/FAILED | Errors Fixed: N | Files Modified: list`++For detailed Kotlin patterns and code examples, see `skill: kotlin-patterns`.diff --git a/commands/kotlin-build.md b/commands/kotlin-build.mdnew file mode 100644index 000000000..bb9f5de1f--- /dev/null+++ b/commands/kotlin-build.md@@ -0,0 +1,172 @@+---+description: Fix Kotlin/Gradle build errors, compiler warnings, and dependency issues incrementally. Invokes the kotlin-build-resolver agent for minimal, surgical fixes.+---++# Kotlin Build and Fix++This command invokes the **kotlin-build-resolver** agent to incrementally fix Kotlin build errors with minimal changes.++## What This Command Does++1. **Run Diagnostics**: Execute `./gradlew build`, `detekt`, `ktlintCheck`+2. **Parse Errors**: Group by file and sort by severity+3. **Fix Incrementally**: One error at a time+4. **Verify Each Fix**: Re-run build after each change+5. **Report Summary**: Show what was fixed and what remains++## When to Use++Use `/kotlin-build` when:+- `./gradlew build` fails with errors+- Kotlin compiler reports errors+- `./gradlew detekt` reports violations+- Gradle dependency resolution fails+- After pulling changes that break the build++## Diagnostic Commands Run++```bash+# Primary build check+./gradlew build++# Static analysis+./gradlew detekt+./gradlew ktlintCheck++# Dependency issues+./gradlew dependencies --configuration runtimeClasspath+./gradlew build --refresh-dependencies+```++## Example Session++````text+User: /kotlin-build++Agent:+# Kotlin Build Resolution++## Initial Diagnostics++```bash+$ ./gradlew build+e: src/main/kotlin/com/example/service/UserService.kt:25:15 Unresolved reference: UserRepository+e: src/main/kotlin/com/example/routes/UserRoutes.kt:42:9 Type mismatch: inferred type is String but Int was expected+e: src/main/kotlin/com/example/routes/UserRoutes.kt:58:5 'when' expression must be exhaustive+```++Errors found: 3++## Fix 1: Unresolved Reference++File: src/main/kotlin/com/example/service/UserService.kt:25+Error: Unresolved reference: UserRepository+Cause: Missing import++```kotlin+// Added import+import com.example.repository.UserRepository+```++```bash+$ ./gradlew build+# 2 errors remaining+```++## Fix 2: Type Mismatch++File: src/main/kotlin/com/example/routes/UserRoutes.kt:42+Error: Type mismatch: inferred type is String but Int was expected++```kotlin+// Changed+val count = call.parameters["count"]+// To+val count = call.parameters["count"]?.toIntOrNull()+ ?: return@get call.respond(HttpStatusCode.BadRequest, "Invalid count")+```++```bash+$ ./gradlew build+# 1 error remaining+```++## Fix 3: Non-Exhaustive When++File: src/main/kotlin/com/example/routes/UserRoutes.kt:58+Error: 'when' expression must be exhaustive++```kotlin+// Added missing branch+when (user.role) {+ Role.ADMIN -> handleAdmin(user)+ Role.USER -> handleUser(user)+ Role.MODERATOR -> handleModerator(user) // Added+}+```++```bash+$ ./gradlew build+# Build successful!+```++## Final Verification++```bash+$ ./gradlew detekt+# No issues++$ ./gradlew test+# All tests passed+```++## Summary++| Metric | Count |+|--------|-------|+| Build errors fixed | 3 |+| Detekt issues fixed | 0 |+| Files modified | 2 |+| Remaining issues | 0 |++Build Status: ✅ SUCCESS+````++## Common Errors Fixed++| Error | Typical Fix |+|-------|-------------|+| `Unresolved reference: X` | Add import or dependency |+| `Type mismatch` | Fix type conversion or assignment |+| `'when' must be exhaustive` | Add missing sealed class branches |+| `Suspend function can only be called from coroutine` | Add `suspend` modifier |+| `Smart cast impossible` | Use local `val` or `let` |+| `None of the following candidates is applicable` | Fix argument types |+| `Could not resolve dependency` | Fix version or add repository |++## Fix Strategy++1. **Build errors first** - Code must compile+2. **Detekt violations second** - Fix code quality issues+3. **ktlint warnings third** - Fix formatting+4. **One fix at a time** - Verify each change+5. **Minimal changes** - Don't refactor, just fix++## Stop Conditions++The agent will stop and report if:+- Same error persists after 3 attempts+- Fix introduces more errors+- Requires architectural changes+- Missing external dependencies++## Related Commands++- `/kotlin-test` - Run tests after build succeeds+- `/kotlin-review` - Review code quality+- `/verify` - Full verification loop++## Related++- Agent: `agents/kotlin-build-resolver.md`+- Skill: `skills/kotlin-patterns/`diff --git a/commands/kotlin-review.md b/commands/kotlin-review.mdnew file mode 100644index 000000000..b8798bb0e--- /dev/null+++ b/commands/kotlin-review.md@@ -0,0 +1,140 @@+---+description: Comprehensive Kotlin code review for idiomatic patterns, null safety, coroutine safety, and security. Invokes the kotlin-reviewer agent.+---++# Kotlin Code Review++This command invokes the **kotlin-reviewer** agent for comprehensive Kotlin-specific code review.++## What This Command Does++1. **Identify Kotlin Changes**: Find modified `.kt` and `.kts` files via `git diff`+2. **Run Build & Static Analysis**: Execute `./gradlew build`, `detekt`, `ktlintCheck`+3. **Security Scan**: Check for SQL injection, command injection, hardcoded secrets+4. **Null Safety Review**: Analyze `!!` usage, platform type handling, unsafe casts+5. **Coroutine Review**: Check structured concurrency, dispatcher usage, cancellation+6. **Generate Report**: Categorize issues by severity++## When to Use++Use `/kotlin-review` when:+- After writing or modifying Kotlin code+- Before committing Kotlin changes+- Reviewing pull requests with Kotlin code+- Onboarding to a new Kotlin codebase+- Learning idiomatic Kotlin patterns++## Review Categories++### CRITICAL (Must Fix)+- SQL/Command injection vulnerabilities+- Force-unwrap `!!` without justification+- Platform type null safety violations+- GlobalScope usage (structured concurrency violation)+- Hardcoded credentials+- Unsafe deserialization++### HIGH (Should Fix)+- Mutable state where immutable suffices+- Blocking calls inside coroutine context+- Missing cancellation checks in long loops+- Non-exhaustive `when` on sealed types+- Large functions (>50 lines)+- Deep nesting (>4 levels)++### MEDIUM (Consider)+- Non-idiomatic Kotlin (Java-style patterns)+- Missing trailing commas+- Scope function misuse or nesting+- Missing sequence for large collection chains+- Redundant explicit types++## Automated Checks Run++```bash+# Build check+./gradlew build++# Static analysis+./gradlew detekt++# Formatting check+./gradlew ktlintCheck++# Tests+./gradlew test+```++## Example Usage++````text+User: /kotlin-review++Agent:+# Kotlin Code Review Report++## Files Reviewed+- src/main/kotlin/com/example/service/UserService.kt (modified)+- src/main/kotlin/com/example/routes/UserRoutes.kt (modified)++## Static Analysis Results+✓ Build: Successful+✓ detekt: No issues+⚠ ktlint: 2 formatting warnings++## Issues Found++[CRITICAL] Force-Unwrap Null Safety+File: src/main/kotlin/com/example/service/UserService.kt:28+Issue: Using !! on nullable repository result+```kotlin+val user = repository.findById(id)!! // NPE risk+```+Fix: Use safe call with error handling+```kotlin+val user = repository.findById(id)+ ?: throw UserNotFoundException("User $id not found")+```++[HIGH] GlobalScope Usage+File: src/main/kotlin/com/example/routes/UserRoutes.kt:45+Issue: Using GlobalScope breaks structured concurrency+```kotlin+GlobalScope.launch {+ notificationService.sendWelcome(user)+}+```+Fix: Use the call's coroutine scope+```kotlin+launch {+ notificationService.sendWelcome(user)+}+```++## Summary+- CRITICAL: 1+- HIGH: 1+- MEDIUM: 0++Recommendation: ❌ Block merge until CRITICAL issue is fixed+````++## Approval Criteria++| Status | Condition |+|--------|-----------|+| ✅ Approve | No CRITICAL or HIGH issues |+| ⚠️ Warning | Only MEDIUM issues (merge with caution) |+| ❌ Block | CRITICAL or HIGH issues found |++## Integration with Other Commands++- Use `/kotlin-test` first to ensure tests pass+- Use `/kotlin-build` if build errors occur+- Use `/kotlin-review` before committing+- Use `/code-review` for non-Kotlin-specific concerns++## Related++- Agent: `agents/kotlin-reviewer.md`+- Skills: `skills/kotlin-patterns/`, `skills/kotlin-testing/`diff --git a/commands/kotlin-test.md b/commands/kotlin-test.mdnew file mode 100644index 000000000..bdfc7a772--- /dev/null+++ b/commands/kotlin-test.md@@ -0,0 +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 = "[email protected]",+ password = "SecureP@ss1",+ )++ val result = validateRegistration(request)++ result.shouldBeInstanceOf<ValidationResult.Valid>()+ }++ test("blank name returns Invalid") {+ val request = RegistrationRequest(+ name = "",+ email = "[email protected]",+ 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 = "[email protected]",+ 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/`diff --git a/rules/kotlin/hooks.md b/rules/kotlin/hooks.mdnew file mode 100644index 000000000..28bb02fc2--- /dev/null+++ b/rules/kotlin/hooks.md@@ -0,0 +1,17 @@+---+paths:+ - "**/*.kt"+ - "**/*.kts"+ - "**/build.gradle.kts"+---+# Kotlin Hooks++> This file extends [common/hooks.md](../common/hooks.md) with Kotlin-specific content.++## PostToolUse Hooks++Configure in `~/.claude/settings.json`:++- **ktfmt/ktlint**: Auto-format `.kt` and `.kts` files after edit+- **detekt**: Run static analysis after editing Kotlin files+- **./gradlew build**: Verify compilation after changesdiff --git a/skills/kotlin-exposed-patterns/SKILL.md b/skills/kotlin-exposed-patterns/SKILL.mdnew file mode 100644index 000000000..3f98ebd57--- /dev/null+++ b/skills/kotlin-exposed-patterns/SKILL.md@@ -0,0 +1,719 @@+---+name: kotlin-exposed-patterns+description: JetBrains Exposed ORM patterns including DSL queries, DAO pattern, transactions, HikariCP connection pooling, Flyway migrations, and repository pattern.+origin: ECC+---++# Kotlin Exposed Patterns++Comprehensive patterns for database access with JetBrains Exposed ORM, including DSL queries, DAO, transactions, and production-ready configuration.++## When to Use++- Setting up database access with Exposed+- Writing SQL queries using Exposed DSL or DAO+- Configuring connection pooling with HikariCP+- Creating database migrations with Flyway+- Implementing the repository pattern with Exposed+- Handling JSON columns and complex queries++## How It Works++Exposed provides two query styles: DSL for direct SQL-like expressions and DAO for entity lifecycle management. HikariCP manages a pool of reusable database connections configured via `HikariConfig`. Flyway runs versioned SQL migration scripts at startup to keep the schema in sync. All database operations run inside `newSuspendedTransaction` blocks for coroutine safety and atomicity. The repository pattern wraps Exposed queries behind an interface so business logic stays decoupled from the data layer and tests can use an in-memory H2 database.++## Examples++### DSL Query++```kotlin+suspend fun findUserById(id: UUID): UserRow? =+ newSuspendedTransaction {+ UsersTable.selectAll()+ .where { UsersTable.id eq id }+ .map { it.toUser() }+ .singleOrNull()+ }+```++### DAO Entity Usage++```kotlin+suspend fun createUser(request: CreateUserRequest): User =+ newSuspendedTransaction {+ UserEntity.new {+ name = request.name+ email = request.email+ role = request.role+ }.toModel()+ }+```++### HikariCP Configuration++```kotlin+val hikariConfig = HikariConfig().apply {+ driverClassName = config.driver+ jdbcUrl = config.url+ username = config.username+ password = config.password+ maximumPoolSize = config.maxPoolSize+ isAutoCommit = false+ transactionIsolation = "TRANSACTION_READ_COMMITTED"+ validate()+}+```++## Database Setup++### HikariCP Connection Pooling++```kotlin+// DatabaseFactory.kt+object DatabaseFactory {+ fun create(config: DatabaseConfig): Database {+ val hikariConfig = HikariConfig().apply {+ driverClassName = config.driver+ jdbcUrl = config.url+ username = config.username+ password = config.password+ maximumPoolSize = config.maxPoolSize+ isAutoCommit = false+ transactionIsolation = "TRANSACTION_READ_COMMITTED"+ validate()+ }++ return Database.connect(HikariDataSource(hikariConfig))+ }+}++data class DatabaseConfig(+ val url: String,+ val driver: String = "org.postgresql.Driver",+ val username: String = "",+ val password: String = "",+ val maxPoolSize: Int = 10,+)+```++### Flyway Migrations++```kotlin+// FlywayMigration.kt+fun runMigrations(config: DatabaseConfig) {+ Flyway.configure()+ .dataSource(config.url, config.username, config.password)+ .locations("classpath:db/migration")+ .baselineOnMigrate(true)+ .load()+ .migrate()+}++// Application startup+fun Application.module() {+ val config = DatabaseConfig(+ url = environment.config.property("database.url").getString(),+ username = environment.config.property("database.username").getString(),+ password = environment.config.property("database.password").getString(),+ )+ runMigrations(config)+ val database = DatabaseFactory.create(config)+ // ...+}+```++### Migration Files++```sql+-- src/main/resources/db/migration/V1__create_users.sql+CREATE TABLE users (+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),+ name VARCHAR(100) NOT NULL,+ email VARCHAR(255) NOT NULL UNIQUE,+ role VARCHAR(20) NOT NULL DEFAULT 'USER',+ metadata JSONB,+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()+);++CREATE INDEX idx_users_email ON users(email);+CREATE INDEX idx_users_role ON users(role);+```++## Table Definitions++### DSL Style Tables++```kotlin+// tables/UsersTable.kt+object UsersTable : UUIDTable("users") {+ val name = varchar("name", 100)+ val email = varchar("email", 255).uniqueIndex()+ val role = enumerationByName<Role>("role", 20)+ val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()+ val createdAt = timestampWithTimeZone("created_at").defaultExpression(CurrentTimestampWithTimeZone)+ val updatedAt = timestampWithTimeZone("updated_at").defaultExpression(CurrentTimestampWithTimeZone)+}++object OrdersTable : UUIDTable("orders") {+ val userId = uuid("user_id").references(UsersTable.id)+ val status = enumerationByName<OrderStatus>("status", 20)+ val totalAmount = long("total_amount")+ val currency = varchar("currency", 3)+ val createdAt = timestampWithTimeZone("created_at").defaultExpression(CurrentTimestampWithTimeZone)+}++object OrderItemsTable : UUIDTable("order_items") {+ val orderId = uuid("order_id").references(OrdersTable.id, onDelete = ReferenceOption.CASCADE)+ val productId = uuid("product_id")+ val quantity = integer("quantity")+ val unitPrice = long("unit_price")+}+```++### Composite Tables++```kotlin+object UserRolesTable : Table("user_roles") {+ val userId = uuid("user_id").references(UsersTable.id, onDelete = ReferenceOption.CASCADE)+ val roleId = uuid("role_id").references(RolesTable.id, onDelete = ReferenceOption.CASCADE)+ override val primaryKey = PrimaryKey(userId, roleId)+}+```++## DSL Queries++### Basic CRUD++```kotlin+// Insert+suspend fun insertUser(name: String, email: String, role: Role): UUID =+ newSuspendedTransaction {+ UsersTable.insertAndGetId {+ it[UsersTable.name] = name+ it[UsersTable.email] = email+ it[UsersTable.role] = role+ }.value+ }++// Select by ID+suspend fun findUserById(id: UUID): UserRow? =+ newSuspendedTransaction {+ UsersTable.selectAll()+ .where { UsersTable.id eq id }+ .map { it.toUser() }+ .singleOrNull()+ }++// Select with conditions+suspend fun findActiveAdmins(): List<UserRow> =+ newSuspendedTransaction {+ UsersTable.selectAll()+ .where { (UsersTable.role eq Role.ADMIN) }+ .orderBy(UsersTable.name)+ .map { it.toUser() }+ }++// Update+suspend fun updateUserEmail(id: UUID, newEmail: String): Boolean =+ newSuspendedTransaction {+ UsersTable.update({ UsersTable.id eq id }) {+ it[email] = newEmail+ it[updatedAt] = CurrentTimestampWithTimeZone+ } > 0+ }++// Delete+suspend fun deleteUser(id: UUID): Boolean =+ newSuspendedTransaction {+ UsersTable.deleteWhere { UsersTable.id eq id } > 0+ }++// Row mapping+private fun ResultRow.toUser() = UserRow(+ id = this[UsersTable.id].value,+ name = this[UsersTable.name],+ email = this[UsersTable.email],+ role = this[UsersTable.role],+ metadata = this[UsersTable.metadata],+ createdAt = this[UsersTable.createdAt],+ updatedAt = this[UsersTable.updatedAt],+)+```++### Advanced Queries++```kotlin+// Join queries+suspend fun findOrdersWithUser(userId: UUID): List<OrderWithUser> =+ newSuspendedTransaction {+ (OrdersTable innerJoin UsersTable)+ .selectAll()+ .where { OrdersTable.userId eq userId }+ .orderBy(OrdersTable.createdAt, SortOrder.DESC)+ .map { row ->+ OrderWithUser(+ orderId = row[OrdersTable.id].value,+ status = row[OrdersTable.status],+ totalAmount = row[OrdersTable.totalAmount],+ userName = row[UsersTable.name],+ )+ }+ }++// Aggregation+suspend fun countUsersByRole(): Map<Role, Long> =+ newSuspendedTransaction {+ UsersTable+ .select(UsersTable.role, UsersTable.id.count())+ .groupBy(UsersTable.role)+ .associate { row ->+ row[UsersTable.role] to row[UsersTable.id.count()]+ }+ }++// Subqueries+suspend fun findUsersWithOrders(): List<UserRow> =+ newSuspendedTransaction {+ UsersTable.selectAll()+ .where {+ UsersTable.id inSubQuery+ OrdersTable.select(OrdersTable.userId).withDistinct()+ }+ .map { it.toUser() }+ }++// LIKE and pattern matching — always escape user input to prevent wildcard injection+private fun escapeLikePattern(input: String): String =+ input.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")++suspend fun searchUsers(query: String): List<UserRow> =+ newSuspendedTransaction {+ val sanitized = escapeLikePattern(query.lowercase())+ UsersTable.selectAll()+ .where {+ (UsersTable.name.lowerCase() like "%${sanitized}%") or+ (UsersTable.email.lowerCase() like "%${sanitized}%")+ }+ .map { it.toUser() }+ }+```++### Pagination++```kotlin+data class Page<T>(+ val data: List<T>,+ val total: Long,+ val page: Int,+ val limit: Int,+) {+ val totalPages: Int get() = ((total + limit - 1) / limit).toInt()+ val hasNext: Boolean get() = page < totalPages+ val hasPrevious: Boolean get() = page > 1+}++suspend fun findUsersPaginated(page: Int, limit: Int): Page<UserRow> =+ newSuspendedTransaction {+ val total = UsersTable.selectAll().count()+ val data = UsersTable.selectAll()+ .orderBy(UsersTable.createdAt, SortOrder.DESC)+ .limit(limit)+ .offset(((page - 1) * limit).toLong())+ .map { it.toUser() }++ Page(data = data, total = total, page = page, limit = limit)+ }+```++### Batch Operations++```kotlin+// Batch insert+suspend fun insertUsers(users: List<CreateUserRequest>): List<UUID> =+ newSuspendedTransaction {+ UsersTable.batchInsert(users) { user ->+ this[UsersTable.name] = user.name+ this[UsersTable.email] = user.email+ this[UsersTable.role] = user.role+ }.map { it[UsersTable.id].value }+ }++// Upsert (insert or update on conflict)+suspend fun upsertUser(id: UUID, name: String, email: String) {+ newSuspendedTransaction {+ UsersTable.upsert(UsersTable.email) {+ it[UsersTable.id] = EntityID(id, UsersTable)+ it[UsersTable.name] = name+ it[UsersTable.email] = email+ it[updatedAt] = CurrentTimestampWithTimeZone+ }+ }+}+```++## DAO Pattern++### Entity Definitions++```kotlin+// entities/UserEntity.kt+class UserEntity(id: EntityID<UUID>) : UUIDEntity(id) {+ companion object : UUIDEntityClass<UserEntity>(UsersTable)++ var name by UsersTable.name+ var email by UsersTable.email+ var role by UsersTable.role+ var metadata by UsersTable.metadata+ var createdAt by UsersTable.createdAt+ var updatedAt by UsersTable.updatedAt++ val orders by OrderEntity referrersOn OrdersTable.userId++ fun toModel(): User = User(+ id = id.value,+ name = name,+ email = email,+ role = role,+ metadata = metadata,+ createdAt = createdAt,+ updatedAt = updatedAt,+ )+}++class OrderEntity(id: EntityID<UUID>) : UUIDEntity(id) {+ companion object : UUIDEntityClass<OrderEntity>(OrdersTable)++ var user by UserEntity referencedOn OrdersTable.userId+ var status by OrdersTable.status+ var totalAmount by OrdersTable.totalAmount+ var currency by OrdersTable.currency+ var createdAt by OrdersTable.createdAt++ val items by OrderItemEntity referrersOn OrderItemsTable.orderId+}+```++### DAO Operations++```kotlin+suspend fun findUserByEmail(email: String): User? =+ newSuspendedTransaction {+ UserEntity.find { UsersTable.email eq email }+ .firstOrNull()+ ?.toModel()+ }++suspend fun createUser(request: CreateUserRequest): User =+ newSuspendedTransaction {+ UserEntity.new {+ name = request.name+ email = request.email+ role = request.role+ }.toModel()+ }++suspend fun updateUser(id: UUID, request: UpdateUserRequest): User? =+ newSuspendedTransaction {+ UserEntity.findById(id)?.apply {+ request.name?.let { name = it }+ request.email?.let { email = it }+ updatedAt = OffsetDateTime.now(ZoneOffset.UTC)+ }?.toModel()+ }+```++## Transactions++### Suspend Transaction Support++```kotlin+// Good: Use newSuspendedTransaction for coroutine support+suspend fun performDatabaseOperation(): Result<User> =+ runCatching {+ newSuspendedTransaction {+ val user = UserEntity.new {+ name = "Alice"+ email = "[email protected]"+ }+ // All operations in this block are atomic+ user.toModel()+ }+ }++// Good: Nested transactions with savepoints+suspend fun transferFunds(fromId: UUID, toId: UUID, amount: Long) {+ newSuspendedTransaction {+ val from = UserEntity.findById(fromId) ?: throw NotFoundException("User $fromId not found")+ val to = UserEntity.findById(toId) ?: throw NotFoundException("User $toId not found")++ // Debit+ from.balance -= amount+ // Credit+ to.balance += amount++ // Both succeed or both fail+ }+}+```++### Transaction Isolation++```kotlin+suspend fun readCommittedQuery(): List<User> =+ newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_READ_COMMITTED) {+ UserEntity.all().map { it.toModel() }+ }++suspend fun serializableOperation() {+ newSuspendedTransaction(transactionIsolation = Connection.TRANSACTION_SERIALIZABLE) {+ // Strictest isolation level for critical operations+ }+}+```++## Repository Pattern++### Interface Definition++```kotlin+interface UserRepository {+ suspend fun findById(id: UUID): User?+ suspend fun findByEmail(email: String): User?+ suspend fun findAll(page: Int, limit: Int): Page<User>+ suspend fun search(query: String): List<User>+ suspend fun create(request: CreateUserRequest): User+ suspend fun update(id: UUID, request: UpdateUserRequest): User?+ suspend fun delete(id: UUID): Boolean+ suspend fun count(): Long+}+```++### Exposed Implementation++```kotlin+class ExposedUserRepository(+ private val database: Database,+) : UserRepository {++ override suspend fun findById(id: UUID): User? =+ newSuspendedTransaction(db = database) {+ UsersTable.selectAll()+ .where { UsersTable.id eq id }+ .map { it.toUser() }+ .singleOrNull()+ }++ override suspend fun findByEmail(email: String): User? =+ newSuspendedTransaction(db = database) {+ UsersTable.selectAll()+ .where { UsersTable.email eq email }+ .map { it.toUser() }+ .singleOrNull()+ }++ override suspend fun findAll(page: Int, limit: Int): Page<User> =+ newSuspendedTransaction(db = database) {+ val total = UsersTable.selectAll().count()+ val data = UsersTable.selectAll()+ .orderBy(UsersTable.createdAt, SortOrder.DESC)+ .limit(limit)+ .offset(((page - 1) * limit).toLong())+ .map { it.toUser() }+ Page(data = data, total = total, page = page, limit = limit)+ }++ override suspend fun search(query: String): List<User> =+ newSuspendedTransaction(db = database) {+ val sanitized = escapeLikePattern(query.lowercase())+ UsersTable.selectAll()+ .where {+ (UsersTable.name.lowerCase() like "%${sanitized}%") or+ (UsersTable.email.lowerCase() like "%${sanitized}%")+ }+ .orderBy(UsersTable.name)+ .map { it.toUser() }+ }++ override suspend fun create(request: CreateUserRequest): User =+ newSuspendedTransaction(db = database) {+ UsersTable.insert {+ it[name] = request.name+ it[email] = request.email+ it[role] = request.role+ }.resultedValues!!.first().toUser()+ }++ override suspend fun update(id: UUID, request: UpdateUserRequest): User? =+ newSuspendedTransaction(db = database) {+ val updated = UsersTable.update({ UsersTable.id eq id }) {+ request.name?.let { name -> it[UsersTable.name] = name }+ request.email?.let { email -> it[UsersTable.email] = email }+ it[updatedAt] = CurrentTimestampWithTimeZone+ }+ if (updated > 0) findById(id) else null+ }++ override suspend fun delete(id: UUID): Boolean =+ newSuspendedTransaction(db = database) {+ UsersTable.deleteWhere { UsersTable.id eq id } > 0+ }++ override suspend fun count(): Long =+ newSuspendedTransaction(db = database) {+ UsersTable.selectAll().count()+ }++ private fun ResultRow.toUser() = User(+ id = this[UsersTable.id].value,+ name = this[UsersTable.name],+ email = this[UsersTable.email],+ role = this[UsersTable.role],+ metadata = this[UsersTable.metadata],+ createdAt = this[UsersTable.createdAt],+ updatedAt = this[UsersTable.updatedAt],+ )+}+```++## JSON Columns++### JSONB with kotlinx.serialization++```kotlin+// Custom column type for JSONB+inline fun <reified T : Any> Table.jsonb(+ name: String,+ json: Json,+): Column<T> = registerColumn(name, object : ColumnType<T>() {+ override fun sqlType() = "JSONB"++ override fun valueFromDB(value: Any): T = when (value) {+ is String -> json.decodeFromString(value)+ is PGobject -> {+ val jsonString = value.value+ ?: throw IllegalArgumentException("PGobject value is null for column '$name'")+ json.decodeFromString(jsonString)+ }+ else -> throw IllegalArgumentException("Unexpected value: $value")+ }++ override fun notNullValueToDB(value: T): Any =+ PGobject().apply {+ type = "jsonb"+ this.value = json.encodeToString(value)+ }+})++// Usage in table+@Serializable+data class UserMetadata(+ val preferences: Map<String, String> = emptyMap(),+ val tags: List<String> = emptyList(),+)++object UsersTable : UUIDTable("users") {+ val metadata = jsonb<UserMetadata>("metadata", Json.Default).nullable()+}+```++## Testing with Exposed++### In-Memory Database for Tests++```kotlin+class UserRepositoryTest : FunSpec({+ lateinit var database: Database+ lateinit var repository: UserRepository++ beforeSpec {+ database = Database.connect(+ url = "jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;MODE=PostgreSQL",+ driver = "org.h2.Driver",+ )+ transaction(database) {+ SchemaUtils.create(UsersTable)+ }+ repository = ExposedUserRepository(database)+ }++ beforeTest {+ transaction(database) {+ UsersTable.deleteAll()+ }+ }++ test("create and find user") {+ val user = repository.create(CreateUserRequest("Alice", "[email protected]"))++ user.name shouldBe "Alice"+ user.email shouldBe "[email protected]"++ val found = repository.findById(user.id)+ found shouldBe user+ }++ test("findByEmail returns null for unknown email") {+ val result = repository.findByEmail("[email protected]")+ result.shouldBeNull()+ }++ test("pagination works correctly") {+ repeat(25) { i ->+ repository.create(CreateUserRequest("User $i", "[email protected]"))+ }++ val page1 = repository.findAll(page = 1, limit = 10)+ page1.data shouldHaveSize 10+ page1.total shouldBe 25+ page1.hasNext shouldBe true++ val page3 = repository.findAll(page = 3, limit = 10)+ page3.data shouldHaveSize 5+ page3.hasNext shouldBe false+ }+})+```++## Gradle Dependencies++```kotlin+// build.gradle.kts+dependencies {+ // Exposed+ implementation("org.jetbrains.exposed:exposed-core:1.0.0")+ implementation("org.jetbrains.exposed:exposed-dao:1.0.0")+ implementation("org.jetbrains.exposed:exposed-jdbc:1.0.0")+ implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.0.0")+ implementation("org.jetbrains.exposed:exposed-json:1.0.0")++ // Database driver+ implementation("org.postgresql:postgresql:42.7.5")++ // Connection pooling+ implementation("com.zaxxer:HikariCP:6.2.1")++ // Migrations+ implementation("org.flywaydb:flyway-core:10.22.0")+ implementation("org.flywaydb:flyway-database-postgresql:10.22.0")++ // Testing+ testImplementation("com.h2database:h2:2.3.232")+}+```++## Quick Reference: Exposed Patterns++| Pattern | Description |+|---------|-------------|+| `object Table : UUIDTable("name")` | Define table with UUID primary key |+| `newSuspendedTransaction { }` | Coroutine-safe transaction block |+| `Table.selectAll().where { }` | Query with conditions |+| `Table.insertAndGetId { }` | Insert and return generated ID |+| `Table.update({ condition }) { }` | Update matching rows |+| `Table.deleteWhere { }` | Delete matching rows |+| `Table.batchInsert(items) { }` | Efficient bulk insert |+| `innerJoin` / `leftJoin` | Join tables |+| `orderBy` / `limit` / `offset` | Sort and paginate |+| `count()` / `sum()` / `avg()` | Aggregation functions |++**Remember**: Use the DSL style for simple queries and the DAO style when you need entity lifecycle management. Always use `newSuspendedTransaction` for coroutine support, and wrap database operations behind a repository interface for testability.diff --git a/skills/kotlin-ktor-patterns/SKILL.md b/skills/kotlin-ktor-patterns/SKILL.mdnew file mode 100644index 000000000..10c9522f8--- /dev/null+++ b/skills/kotlin-ktor-patterns/SKILL.md@@ -0,0 +1,689 @@+---+name: kotlin-ktor-patterns+description: Ktor server patterns including routing DSL, plugins, authentication, Koin DI, kotlinx.serialization, WebSockets, and testApplication testing.+origin: ECC+---++# Ktor Server Patterns++Comprehensive Ktor patterns for building robust, maintainable HTTP servers with Kotlin coroutines.++## When to Activate++- Building Ktor HTTP servers+- Configuring Ktor plugins (Auth, CORS, ContentNegotiation, StatusPages)+- Implementing REST APIs with Ktor+- Setting up dependency injection with Koin+- Writing Ktor integration tests with testApplication+- Working with WebSockets in Ktor++## Application Structure++### Standard Ktor Project Layout++```text+src/main/kotlin/+├── com/example/+│ ├── Application.kt # Entry point, module configuration+│ ├── plugins/+│ │ ├── Routing.kt # Route definitions+│ │ ├── Serialization.kt # Content negotiation setup+│ │ ├── Authentication.kt # Auth configuration+│ │ ├── StatusPages.kt # Error handling+│ │ └── CORS.kt # CORS configuration+│ ├── routes/+│ │ ├── UserRoutes.kt # /users endpoints+│ │ ├── AuthRoutes.kt # /auth endpoints+│ │ └── HealthRoutes.kt # /health endpoints+│ ├── models/+│ │ ├── User.kt # Domain models+│ │ └── ApiResponse.kt # Response envelopes+│ ├── services/+│ │ ├── UserService.kt # Business logic+│ │ └── AuthService.kt # Auth logic+│ ├── repositories/+│ │ ├── UserRepository.kt # Data access interface+│ │ └── ExposedUserRepository.kt+│ └── di/+│ └── AppModule.kt # Koin modules+src/test/kotlin/+├── com/example/+│ ├── routes/+│ │ └── UserRoutesTest.kt+│ └── services/+│ └── UserServiceTest.kt+```++### Application Entry Point++```kotlin+// Application.kt+fun main() {+ embeddedServer(Netty, port = 8080, module = Application::module).start(wait = true)+}++fun Application.module() {+ configureSerialization()+ configureAuthentication()+ configureStatusPages()+ configureCORS()+ configureDI()+ configureRouting()+}+```++## Routing DSL++### Basic Routes++```kotlin+// plugins/Routing.kt+fun Application.configureRouting() {+ routing {+ userRoutes()+ authRoutes()+ healthRoutes()+ }+}++// routes/UserRoutes.kt+fun Route.userRoutes() {+ val userService by inject<UserService>()++ route("/users") {+ get {+ val users = userService.getAll()+ call.respond(users)+ }++ get("/{id}") {+ val id = call.parameters["id"]+ ?: return@get call.respond(HttpStatusCode.BadRequest, "Missing id")+ val user = userService.getById(id)+ ?: return@get call.respond(HttpStatusCode.NotFound)+ call.respond(user)+ }++ post {+ val request = call.receive<CreateUserRequest>()+ val user = userService.create(request)+ call.respond(HttpStatusCode.Created, user)+ }++ put("/{id}") {+ val id = call.parameters["id"]+ ?: return@put call.respond(HttpStatusCode.BadRequest, "Missing id")+ val request = call.receive<UpdateUserRequest>()+ val user = userService.update(id, request)+ ?: return@put call.respond(HttpStatusCode.NotFound)+ call.respond(user)+ }++ delete("/{id}") {+ val id = call.parameters["id"]+ ?: return@delete call.respond(HttpStatusCode.BadRequest, "Missing id")+ val deleted = userService.delete(id)+ if (deleted) call.respond(HttpStatusCode.NoContent)+ else call.respond(HttpStatusCode.NotFound)+ }+ }+}+```++### Route Organization with Authenticated Routes++```kotlin+fun Route.userRoutes() {+ route("/users") {+ // Public routes+ get { /* list users */ }+ get("/{id}") { /* get user */ }++ // Protected routes+ authenticate("jwt") {+ post { /* create user - requires auth */ }+ put("/{id}") { /* update user - requires auth */ }+ delete("/{id}") { /* delete user - requires auth */ }+ }+ }+}+```++## Content Negotiation & Serialization++### kotlinx.serialization Setup++```kotlin+// plugins/Serialization.kt+fun Application.configureSerialization() {+ install(ContentNegotiation) {+ json(Json {+ prettyPrint = true+ isLenient = false+ ignoreUnknownKeys = true+ encodeDefaults = true+ explicitNulls = false+ })+ }+}+```++### Serializable Models++```kotlin+@Serializable+data class UserResponse(+ val id: String,+ val name: String,+ val email: String,+ val role: Role,+ @Serializable(with = InstantSerializer::class)+ val createdAt: Instant,+)++@Serializable+data class CreateUserRequest(+ val name: String,+ val email: String,+ val role: Role = Role.USER,+)++@Serializable+data class ApiResponse<T>(+ val success: Boolean,+ val data: T? = null,+ val error: String? = null,+) {+ companion object {+ fun <T> ok(data: T): ApiResponse<T> = ApiResponse(success = true, data = data)+ fun <T> error(message: String): ApiResponse<T> = ApiResponse(success = false, error = message)+ }+}++@Serializable+data class PaginatedResponse<T>(+ val data: List<T>,+ val total: Long,+ val page: Int,+ val limit: Int,+)+```++### Custom Serializers++```kotlin+object InstantSerializer : KSerializer<Instant> {+ override val descriptor = PrimitiveSerialDescriptor("Instant", PrimitiveKind.STRING)+ override fun serialize(encoder: Encoder, value: Instant) =+ encoder.encodeString(value.toString())+ override fun deserialize(decoder: Decoder): Instant =+ Instant.parse(decoder.decodeString())+}+```++## Authentication++### JWT Authentication++```kotlin+// plugins/Authentication.kt+fun Application.configureAuthentication() {+ val jwtSecret = environment.config.property("jwt.secret").getString()+ val jwtIssuer = environment.config.property("jwt.issuer").getString()+ val jwtAudience = environment.config.property("jwt.audience").getString()+ val jwtRealm = environment.config.property("jwt.realm").getString()++ install(Authentication) {+ jwt("jwt") {+ realm = jwtRealm+ verifier(+ JWT.require(Algorithm.HMAC256(jwtSecret))+ .withAudience(jwtAudience)+ .withIssuer(jwtIssuer)+ .build()+ )+ validate { credential ->+ if (credential.payload.audience.contains(jwtAudience)) {+ JWTPrincipal(credential.payload)+ } else {+ null+ }+ }+ challenge { _, _ ->+ call.respond(HttpStatusCode.Unauthorized, ApiResponse.error<Unit>("Invalid or expired token"))+ }+ }+ }+}++// Extracting user from JWT+fun ApplicationCall.userId(): String =+ principal<JWTPrincipal>()+ ?.payload+ ?.getClaim("userId")+ ?.asString()+ ?: throw AuthenticationException("No userId in token")+```++### Auth Routes++```kotlin+fun Route.authRoutes() {+ val authService by inject<AuthService>()++ route("/auth") {+ post("/login") {+ val request = call.receive<LoginRequest>()+ val token = authService.login(request.email, request.password)+ ?: return@post call.respond(+ HttpStatusCode.Unauthorized,+ ApiResponse.error<Unit>("Invalid credentials"),+ )+ call.respond(ApiResponse.ok(TokenResponse(token)))+ }++ post("/register") {+ val request = call.receive<RegisterRequest>()+ val user = authService.register(request)+ call.respond(HttpStatusCode.Created, ApiResponse.ok(user))+ }++ authenticate("jwt") {+ get("/me") {+ val userId = call.userId()+ val user = authService.getProfile(userId)+ call.respond(ApiResponse.ok(user))+ }+ }+ }+}+```++## Status Pages (Error Handling)++```kotlin+// plugins/StatusPages.kt+fun Application.configureStatusPages() {+ install(StatusPages) {+ exception<ContentTransformationException> { call, cause ->+ call.respond(+ HttpStatusCode.BadRequest,+ ApiResponse.error<Unit>("Invalid request body: ${cause.message}"),+ )+ }++ exception<IllegalArgumentException> { call, cause ->+ call.respond(+ HttpStatusCode.BadRequest,+ ApiResponse.error<Unit>(cause.message ?: "Bad request"),+ )+ }++ exception<AuthenticationException> { call, _ ->+ call.respond(+ HttpStatusCode.Unauthorized,+ ApiResponse.error<Unit>("Authentication required"),+ )+ }++ exception<AuthorizationException> { call, _ ->+ call.respond(+ HttpStatusCode.Forbidden,+ ApiResponse.error<Unit>("Access denied"),+ )+ }++ exception<NotFoundException> { call, cause ->+ call.respond(+ HttpStatusCode.NotFound,+ ApiResponse.error<Unit>(cause.message ?: "Resource not found"),+ )+ }++ exception<Throwable> { call, cause ->+ call.application.log.error("Unhandled exception", cause)+ call.respond(+ HttpStatusCode.InternalServerError,+ ApiResponse.error<Unit>("Internal server error"),+ )+ }++ status(HttpStatusCode.NotFound) { call, status ->+ call.respond(status, ApiResponse.error<Unit>("Route not found"))+ }+ }+}+```++## CORS Configuration++```kotlin+// plugins/CORS.kt+fun Application.configureCORS() {+ install(CORS) {+ allowHost("localhost:3000")+ allowHost("example.com", schemes = listOf("https"))+ allowHeader(HttpHeaders.ContentType)+ allowHeader(HttpHeaders.Authorization)+ allowMethod(HttpMethod.Put)+ allowMethod(HttpMethod.Delete)+ allowMethod(HttpMethod.Patch)+ allowCredentials = true+ maxAgeInSeconds = 3600+ }+}+```++## Koin Dependency Injection++### Module Definition++```kotlin+// di/AppModule.kt+val appModule = module {+ // Database+ single<Database> { DatabaseFactory.create(get()) }++ // Repositories+ single<UserRepository> { ExposedUserRepository(get()) }+ single<OrderRepository> { ExposedOrderRepository(get()) }++ // Services+ single { UserService(get()) }+ single { OrderService(get(), get()) }+ single { AuthService(get(), get()) }+}++// Application setup+fun Application.configureDI() {+ install(Koin) {+ modules(appModule)+ }+}+```++### Using Koin in Routes++```kotlin+fun Route.userRoutes() {+ val userService by inject<UserService>()++ route("/users") {+ get {+ val users = userService.getAll()+ call.respond(ApiResponse.ok(users))+ }+ }+}+```++### Koin for Testing++```kotlin+class UserServiceTest : FunSpec(), KoinTest {+ override fun extensions() = listOf(KoinExtension(testModule))++ private val testModule = module {+ single<UserRepository> { mockk() }+ single { UserService(get()) }+ }++ private val repository by inject<UserRepository>()+ private val service by inject<UserService>()++ init {+ test("getUser returns user") {+ coEvery { repository.findById("1") } returns testUser+ service.getById("1") shouldBe testUser+ }+ }+}+```++## Request Validation++```kotlin+// Validate request data in routes+fun Route.userRoutes() {+ val userService by inject<UserService>()++ post("/users") {+ val request = call.receive<CreateUserRequest>()++ // Validate+ require(request.name.isNotBlank()) { "Name is required" }+ require(request.name.length <= 100) { "Name must be 100 characters or less" }+ require(request.email.matches(Regex(".+@.+\\..+"))) { "Invalid email format" }++ val user = userService.create(request)+ call.respond(HttpStatusCode.Created, ApiResponse.ok(user))+ }+}++// Or use a validation extension+fun CreateUserRequest.validate() {+ require(name.isNotBlank()) { "Name is required" }+ require(name.length <= 100) { "Name must be 100 characters or less" }+ require(email.matches(Regex(".+@.+\\..+"))) { "Invalid email format" }+}+```++## WebSockets++```kotlin+fun Application.configureWebSockets() {+ install(WebSockets) {+ pingPeriod = 15.seconds+ timeout = 15.seconds+ maxFrameSize = 64 * 1024 // 64 KiB — increase only if your protocol requires larger frames+ masking = false // Server-to-client frames are unmasked per RFC 6455; client-to-server are always masked by Ktor+ }+}++fun Route.chatRoutes() {+ val connections = Collections.synchronizedSet<Connection>(LinkedHashSet())++ webSocket("/chat") {+ val thisConnection = Connection(this)+ connections += thisConnection++ try {+ send("Connected! Users online: ${connections.size}")++ for (frame in incoming) {+ frame as? Frame.Text ?: continue+ val text = frame.readText()+ val message = ChatMessage(thisConnection.name, text)++ // Snapshot under lock to avoid ConcurrentModificationException+ val snapshot = synchronized(connections) { connections.toList() }+ snapshot.forEach { conn ->+ conn.session.send(Json.encodeToString(message))+ }+ }+ } catch (e: Exception) {+ logger.error("WebSocket error", e)+ } finally {+ connections -= thisConnection+ }+ }+}++data class Connection(val session: DefaultWebSocketSession) {+ val name: String = "User-${counter.getAndIncrement()}"++ companion object {+ private val counter = AtomicInteger(0)+ }+}+```++## testApplication Testing++### Basic Route Testing++```kotlin+class UserRoutesTest : FunSpec({+ test("GET /users returns list of users") {+ testApplication {+ application {+ install(Koin) { modules(testModule) }+ configureSerialization()+ configureRouting()+ }++ val response = client.get("/users")++ response.status shouldBe HttpStatusCode.OK+ val body = response.body<ApiResponse<List<UserResponse>>>()+ body.success shouldBe true+ body.data.shouldNotBeNull().shouldNotBeEmpty()+ }+ }++ test("POST /users creates a user") {+ testApplication {+ application {+ install(Koin) { modules(testModule) }+ configureSerialization()+ configureStatusPages()+ configureRouting()+ }++ val client = createClient {+ install(io.ktor.client.plugins.contentnegotiation.ContentNegotiation) {+ json()+ }+ }++ val response = client.post("/users") {+ contentType(ContentType.Application.Json)+ setBody(CreateUserRequest("Alice", "[email protected]"))+ }++ response.status shouldBe HttpStatusCode.Created+ }+ }++ test("GET /users/{id} returns 404 for unknown id") {+ testApplication {+ application {+ install(Koin) { modules(testModule) }+ configureSerialization()+ configureStatusPages()+ configureRouting()+ }++ val response = client.get("/users/unknown-id")++ response.status shouldBe HttpStatusCode.NotFound+ }+ }+})+```++### Testing Authenticated Routes++```kotlin+class AuthenticatedRoutesTest : FunSpec({+ test("protected route requires JWT") {+ testApplication {+ application {+ install(Koin) { modules(testModule) }+ configureSerialization()+ configureAuthentication()+ configureRouting()+ }++ val response = client.post("/users") {+ contentType(ContentType.Application.Json)+ setBody(CreateUserRequest("Alice", "[email protected]"))+ }++ response.status shouldBe HttpStatusCode.Unauthorized+ }+ }++ test("protected route succeeds with valid JWT") {+ testApplication {+ application {+ install(Koin) { modules(testModule) }+ configureSerialization()+ configureAuthentication()+ configureRouting()+ }++ val token = generateTestJWT(userId = "test-user")++ val client = createClient {+ install(io.ktor.client.plugins.contentnegotiation.ContentNegotiation) { json() }+ }++ val response = client.post("/users") {+ contentType(ContentType.Application.Json)+ bearerAuth(token)+ setBody(CreateUserRequest("Alice", "[email protected]"))+ }++ response.status shouldBe HttpStatusCode.Created+ }+ }+})+```++## Configuration++### application.yaml++```yaml+ktor:+ application:+ modules:+ - com.example.ApplicationKt.module+ deployment:+ port: 8080++jwt:+ secret: ${JWT_SECRET}+ issuer: "https://example.com"+ audience: "https://example.com/api"+ realm: "example"++database:+ url: ${DATABASE_URL}+ driver: "org.postgresql.Driver"+ maxPoolSize: 10+```++### Reading Config++```kotlin+fun Application.configureDI() {+ val dbUrl = environment.config.property("database.url").getString()+ val dbDriver = environment.config.property("database.driver").getString()+ val maxPoolSize = environment.config.property("database.maxPoolSize").getString().toInt()++ install(Koin) {+ modules(module {+ single { DatabaseConfig(dbUrl, dbDriver, maxPoolSize) }+ single { DatabaseFactory.create(get()) }+ })+ }+}+```++## Quick Reference: Ktor Patterns++| Pattern | Description |+|---------|-------------|+| `route("/path") { get { } }` | Route grouping with DSL |+| `call.receive<T>()` | Deserialize request body |+| `call.respond(status, body)` | Send response with status |+| `call.parameters["id"]` | Read path parameters |+| `call.request.queryParameters["q"]` | Read query parameters |+| `install(Plugin) { }` | Install and configure plugin |+| `authenticate("name") { }` | Protect routes with auth |+| `by inject<T>()` | Koin dependency injection |+| `testApplication { }` | Integration testing |++**Remember**: Ktor is designed around Kotlin coroutines and DSLs. Keep routes thin, push logic to services, and use Koin for dependency injection. Test with `testApplication` for full integration coverage.diff --git a/skills/kotlin-patterns/SKILL.md b/skills/kotlin-patterns/SKILL.mdnew file mode 100644index 000000000..5e75d2710--- /dev/null+++ b/skills/kotlin-patterns/SKILL.md@@ -0,0 +1,711 @@+---+name: kotlin-patterns+description: Idiomatic Kotlin patterns, best practices, and conventions for building robust, efficient, and maintainable Kotlin applications with coroutines, null safety, and DSL builders.+origin: ECC+---++# Kotlin Development Patterns++Idiomatic Kotlin patterns and best practices for building robust, efficient, and maintainable applications.++## When to Use++- Writing new Kotlin code+- Reviewing Kotlin code+- Refactoring existing Kotlin code+- Designing Kotlin modules or libraries+- Configuring Gradle Kotlin DSL builds++## How It Works++This skill enforces idiomatic Kotlin conventions across seven key areas: null safety using the type system and safe-call operators, immutability via `val` and `copy()` on data classes, sealed classes and interfaces for exhaustive type hierarchies, structured concurrency with coroutines and `Flow`, extension functions for adding behaviour without inheritance, type-safe DSL builders using `@DslMarker` and lambda receivers, and Gradle Kotlin DSL for build configuration.++## Examples++**Null safety with Elvis operator:**+```kotlin+fun getUserEmail(userId: String): String {+ val user = userRepository.findById(userId)+ return user?.email ?: "[email protected]"+}+```++**Sealed class for exhaustive results:**+```kotlin+sealed class Result<out T> {+ data class Success<T>(val data: T) : Result<T>()+ data class Failure(val error: AppError) : Result<Nothing>()+ data object Loading : Result<Nothing>()+}+```++**Structured concurrency with async/await:**+```kotlin+suspend fun fetchUserWithPosts(userId: String): UserProfile =+ coroutineScope {+ val user = async { userService.getUser(userId) }+ val posts = async { postService.getUserPosts(userId) }+ UserProfile(user = user.await(), posts = posts.await())+ }+```++## Core Principles++### 1. Null Safety++Kotlin's type system distinguishes nullable and non-nullable types. Leverage it fully.++```kotlin+// Good: Use non-nullable types by default+fun getUser(id: String): User {+ return userRepository.findById(id)+ ?: throw UserNotFoundException("User $id not found")+}++// Good: Safe calls and Elvis operator+fun getUserEmail(userId: String): String {+ val user = userRepository.findById(userId)+ return user?.email ?: "[email protected]"+}++// Bad: Force-unwrapping nullable types+fun getUserEmail(userId: String): String {+ val user = userRepository.findById(userId)+ return user!!.email // Throws NPE if null+}+```++### 2. Immutability by Default++Prefer `val` over `var`, immutable collections over mutable ones.++```kotlin+// Good: Immutable data+data class User(+ val id: String,+ val name: String,+ val email: String,+)++// Good: Transform with copy()+fun updateEmail(user: User, newEmail: String): User =+ user.copy(email = newEmail)++// Good: Immutable collections+val users: List<User> = listOf(user1, user2)+val filtered = users.filter { it.email.isNotBlank() }++// Bad: Mutable state+var currentUser: User? = null // Avoid mutable global state+val mutableUsers = mutableListOf<User>() // Avoid unless truly needed+```++### 3. Expression Bodies and Single-Expression Functions++Use expression bodies for concise, readable functions.++```kotlin+// Good: Expression body+fun isAdult(age: Int): Boolean = age >= 18++fun formatFullName(first: String, last: String): String =+ "$first $last".trim()++fun User.displayName(): String =+ name.ifBlank { email.substringBefore('@') }++// Good: When as expression+fun statusMessage(code: Int): String = when (code) {+ 200 -> "OK"+ 404 -> "Not Found"+ 500 -> "Internal Server Error"+ else -> "Unknown status: $code"+}++// Bad: Unnecessary block body+fun isAdult(age: Int): Boolean {+ return age >= 18+}+```++### 4. Data Classes for Value Objects++Use data classes for types that primarily hold data.++```kotlin+// Good: Data class with copy, equals, hashCode, toString+data class CreateUserRequest(+ val name: String,+ val email: String,+ val role: Role = Role.USER,+)++// Good: Value class for type safety (zero overhead at runtime)+@JvmInline+value class UserId(val value: String) {+ init {+ require(value.isNotBlank()) { "UserId cannot be blank" }+ }+}++@JvmInline+value class Email(val value: String) {+ init {+ require('@' in value) { "Invalid email: $value" }+ }+}++fun getUser(id: UserId): User = userRepository.findById(id)+```++## Sealed Classes and Interfaces++### Modeling Restricted Hierarchies++```kotlin+// Good: Sealed class for exhaustive when+sealed class Result<out T> {+ data class Success<T>(val data: T) : Result<T>()+ data class Failure(val error: AppError) : Result<Nothing>()+ data object Loading : Result<Nothing>()+}++fun <T> Result<T>.getOrNull(): T? = when (this) {+ is Result.Success -> data+ is Result.Failure -> null+ is Result.Loading -> null+}++fun <T> Result<T>.getOrThrow(): T = when (this) {+ is Result.Success -> data+ is Result.Failure -> throw error.toException()+ is Result.Loading -> throw IllegalStateException("Still loading")+}+```++### Sealed Interfaces for API Responses++```kotlin+sealed interface ApiError {+ val message: String++ data class NotFound(override val message: String) : ApiError+ data class Unauthorized(override val message: String) : ApiError+ data class Validation(+ override val message: String,+ val field: String,+ ) : ApiError+ data class Internal(+ override val message: String,+ val cause: Throwable? = null,+ ) : ApiError+}++fun ApiError.toStatusCode(): Int = when (this) {+ is ApiError.NotFound -> 404+ is ApiError.Unauthorized -> 401+ is ApiError.Validation -> 422+ is ApiError.Internal -> 500+}+```++## Scope Functions++### When to Use Each++```kotlin+// let: Transform nullable or scoped result+val length: Int? = name?.let { it.trim().length }++// apply: Configure an object (returns the object)+val user = User().apply {+ name = "Alice"+ email = "[email protected]"+}++// also: Side effects (returns the object)+val user = createUser(request).also { logger.info("Created user: ${it.id}") }++// run: Execute a block with receiver (returns result)+val result = connection.run {+ prepareStatement(sql)+ executeQuery()+}++// with: Non-extension form of run+val csv = with(StringBuilder()) {+ appendLine("name,email")+ users.forEach { appendLine("${it.name},${it.email}") }+ toString()+}+```++### Anti-Patterns++```kotlin+// Bad: Nesting scope functions+user?.let { u ->+ u.address?.let { addr ->+ addr.city?.let { city ->+ println(city) // Hard to read+ }+ }+}++// Good: Chain safe calls instead+val city = user?.address?.city+city?.let { println(it) }+```++## Extension Functions++### Adding Functionality Without Inheritance++```kotlin+// Good: Domain-specific extensions+fun String.toSlug(): String =+ lowercase()+ .replace(Regex("[^a-z0-9\\s-]"), "")+ .replace(Regex("\\s+"), "-")+ .trim('-')++fun Instant.toLocalDate(zone: ZoneId = ZoneId.systemDefault()): LocalDate =+ atZone(zone).toLocalDate()++// Good: Collection extensions+fun <T> List<T>.second(): T = this[1]++fun <T> List<T>.secondOrNull(): T? = getOrNull(1)++// Good: Scoped extensions (not polluting global namespace)+class UserService {+ private fun User.isActive(): Boolean =+ status == Status.ACTIVE && lastLogin.isAfter(Instant.now().minus(30, ChronoUnit.DAYS))++ fun getActiveUsers(): List<User> = userRepository.findAll().filter { it.isActive() }+}+```++## Coroutines++### Structured Concurrency++```kotlin+// Good: Structured concurrency with coroutineScope+suspend fun fetchUserWithPosts(userId: String): UserProfile =+ coroutineScope {+ val userDeferred = async { userService.getUser(userId) }+ val postsDeferred = async { postService.getUserPosts(userId) }++ UserProfile(+ user = userDeferred.await(),+ posts = postsDeferred.await(),+ )+ }++// Good: supervisorScope when children can fail independently+suspend fun fetchDashboard(userId: String): Dashboard =+ supervisorScope {+ val user = async { userService.getUser(userId) }+ val notifications = async { notificationService.getRecent(userId) }+ val recommendations = async { recommendationService.getFor(userId) }++ Dashboard(+ user = user.await(),+ notifications = try {+ notifications.await()+ } catch (e: CancellationException) {+ throw e+ } catch (e: Exception) {+ emptyList()+ },+ recommendations = try {+ recommendations.await()+ } catch (e: CancellationException) {+ throw e+ } catch (e: Exception) {+ emptyList()+ },+ )+ }+```++### Flow for Reactive Streams++```kotlin+// Good: Cold flow with proper error handling+fun observeUsers(): Flow<List<User>> = flow {+ while (currentCoroutineContext().isActive) {+ val users = userRepository.findAll()+ emit(users)+ delay(5.seconds)+ }+}.catch { e ->+ logger.error("Error observing users", e)+ emit(emptyList())+}++// Good: Flow operators+fun searchUsers(query: Flow<String>): Flow<List<User>> =+ query+ .debounce(300.milliseconds)+ .distinctUntilChanged()+ .filter { it.length >= 2 }+ .mapLatest { q -> userRepository.search(q) }+ .catch { emit(emptyList()) }+```++### Cancellation and Cleanup++```kotlin+// Good: Respect cancellation+suspend fun processItems(items: List<Item>) {+ items.forEach { item ->+ ensureActive() // Check cancellation before expensive work+ processItem(item)+ }+}++// Good: Cleanup with try/finally+suspend fun acquireAndProcess() {+ val resource = acquireResource()+ try {+ resource.process()+ } finally {+ withContext(NonCancellable) {+ resource.release() // Always release, even on cancellation+ }+ }+}+```++## Delegation++### Property Delegation++```kotlin+// Lazy initialization+val expensiveData: List<User> by lazy {+ userRepository.findAll()+}++// Observable property+var name: String by Delegates.observable("initial") { _, old, new ->+ logger.info("Name changed from '$old' to '$new'")+}++// Map-backed properties+class Config(private val map: Map<String, Any?>) {+ val host: String by map+ val port: Int by map+ val debug: Boolean by map+}++val config = Config(mapOf("host" to "localhost", "port" to 8080, "debug" to true))+```++### Interface Delegation++```kotlin+// Good: Delegate interface implementation+class LoggingUserRepository(+ private val delegate: UserRepository,+ private val logger: Logger,+) : UserRepository by delegate {+ // Only override what you need to add logging to+ override suspend fun findById(id: String): User? {+ logger.info("Finding user by id: $id")+ return delegate.findById(id).also {+ logger.info("Found user: ${it?.name ?: "null"}")+ }+ }+}+```++## DSL Builders++### Type-Safe Builders++```kotlin+// Good: DSL with @DslMarker+@DslMarker+annotation class HtmlDsl++@HtmlDsl+class HTML {+ private val children = mutableListOf<Element>()++ fun head(init: Head.() -> Unit) {+ children += Head().apply(init)+ }++ fun body(init: Body.() -> Unit) {+ children += Body().apply(init)+ }++ override fun toString(): String = children.joinToString("\n")+}++fun html(init: HTML.() -> Unit): HTML = HTML().apply(init)++// Usage+val page = html {+ head { title("My Page") }+ body {+ h1("Welcome")+ p("Hello, World!")+ }+}+```++### Configuration DSL++```kotlin+data class ServerConfig(+ val host: String = "0.0.0.0",+ val port: Int = 8080,+ val ssl: SslConfig? = null,+ val database: DatabaseConfig? = null,+)++data class SslConfig(val certPath: String, val keyPath: String)+data class DatabaseConfig(val url: String, val maxPoolSize: Int = 10)++class ServerConfigBuilder {+ var host: String = "0.0.0.0"+ var port: Int = 8080+ private var ssl: SslConfig? = null+ private var database: DatabaseConfig? = null++ fun ssl(certPath: String, keyPath: String) {+ ssl = SslConfig(certPath, keyPath)+ }++ fun database(url: String, maxPoolSize: Int = 10) {+ database = DatabaseConfig(url, maxPoolSize)+ }++ fun build(): ServerConfig = ServerConfig(host, port, ssl, database)+}++fun serverConfig(init: ServerConfigBuilder.() -> Unit): ServerConfig =+ ServerConfigBuilder().apply(init).build()++// Usage+val config = serverConfig {+ host = "0.0.0.0"+ port = 443+ ssl("/certs/cert.pem", "/certs/key.pem")+ database("jdbc:postgresql://localhost:5432/mydb", maxPoolSize = 20)+}+```++## Sequences for Lazy Evaluation++```kotlin+// Good: Use sequences for large collections with multiple operations+val result = users.asSequence()+ .filter { it.isActive }+ .map { it.email }+ .filter { it.endsWith("@company.com") }+ .take(10)+ .toList()++// Good: Generate infinite sequences+val fibonacci: Sequence<Long> = sequence {+ var a = 0L+ var b = 1L+ while (true) {+ yield(a)+ val next = a + b+ a = b+ b = next+ }+}++val first20 = fibonacci.take(20).toList()+```++## Gradle Kotlin DSL++### build.gradle.kts Configuration++```kotlin+// Check for latest versions: https://kotlinlang.org/docs/releases.html+plugins {+ kotlin("jvm") version "2.3.10"+ kotlin("plugin.serialization") version "2.3.10"+ id("io.ktor.plugin") version "3.4.0"+ id("org.jetbrains.kotlinx.kover") version "0.9.7"+ id("io.gitlab.arturbosch.detekt") version "1.23.8"+}++group = "com.example"+version = "1.0.0"++kotlin {+ jvmToolchain(21)+}++dependencies {+ // Ktor+ implementation("io.ktor:ktor-server-core:3.4.0")+ implementation("io.ktor:ktor-server-netty:3.4.0")+ implementation("io.ktor:ktor-server-content-negotiation:3.4.0")+ implementation("io.ktor:ktor-serialization-kotlinx-json:3.4.0")++ // Exposed+ implementation("org.jetbrains.exposed:exposed-core:1.0.0")+ implementation("org.jetbrains.exposed:exposed-dao:1.0.0")+ implementation("org.jetbrains.exposed:exposed-jdbc:1.0.0")+ implementation("org.jetbrains.exposed:exposed-kotlin-datetime:1.0.0")++ // Koin+ implementation("io.insert-koin:koin-ktor:4.2.0")++ // Coroutines+ implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.10.2")++ // Testing+ testImplementation("io.kotest:kotest-runner-junit5:6.1.4")+ testImplementation("io.kotest:kotest-assertions-core:6.1.4")+ testImplementation("io.kotest:kotest-property:6.1.4")+ testImplementation("io.mockk:mockk:1.14.9")+ testImplementation("io.ktor:ktor-server-test-host:3.4.0")+ testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.10.2")+}++tasks.withType<Test> {+ useJUnitPlatform()+}++detekt {+ config.setFrom(files("config/detekt/detekt.yml"))+ buildUponDefaultConfig = true+}+```++## Error Handling Patterns++### Result Type for Domain Operations++```kotlin+// Good: Use Kotlin's Result or a custom sealed class+suspend fun createUser(request: CreateUserRequest): Result<User> = runCatching {+ require(request.name.isNotBlank()) { "Name cannot be blank" }+ require('@' in request.email) { "Invalid email format" }++ val user = User(+ id = UserId(UUID.randomUUID().toString()),+ name = request.name,+ email = Email(request.email),+ )+ userRepository.save(user)+ user+}++// Good: Chain results+val displayName = createUser(request)+ .map { it.name }+ .getOrElse { "Unknown" }+```++### require, check, error++```kotlin+// Good: Preconditions with clear messages+fun withdraw(account: Account, amount: Money): Account {+ require(amount.value > 0) { "Amount must be positive: $amount" }+ check(account.balance >= amount) { "Insufficient balance: ${account.balance} < $amount" }++ return account.copy(balance = account.balance - amount)+}+```++## Collection Operations++### Idiomatic Collection Processing++```kotlin+// Good: Chained operations+val activeAdminEmails: List<String> = users+ .filter { it.role == Role.ADMIN && it.isActive }+ .sortedBy { it.name }+ .map { it.email }++// Good: Grouping and aggregation+val usersByRole: Map<Role, List<User>> = users.groupBy { it.role }++val oldestByRole: Map<Role, User?> = users.groupBy { it.role }+ .mapValues { (_, users) -> users.minByOrNull { it.createdAt } }++// Good: Associate for map creation+val usersById: Map<UserId, User> = users.associateBy { it.id }++// Good: Partition for splitting+val (active, inactive) = users.partition { it.isActive }+```++## Quick Reference: Kotlin Idioms++| Idiom | Description |+|-------|-------------|+| `val` over `var` | Prefer immutable variables |+| `data class` | For value objects with equals/hashCode/copy |+| `sealed class/interface` | For restricted type hierarchies |+| `value class` | For type-safe wrappers with zero overhead |+| Expression `when` | Exhaustive pattern matching |+| Safe call `?.` | Null-safe member access |+| Elvis `?:` | Default value for nullables |+| `let`/`apply`/`also`/`run`/`with` | Scope functions for clean code |+| Extension functions | Add behavior without inheritance |+| `copy()` | Immutable updates on data classes |+| `require`/`check` | Precondition assertions |+| Coroutine `async`/`await` | Structured concurrent execution |+| `Flow` | Cold reactive streams |+| `sequence` | Lazy evaluation |+| Delegation `by` | Reuse implementation without inheritance |++## Anti-Patterns to Avoid++```kotlin+// Bad: Force-unwrapping nullable types+val name = user!!.name++// Bad: Platform type leakage from Java+fun getLength(s: String) = s.length // Safe+fun getLength(s: String?) = s?.length ?: 0 // Handle nulls from Java++// Bad: Mutable data classes+data class MutableUser(var name: String, var email: String)++// Bad: Using exceptions for control flow+try {+ val user = findUser(id)+} catch (e: NotFoundException) {+ // Don't use exceptions for expected cases+}++// Good: Use nullable return or Result+val user: User? = findUserOrNull(id)++// Bad: Ignoring coroutine scope+GlobalScope.launch { /* Avoid GlobalScope */ }++// Good: Use structured concurrency+coroutineScope {+ launch { /* Properly scoped */ }+}++// Bad: Deeply nested scope functions+user?.let { u ->+ u.address?.let { a ->+ a.city?.let { c -> process(c) }+ }+}++// Good: Direct null-safe chain+user?.address?.city?.let { process(it) }+```++**Remember**: Kotlin code should be concise but readable. Leverage the type system for safety, prefer immutability, and use coroutines for concurrency. When in doubt, let the compiler help you.diff --git a/skills/kotlin-testing/SKILL.md b/skills/kotlin-testing/SKILL.mdnew file mode 100644index 000000000..bfc2772f3--- /dev/null+++ b/skills/kotlin-testing/SKILL.md@@ -0,0 +1,824 @@+---+name: kotlin-testing+description: Kotlin testing patterns with Kotest, MockK, coroutine testing, property-based testing, and Kover coverage. Follows TDD methodology with idiomatic Kotlin practices.+origin: ECC+---++# Kotlin Testing Patterns++Comprehensive Kotlin testing patterns for writing reliable, maintainable tests following TDD methodology with Kotest and MockK.++## When to Use++- Writing new Kotlin functions or classes+- Adding test coverage to existing Kotlin code+- Implementing property-based tests+- Following TDD workflow in Kotlin projects+- Configuring Kover for code coverage++## How It Works++1. **Identify target code** — Find the function, class, or module to test+2. **Write a Kotest spec** — Choose a spec style (StringSpec, FunSpec, BehaviorSpec) matching the test scope+3. **Mock dependencies** — Use MockK to isolate the unit under test+4. **Run tests (RED)** — Verify the test fails with the expected error+5. **Implement code (GREEN)** — Write minimal code to pass the test+6. **Refactor** — Improve the implementation while keeping tests green+7. **Check coverage** — Run `./gradlew koverHtmlReport` and verify 80%+ coverage++## Examples++The following sections contain detailed, runnable examples for each testing pattern:++### Quick Reference++- **Kotest specs** — StringSpec, FunSpec, BehaviorSpec, DescribeSpec examples in [Kotest Spec Styles](#kotest-spec-styles)+- **Mocking** — MockK setup, coroutine mocking, argument capture in [MockK](#mockk)+- **TDD walkthrough** — Full RED/GREEN/REFACTOR cycle with EmailValidator in [TDD Workflow for Kotlin](#tdd-workflow-for-kotlin)+- **Coverage** — Kover configuration and commands in [Kover Coverage](#kover-coverage)+- **Ktor testing** — testApplication setup in [Ktor testApplication Testing](#ktor-testapplication-testing)++## TDD Workflow for Kotlin++### The RED-GREEN-REFACTOR Cycle++```+RED -> Write a failing test first+GREEN -> Write minimal code to pass the test+REFACTOR -> Improve code while keeping tests green+REPEAT -> Continue with next requirement+```++### Step-by-Step TDD in Kotlin++```kotlin+// Step 1: Define the interface/signature+// EmailValidator.kt+package com.example.validator++fun validateEmail(email: String): Result<String> {+ TODO("not implemented")+}++// Step 2: Write failing test (RED)+// 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({+ "valid email returns success" {+ validateEmail("[email protected]").shouldBeSuccess("[email protected]")+ }++ "empty email returns failure" {+ validateEmail("").shouldBeFailure()+ }++ "email without @ returns failure" {+ validateEmail("userexample.com").shouldBeFailure()+ }+})++// Step 3: Run tests - verify FAIL+// $ ./gradlew test+// EmailValidatorTest > valid email returns success FAILED+// kotlin.NotImplementedError: An operation is not implemented++// Step 4: Implement minimal code (GREEN)+fun validateEmail(email: String): Result<String> {+ if (email.isBlank()) return Result.failure(IllegalArgumentException("Email cannot be blank"))+ if ('@' !in email) return Result.failure(IllegalArgumentException("Email must contain @"))+ val regex = Regex("^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$")+ if (!regex.matches(email)) return Result.failure(IllegalArgumentException("Invalid email format"))+ return Result.success(email)+}++// Step 5: Run tests - verify PASS+// $ ./gradlew test+// EmailValidatorTest > valid email returns success PASSED+// EmailValidatorTest > empty email returns failure PASSED+// EmailValidatorTest > email without @ returns failure PASSED++// Step 6: Refactor if needed, verify tests still pass+```++## Kotest Spec Styles++### StringSpec (Simplest)++```kotlin+class CalculatorTest : StringSpec({+ "add two positive numbers" {+ Calculator.add(2, 3) shouldBe 5+ }++ "add negative numbers" {+ Calculator.add(-1, -2) shouldBe -3+ }++ "add zero" {+ Calculator.add(0, 5) shouldBe 5+ }+})+```++### FunSpec (JUnit-like)++```kotlin+class UserServiceTest : FunSpec({+ val repository = mockk<UserRepository>()+ val service = UserService(repository)++ test("getUser returns user when found") {+ val expected = User(id = "1", name = "Alice")+ coEvery { repository.findById("1") } returns expected++ val result = service.getUser("1")++ result shouldBe expected+ }++ test("getUser throws when not found") {+ coEvery { repository.findById("999") } returns null++ shouldThrow<UserNotFoundException> {+ service.getUser("999")+ }+ }+})+```++### BehaviorSpec (BDD Style)++```kotlin+class OrderServiceTest : BehaviorSpec({+ val repository = mockk<OrderRepository>()+ val paymentService = mockk<PaymentService>()+ val service = OrderService(repository, paymentService)++ Given("a valid order request") {+ val request = CreateOrderRequest(+ userId = "user-1",+ items = listOf(OrderItem("product-1", quantity = 2)),+ )++ When("the order is placed") {+ coEvery { paymentService.charge(any()) } returns PaymentResult.Success+ coEvery { repository.save(any()) } answers { firstArg() }++ val result = service.placeOrder(request)++ Then("it should return a confirmed order") {+ result.status shouldBe OrderStatus.CONFIRMED+ }++ Then("it should charge payment") {+ coVerify(exactly = 1) { paymentService.charge(any()) }+ }+ }++ When("payment fails") {+ coEvery { paymentService.charge(any()) } returns PaymentResult.Declined++ Then("it should throw PaymentException") {+ shouldThrow<PaymentException> {+ service.placeOrder(request)+ }+ }+ }+ }+})+```++### DescribeSpec (RSpec Style)++```kotlin+class UserValidatorTest : DescribeSpec({+ describe("validateUser") {+ val validator = UserValidator()++ context("with valid input") {+ it("accepts a normal user") {+ val user = CreateUserRequest("Alice", "[email protected]")+ validator.validate(user).shouldBeValid()+ }+ }++ context("with invalid name") {+ it("rejects blank name") {+ val user = CreateUserRequest("", "[email protected]")+ validator.validate(user).shouldBeInvalid()+ }++ it("rejects name exceeding max length") {+ val user = CreateUserRequest("A".repeat(256), "[email protected]")+ validator.validate(user).shouldBeInvalid()+ }+ }+ }+})+```++## Kotest Matchers++### Core Matchers++```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.*++// Equality+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()++// Collections+list shouldContain "item"+list shouldHaveSize 3+list.shouldBeSorted()+list.shouldContainAll("a", "b", "c")+list.shouldBeEmpty()++// Nulls+result.shouldNotBeNull()+result.shouldBeNull()++// Types+result.shouldBeInstanceOf<User>()++// Numbers+count shouldBeGreaterThan 0+price shouldBeInRange 1.0..100.0++// Exceptions+shouldThrow<IllegalArgumentException> {+ validateAge(-1)+}.message shouldBe "Age must be positive"++shouldNotThrow<Exception> {+ validateAge(25)+}+```++### Custom Matchers++```kotlin+fun beActiveUser() = object : Matcher<User> {+ override fun test(value: User) = MatcherResult(+ value.isActive && value.lastLogin != null,+ { "User ${value.id} should be active with a last login" },+ { "User ${value.id} should not be active" },+ )+}++// Usage+user should beActiveUser()+```++## MockK++### Basic Mocking++```kotlin+class UserServiceTest : FunSpec({+ val repository = mockk<UserRepository>()+ val logger = mockk<Logger>(relaxed = true) // Relaxed: returns defaults+ val service = UserService(repository, logger)++ beforeTest {+ clearMocks(repository, logger)+ }++ test("findUser delegates to repository") {+ 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 returns null for unknown id") {+ every { repository.findById(any()) } returns null++ val result = service.findUser("unknown")++ result.shouldBeNull()+ }+})+```++### Coroutine Mocking++```kotlin+class AsyncUserServiceTest : FunSpec({+ val repository = mockk<UserRepository>()+ val service = UserService(repository)++ test("getUser suspending function") {+ 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 with delay") {+ coEvery { repository.findById("1") } coAnswers {+ delay(100) // Simulate async work+ User(id = "1", name = "Alice")+ }++ val result = service.getUser("1")+ result.name shouldBe "Alice"+ }+})+```++### Argument Capture++```kotlin+test("save captures the user argument") {+ val slot = slot<User>()+ coEvery { repository.save(capture(slot)) } returns Unit++ service.createUser(CreateUserRequest("Alice", "[email protected]"))++ slot.captured.name shouldBe "Alice"+ slot.captured.email shouldBe "[email protected]"+ slot.captured.id.shouldNotBeNull()+}+```++### Spy and Partial Mocking++```kotlin+test("spy on real object") {+ val realService = UserService(repository)+ val spy = spyk(realService)++ every { spy.generateId() } returns "fixed-id"++ spy.createUser(request)++ verify { spy.generateId() } // Overridden+ // Other methods use real implementation+}+```++## Coroutine Testing++### runTest for Suspend Functions++```kotlin+import kotlinx.coroutines.test.runTest++class CoroutineServiceTest : FunSpec({+ test("concurrent fetches complete together") {+ runTest {+ val service = DataService(testScope = this)++ val result = service.fetchAllData()++ result.users.shouldNotBeEmpty()+ result.products.shouldNotBeEmpty()+ }+ }++ test("timeout after delay") {+ runTest {+ val service = SlowService()++ shouldThrow<TimeoutCancellationException> {+ withTimeout(100) {+ service.slowOperation() // Takes > 100ms+ }+ }+ }+ }+})+```++### Testing 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 emits updates") {+ runTest {+ val service = UserFlowService()++ val emissions = service.observeUsers()+ .take(3)+ .toList()++ emissions shouldHaveSize 3+ emissions.last().shouldNotBeEmpty()+ }+ }++ test("searchUsers debounces input") {+ 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") // Only this should trigger search+ advanceTimeBy(500)++ results shouldHaveSize 1+ job.cancel()+ }+ }+})+```++### TestDispatcher++```kotlin+import kotlinx.coroutines.test.StandardTestDispatcher+import kotlinx.coroutines.test.advanceUntilIdle++class DispatcherTest : FunSpec({+ test("uses test dispatcher for controlled execution") {+ val dispatcher = StandardTestDispatcher()++ runTest(dispatcher) {+ var completed = false++ launch {+ delay(1000)+ completed = true+ }++ completed shouldBe false+ advanceTimeBy(1000)+ completed shouldBe true+ }+ }+})+```++## Property-Based Testing++### Kotest Property Testing++```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++// Note: The serialization roundtrip test below requires the User data class+// to be annotated with @Serializable (from kotlinx.serialization).++class PropertyTest : FunSpec({+ test("string reverse is involutory") {+ forAll<String> { s ->+ s.reversed().reversed() == s+ }+ }++ test("list sort is idempotent") {+ forAll(Arb.list(Arb.int())) { list ->+ list.sorted() == list.sorted().sorted()+ }+ }++ test("serialization roundtrip preserves data") {+ checkAll(Arb.bind(Arb.string(1..50), Arb.string(5..100)) { name, email ->+ User(name = name, email = "[email protected]")+ }) { user ->+ val json = Json.encodeToString(user)+ val decoded = Json.decodeFromString<User>(json)+ decoded shouldBe user+ }+ }+})+```++### Custom Generators++```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)+}+```++## Data-Driven Testing++### withData in Kotest++```kotlin+class ParserTest : FunSpec({+ context("parsing valid dates") {+ 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("rejecting invalid dates") {+ withData(+ nameFn = { "rejects '$it'" },+ "not-a-date",+ "2026-13-01",+ "2026-00-15",+ "",+ ) { input ->+ shouldThrow<DateParseException> {+ parseDate(input)+ }+ }+ }+})+```++## Test Lifecycle and 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("insert and retrieve user") {+ transaction(db) {+ UsersTable.insert {+ it[name] = "Alice"+ it[email] = "[email protected]"+ }+ }++ val users = transaction(db) {+ UsersTable.selectAll().map { it[UsersTable.name] }+ }++ users shouldContain "Alice"+ }+})+```++### Kotest Extensions++```kotlin+// Reusable test extension+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) {+ // cleanup+ }+}++class UserRepositoryTest : FunSpec({+ val dbExt = DatabaseExtension()+ register(dbExt)++ test("save and find user") {+ val repo = UserRepository(dbExt.db)+ // ...+ }+})+```++## Kover Coverage++### Gradle Configuration++```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) // Fail build below 80% coverage+ }+ }+ }+}+```++### Coverage Commands++```bash+# Run tests with coverage+./gradlew koverHtmlReport++# Verify coverage thresholds+./gradlew koverVerify++# XML report for CI+./gradlew koverXmlReport++# View HTML report (use the command for your OS)+# 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+```++### Coverage Targets++| Code Type | Target |+|-----------|--------|+| Critical business logic | 100% |+| Public APIs | 90%+ |+| General code | 80%+ |+| Generated / config code | Exclude |++## Ktor testApplication Testing++```kotlin+class ApiRoutesTest : FunSpec({+ test("GET /users returns list") {+ 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 creates user") {+ testApplication {+ application {+ configureRouting()+ configureSerialization()+ }++ val response = client.post("/users") {+ contentType(ContentType.Application.Json)+ setBody(CreateUserRequest("Alice", "[email protected]"))+ }++ response.status shouldBe HttpStatusCode.Created+ }+ }+})+```++## Testing Commands++```bash+# Run all tests+./gradlew test++# Run specific test class+./gradlew test --tests "com.example.UserServiceTest"++# Run specific test+./gradlew test --tests "com.example.UserServiceTest.getUser returns user when found"++# Run with verbose output+./gradlew test --info++# Run with coverage+./gradlew koverHtmlReport++# Run detekt (static analysis)+./gradlew detekt++# Run ktlint (formatting check)+./gradlew ktlintCheck++# Continuous testing+./gradlew test --continuous+```++## Best Practices++**DO:**+- Write tests FIRST (TDD)+- Use Kotest's spec styles consistently across the project+- Use MockK's `coEvery`/`coVerify` for suspend functions+- Use `runTest` for coroutine testing+- Test behavior, not implementation+- Use property-based testing for pure functions+- Use `data class` test fixtures for clarity++**DON'T:**+- Mix testing frameworks (pick Kotest and stick with it)+- Mock data classes (use real instances)+- Use `Thread.sleep()` in coroutine tests (use `advanceTimeBy`)+- Skip the RED phase in TDD+- Test private functions directly+- Ignore flaky tests++## Integration with CI/CD++```yaml+# GitHub Actions example+test:+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-java@v4+ with:+ distribution: 'temurin'+ java-version: '21'++ - name: Run tests with coverage+ run: ./gradlew test koverXmlReport++ - name: Verify coverage+ run: ./gradlew koverVerify++ - name: Upload coverage+ uses: codecov/codecov-action@v5+ with:+ files: build/reports/kover/report.xml+ token: ${{ secrets.CODECOV_TOKEN }}+```++**Remember**: Tests are documentation. They show how your Kotlin code is meant to be used. Use Kotest's expressive matchers to make tests readable and MockK for clean mocking of dependencies.