springboot-verification

Spring Boot Verification Protocol

This is the PRIMARY FEEDBACK LOOP. You run these commands yourself via Bash, read the full output, diagnose using the patterns below, fix, and repeat.

Quality Gate Thresholds (ENFORCED)

Gate	Threshold	Status
Compile	0 errors	REQUIRED
Tests	100% pass (0 failures, 0 errors)	REQUIRED
Coverage	≥ 80% line coverage	REQUIRED
Checkstyle	0 violations	REQUIRED
Build Verify	mvn verify passes	REQUIRED

⛔ BLOCKING: Any gate failure blocks completion. No exceptions.

The Verification Cycle

┌─────────────────────────────────────────────────────────────┐
│  1. COMPILE                                                  │
│     Run: mvn compile -B                                      │
│     Read: FULL output                                        │
│     ⛔ GATE: 0 errors required                               │
│     If errors → go to Error→Fix table → fix → restart       │
│                                                              │
│  2. TEST                                                     │
│     Run: mvn test -B                                         │
│     Read: FULL output                                        │
│     ⛔ GATE: 0 failures, 0 errors required                   │
│     If failures → go to Error→Fix table → fix → restart     │
│                                                              │
│  3. CHECKSTYLE                                               │
│     Run: mvn checkstyle:check -B                             │
│     Read: FULL output                                        │
│     ⛔ GATE: 0 violations required                           │
│     If violations → fix style issues → restart               │
│                                                              │
│  4. COVERAGE ⚠️ MANDATORY                                    │
│     Run: mvn test jacoco:report -B                           │
│     Check: target/site/jacoco/index.html                     │
│     Parse: target/site/jacoco/jacoco.xml for exact %         │
│     ⛔ GATE: ≥ 80% line coverage required                    │
│     If < 80% → Add more tests → Re-run → Repeat              │
│     ⛔ Do NOT proceed if coverage < 80%                      │
│                                                              │
│  5. VERIFY                                                   │
│     Run: mvn verify -B                                       │
│     Confirms full build including integration tests          │
│     ⛔ GATE: Must pass                                       │
│                                                              │
│  ✓ ALL GATES PASS → VERIFICATION PASSED → May proceed       │
│  ✗ ANY GATE FAILS → VERIFICATION FAILED → Must fix first    │
└─────────────────────────────────────────────────────────────┘

Error→Fix Pattern Table

Compile Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic Command
cannot find symbol	Missing import or typo	Check class name spelling, add import	grep -r "class ClassName" src/
package does not exist	Missing dependency	Add dependency to pom.xml	Check pom.xml dependencies
incompatible types	Type mismatch	Check return types, use correct type	Read method signature
method does not override	Wrong signature	Match parent method exactly	Read parent class/interface
unreported exception	Uncaught checked exception	Add try-catch or throws clause	Read exception hierarchy
cannot access	Visibility issue	Change to public or add getter	Check access modifiers
constructor not found	Wrong constructor args	Match constructor signature	Read class definition

Bean/DI Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic Command
No qualifying bean of type	Missing @Component/@Service/@Repository	Add appropriate annotation	grep -r "@Service|@Component|@Repository" src/
BeanCreationException	Bean initialization failed	Check constructor, dependencies	Read full stack trace for cause
UnsatisfiedDependencyException	Cannot autowire dependency	Check if dependency bean exists	grep -r "class DependencyName" src/
Circular dependency	A→B→A injection cycle	Use @Lazy or refactor	Trace dependency chain
NoUniqueBeanDefinitionException	Multiple beans match	Use @Primary or @Qualifier	grep -r "@Bean.*TypeName" src/
BeanCurrentlyInCreationException	Circular reference	Break cycle with @Lazy	Check constructor injection

Test Failures

Error Pattern	Root Cause	Fix Strategy	Diagnostic Command
NullPointerException at mock	Mock not injected	Check @Mock/@MockBean, verify setup	Read test class annotations
404 Not Found in MockMvc	Wrong path or missing controller	Check @RequestMapping path	grep -r "@RequestMapping|@GetMapping" src/
Wanted but not invoked	Method never called	Check test logic, verify conditions	Debug test flow
Argument(s) are different	Mock called with wrong args	Check argument values	Use ArgumentCaptor
expected:<X> but was:<Y>	Assertion failed	Check logic, fix implementation	Compare expected vs actual
Strict stubbing argument mismatch	Wrong args to when()	Use any() or exact matcher	Check mock setup
UnnecessaryStubbingException	Unused stub	Remove unused when() or use lenient()	Review test setup

Database Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic Command
PSQLException: Connection refused	DB not running	Start PostgreSQL	pg_isready -h localhost
PSQLException: Connection timeout	Pool exhaustion	Reduce maxPoolSize	Check hikari config
DataIntegrityViolationException	FK/unique constraint	Check test data, verify refs exist	Read migration files
BadSqlGrammarException	SQL syntax error	Fix query syntax	Read the SQL in error
EmptyResultDataAccessException	Expected 1, got 0	Handle with Optional	Use queryForObject correctly
IncorrectResultSizeDataAccessException	Expected 1, got many	Add LIMIT or fix query	Check query conditions
CannotGetJdbcConnectionException	No available connections	Check pool size, close connections	Check HikariCP metrics

Validation Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic Command
ConstraintViolationException	@Valid failed	Check DTO annotations vs test data	Read DTO validation annotations
MethodArgumentNotValidException	Request body invalid	Add missing @Valid or fix test data	Check controller parameter
HttpMessageNotReadableException	JSON parse failed	Check JSON structure matches DTO	Compare JSON vs DTO fields
MissingServletRequestParameterException	Required param missing	Add param to request or make optional	Check @RequestParam

Connection Pool Errors

Error Pattern	Root Cause	Fix Strategy	Diagnostic Command
Connection is not available	Pool exhausted	Check sizing: maxPoolSize × pods < max_connections	Check application.yml hikari settings
Connection timeout	Slow queries holding connections	Add query timeout, check N+1	Enable slow query log
Connection closed	Connection leaked	Close resources in finally/try-with-resources	Check JDBC code

Diagnostic Commands

When an error occurs, run these to gather more information:

# Find missing class
grep -r "class ClassName" src/

# Find missing annotation
grep -r "@Service\|@Component\|@Repository" src/main/java/

# Find controller mappings
grep -r "@RequestMapping\|@GetMapping\|@PostMapping" src/

# Check test output details
mvn test -Dtest=SpecificTest#specificMethod -X

# Check dependency tree
mvn dependency:tree

# Check effective POM
mvn help:effective-pom

# Run single test with full output
mvn test -Dtest=TodoControllerTest#should_return404_whenTodoNotFound -X

# Check for compilation errors only
mvn compile -X 2>&1 | head -100

Max Retry Rule

After 3 attempts at fixing the SAME error:

1. Summarize what you've tried
2. Show the error output
3. Ask the developer for guidance

Do NOT:

• Keep trying the same fix
• Silently skip the failing test
• Lower quality thresholds
• Declare "done" with failures
• Comment out failing assertions