Day 4: PRS Few-Shot Exemplar Engineering

---
name: spring-boot-mockk-tester
schema-version: "1.0.0"
description: >
  Generates and refactors isolated JVM unit tests for Kotlin, Spring Boot 3.x, 
  and Coroutines using MockK, AssertJ, and kotlinx-coroutines-test.
  USE WHEN: Writing unit tests for suspend functions, Spring Data R2DBC, or WebFlux services.
  DO NOT USE WHEN: Writing @SpringBootTest integration tests or database Testcontainers.
metadata:
  domain: "reactive-backend"
  framework: "Spring Boot 3.x / Kotlin 1.9+"
---

# Kotlin Spring Boot & Coroutine Unit Test Engine

## 1. Non-Negotiable In-Context Invariants
- **MUST NOT** import `org.mockito.*` or `org.springframework.boot.test.mock.mockito.*`.
- **MUST NOT** use `@SpringBootTest`, `@WebFluxTest`, or boot the ApplicationContext.
- **MUST** wrap all suspend function invocations inside `kotlinx.coroutines.test.runTest`.
- **MUST** use `coEvery { ... }` and `coVerify { ... }` for suspend functions.
- **MUST** structure test methods using explicit `// Arrange`, `// Act`, and `// Assert`.


## 2. Pattern-Reasoning-Solution (PRS) Exemplars

### Exemplar 1: Suspend Service Call with Coroutines & MockK

#### [P] Pattern:
Testing an asynchronous `OrderSettlementService.processOrder(orderId)` that executes a suspension 
call to `PaymentClient.authorize(paymentRequest)` and persists via `OrderRepository.updateStatus()`.

#### [R] Architectural Reasoning:
1. **Coroutine Scope Execution**: Because `processOrder` is a `suspend fun`, the test method MUST be 
   wrapped in `runTest` from `kotlinx.coroutines.test` to advance virtual time deterministically.
2. **Mocking Suspension Methods**: Regular `every { ... }` will throw a runtime compilation error when 
   stubbing suspend functions. The engineer MUST use `coEvery { ... }`.
3. **Pure Memory Isolation**: Injected constructor dependencies are instantiated via `mockk<T>()`. 
   No Spring runner or Reflection is used.

#### [S] Canonical Solution:
```kotlin
package com.enterprise.billing.service

import io.mockk.coEvery
import io.mockk.coVerify
import io.mockk.confirmVerified
import io.mockk.mockk
import kotlinx.coroutines.test.runTest
import org.assertj.core.api.Assertions.assertThat
import org.junit.jupiter.api.AfterEach
import org.junit.jupiter.api.Test
import java.util.UUID

class OrderSettlementServiceTest {

    private val paymentClient: PaymentClient = mockk()
    private val orderRepository: OrderRepository = mockk()

    private val service = OrderSettlementService(
        paymentClient = paymentClient,
        orderRepository = orderRepository
    )

    @AfterEach
    fun tearDown() {
        confirmVerified(paymentClient, orderRepository)
    }

    @Test
    fun `should successfully process valid order and update status to SETTLED`() = runTest {
        // Arrange
        val orderId = UUID.randomUUID()
        val expectedTxId = "TX-998822"
        
        coEvery { paymentClient.authorize(orderId, any()) } returns PaymentResult.Success(expectedTxId)
        coEvery { orderRepository.updateStatus(orderId, OrderStatus.SETTLED) } returns true

        // Act
        val result = service.processOrder(orderId)

        // Assert
        assertThat(result.isSuccess).isTrue()
        assertThat(result.transactionId).isEqualTo(expectedTxId)

        coVerify(exactly = 1) { paymentClient.authorize(orderId, any()) }
        coVerify(exactly = 1) { orderRepository.updateStatus(orderId, OrderStatus.SETTLED) }
    }
}
```

---

### Exemplar 2: Exception Handling & Verification Triage

#### [P] Pattern:
Testing failure degradation in `OrderSettlementService.processOrder(orderId)` when `PaymentClient.authorize` 
throws an unrecoverable `PaymentGatewayTimeoutException`.

#### [R] Architectural Reasoning:
1. **Throwing in Coroutines**: When simulating an exception from a suspend method, use `coEvery { ... } throws Exception()`.
2. **Deterministic Assertions**: Use AssertJ's `assertThatThrownBy` to assert exception type and message.
3. **Interaction Verification Verification**: Ensure `orderRepository.updateStatus()` is NEVER called if authorization fails 
   using `coVerify(exactly = 0)`.

#### [S] Canonical Solution:
```kotlin
    @Test
    fun `should abort and throw PaymentTimeoutException when payment provider times out`() = runTest {
        // Arrange
        val orderId = UUID.randomUUID()
        coEvery { 
            paymentClient.authorize(orderId, any()) 
        } throws PaymentGatewayTimeoutException("Provider connection dropped")

        // Act & Assert
        org.assertj.core.api.Assertions.assertThatThrownBy {
            kotlinx.coroutines.runBlocking { service.processOrder(orderId) }
        }.isInstanceOf(PaymentGatewayTimeoutException::class.java)
         .hasMessageContaining("Provider connection dropped")

        coVerify(exactly = 1) { paymentClient.authorize(orderId, any()) }
        coVerify(exactly = 0) { orderRepository.updateStatus(any(), any()) }
    }
```