diagnose

name	diagnose
description	Use when a test fails and you need to diagnose the root cause. Run the test, read errors, trace through generated and source code, fix, and verify.
allowed-tools	Bash(./mvnw:*), Bash(javap:*), Bash(unzip:*), Bash(grep:*)

Diagnose Test Failure

Overview

Systematic diagnosis of test failures in the Morphia project. Run the test, read the full error, trace the root cause through source and generated code, fix minimally, and verify.

Workflow

1. Run the failing test

   ./mvnw test -pl :module-name -Dtest="ClassName#methodName" -Ddeploy.skip=true
   

   • Use -Ddeploy.skip=true to skip dokka
   • Do NOT use -am with -Dtest= (applies test filter to all modules)
   • If dependencies need rebuilding first:

     ./mvnw install -pl :dep1,:dep2 -DskipTests -Ddeploy.skip=true -Dinvoker.skip=true
     

2. Read the full error - stack trace, error message, line numbers. Don't skip anything.

3. Find relevant code - Read both source AND generated code:

   • Source: src/main/, src/test/
   • Generated bytecode: target/test-classes/ - use javap -c -p ClassName to decompile
   • Generated sources: target/generated-sources/
   • Interfaces from dependencies: check ~/.m2/repository/ source jars with unzip -p

4. Trace the root cause - Follow the error backward:

   • What method is missing/wrong?
   • What generated it? (Gizmo generator? ASM generator?)
   • What does the interface/superclass require?
   • Compare with working examples (ASM-based generators have bridge methods; check if Gizmo-based ones do too)

5. Fix minimally - One change at a time. Rebuild affected modules:

   ./mvnw install -pl :critter-core,:critter-maven -DskipTests -Ddeploy.skip=true -Dinvoker.skip=true
   

6. Verify - Re-run the failing test AND related tests in the same class.

Common Morphia/Critter Issues

Error	Likely Cause
AbstractMethodError	Missing bridge methods in generated bytecode (generic interface erasure)
Cannot checkcast to primitive	Gizmo checkCast doesn't work on primitives - use smartCast
Cannot convert primitive to Object	Need boxing: smartCast(result, wrapperType)
NoSuchMethodError __read*/__write*	Accessor methods not generated on entity class
ClassNotFoundException __morphia.*	Critter code generation didn't run or class not registered

Key Gotchas

• Gizmo does NOT auto-generate bridge methods for generic interfaces
• Primitive types need explicit boxing/unboxing via smartCast
• checkCast(Object -> wrapper) then smartCast(wrapper -> primitive) for unboxing
• smartCast(primitive -> wrapper) for boxing
• Always check both Gizmo (parser/gizmo/) and ASM (parser/asm/) generators for patterns