Day 10: Capstone: Enterprise Unit Test Skill

---
name: spring-boot-unit-tester
schema-version: "1.0.0"
description: >
  Generates and refactors isolated JVM unit tests for Kotlin and Spring Boot 3.x 
  using JUnit 5, MockK, AssertJ, and Coroutines Test.
  
  USE WHEN:
  - Authoring unit tests for @Service, @Component, or Domain Logic classes.
  - Mocking suspend functions using MockK (`coEvery { ... }`, `runTest`).
  - Diagnosing failed Maven unit test runs.
  
  DO NOT USE WHEN:
  - Testing database interactions requiring Testcontainers, Postgres, or H2.
  - Writing integration tests annotated with @SpringBootTest or @DataJpaTest.
  - Writing frontend or end-to-end Cypress/Playwright tests.
tools:
  - name: extract-target-ast
    description: Extracts concise AST skeleton (constructor dependencies and suspend methods) from target source file.
    file: scripts/extract-target-ast.py
  - name: harvest-exemplars
    description: Dynamically harvests idiomatic golden unit test exemplars from the local repository.
    file: scripts/harvest-exemplars.py
  - name: query-reference
    description: Queries on-demand domain DTO schemas and fixtures from references/ directory.
    file: scripts/query-reference.sh
  - name: run-unit-tests
    description: Runs sandboxed Maven test execution with automatic stderr triage and timeout guards.
    file: scripts/run-unit-tests.sh
metadata:
  domain: "backend-quality"
  target-framework: "Spring Boot 3.x / Kotlin 1.9+"
---

# Spring Boot Unit Test Architect Specification

## 1. Architectural Invariants (RFC 2119 Mandates)
- **MUST NOT** import `org.mockito.*` or `org.springframework.boot.test.mock.mockito.*`.
- **MUST NOT** annotate test classes with `@SpringBootTest`, `@DataJpaTest`, or `@WebMvcTest`.
- **MUST NOT** use Reflection (`ReflectionTestUtils`). All dependencies MUST be injected via constructor.
- **MUST** execute strictly in-memory (< 50ms per method) without Spring ApplicationContext.
- **MUST** wrap all `suspend` methods inside `kotlinx.coroutines.test.runTest` using `coEvery` and `coVerify`.
- **MUST** follow explicit AAA phases marked with single-line comments: `// Arrange`, `// Act`, `// Assert`.


## 2. Sequential Execution Lifecycle

### Phase 1: Pre-flight Context Harvesting
Before writing any unit test code, the Host Agent MUST execute this sequential pre-flight:
1. **Extract AST Skeleton**: Run `python3 scripts/extract-target-ast.py <TARGET_FILE>` to harvest constructor dependencies.
2. **Mine Repo Exemplar**: Run `python3 scripts/harvest-exemplars.py <TARGET_FILE>` to identify local assertion DSLs.
3. **Query References (Conditional)**: If target uses complex DTOs, query `scripts/query-reference.sh`.

### Phase 2: Test Scaffolding
- Instantiate dependencies using `private val dep = mockk<Dep>()`.
- Implement clean Arrange-Act-Assert testing structure adhering to mined exemplar conventions.

### Phase 3: Sandboxed Verification & Remediation
1. Trigger validation runner: `bash scripts/run-unit-tests.sh <TARGET_TEST_FILE>`.
2. Inspect exit code:
   - **Exit 0**: Complete. Return test code to user.
   - **Exit 2**: Invariant failure. Purge Mockito or Spring runner immediately.
   - **Exit 3**: Compilation error. Parse line number and type mismatch from stderr.
   - **Exit 4**: Assertion error. Adjust mock stubs or expected values.
   - **Exit 124**: Execution timeout. Purge blocking operations or heavy context loaders.
3. Max Retries: Limit autonomous self-correction loop to 3 iterations.
          

#!/usr/bin/env bash
# ==============================================================================
# scripts/run-unit-tests.sh
# Standard: agentskills Standard v1.0 (Phase 3 Capstone Release)
# Complete Orchestrator: Fast-Fail Static Linter, 45s Timeout Sandbox & Triage
# ==============================================================================
set -euo pipefail

TARGET_FILE="${1:-}"
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
TRIAGE_SCRIPT="${SCRIPT_DIR}/triage-test-failure.py"
LOG_FILE=$(mktemp /tmp/capstone_mvn.XXXXXX.log)

# Safe Cleanup Hook
trap 'rm -f "${LOG_FILE}"' EXIT

# 1. Parameter Verification
if [[ -z "${TARGET_FILE}" ]] || [[ ! -f "${TARGET_FILE}" ]]; then
    echo "### 🚨 DETERMINISTIC TRIAGE REPORT" >&2
    echo "- **Category**: \`ENVIRONMENT_ERROR\`" >&2
    echo "- **Error**: Target test file '${TARGET_FILE}' does not exist or was not specified." >&2
    exit 1
fi

CLASS_NAME=$(basename "${TARGET_FILE}" .kt)

# 2. Stage 1: Fast-Fail Negative Boundary Gate (< 50ms)
if grep -En "org\.mockito" "${TARGET_FILE}" >&2; then
    echo "### 🚨 DETERMINISTIC TRIAGE REPORT" >&2
    echo "- **Category**: \`STATIC_INVARIANT_VIOLATION\`" >&2
    echo "- **Error**: Forbidden Mockito import detected. Pure unit tests MUST use io.mockk." >&2
    exit 2
fi

if grep -En "@SpringBootTest|@DataJpaTest|@WebMvcTest" "${TARGET_FILE}" >&2; then
    echo "### 🚨 DETERMINISTIC TRIAGE REPORT" >&2
    echo "- **Category**: \`STATIC_INVARIANT_VIOLATION\`" >&2
    echo "- **Error**: Spring ApplicationContext runner detected. Unit tests must execute in pure memory." >&2
    exit 2
fi

# 3. Stage 2: Sandboxed Maven Execution with Timeout Guard (Max 45s)
set +e
timeout 45s mvn test -B --no-transfer-progress -Dtest="${CLASS_NAME}" > "${LOG_FILE}" 2>&1
BUILD_STATUS=$?
set -e

if [[ ${BUILD_STATUS} -eq 124 ]]; then
    echo "### 🚨 DETERMINISTIC TRIAGE REPORT" >&2
    echo "- **Category**: \`EXECUTION_TIMEOUT\`" >&2
    echo "- **Error**: Test execution exceeded 45s limit. Potential deadlock or heavy context initialization." >&2
    exit 124
elif [[ ${BUILD_STATUS} -ne 0 ]]; then
    # Pipeline raw noisy log into Python triage parser and output strictly to stderr
    python3 "${TRIAGE_SCRIPT}" "${LOG_FILE}"
    
    if grep -q "Compilation failure" "${LOG_FILE}"; then
        exit 3
    else
        exit 4
    fi
fi

# 4. Success Path: Clean Structured JSON to stdout, zero stderr
echo "{\"status\": \"SUCCESS\", \"class\": \"${CLASS_NAME}\", \"verified\": true}"
exit 0