Runtime Diagnostics
Maven Test Failure Debugging Guide
Debug Maven Surefire and Failsafe failures by separating test discovery, forked JVM crashes, environment drift and integration-test lifecycle issues. This reference is written for developers who need practical validation behavior, reviewable rules and safe examples rather than copied snippets with no explanation.
Recommended workflow
| Step | Why it matters |
|---|---|
| Classify the phase | Confirm whether Surefire unit tests or Failsafe integration tests are failing. |
| Run one test | Reproduce the smallest class or method while preserving the same profile and JVM options. |
| Inspect reports | Read XML, text reports and dump files before relying on the final Maven summary. |
| Compare environments | Check JDK, locale, timezone, ports, services and parallel execution between local and CI runs. |
Starter snippet
mvn -e -X -Dtest=ClassName#method testReview checks
- Keep plugin versions explicit.
- Capture forked-process exit codes.
- Avoid shared mutable test data.
- Run integration verification through the verify phase.
Common mistakes
- Adding unlimited retries to flaky tests.
- Running failsafe tests with only the test phase.
- Deleting reports before examining JVM dump files.
Validation should help users correct input while protecting systems from bad data. Keep syntax checks, product policy, security review and deliverability checks separate.
Related Formalint references
Continue with Java Maven Dependency Debugging, Ci Failing Tests Debugging Guide, Java Thread Dump Guide.