pi_mcps/zoo_backup/home/skills/mvn-test/SKILL.md

name, description

name	description
mvn-test	Run Maven tests in multi-module projects. Resolves module paths, builds dependencies, parses surefire XML reports, and returns structured pass/fail results. Use when asked to run tests, execute test classes, or verify a module build.

Maven Test & Build Runner

When to use

• Running all tests for a module in a multi-module Maven project
• Running a specific test class or method
• Building a fat JAR for deployment
• Verifying a build after code changes in a worktree
• Troubleshooting Maven dependency/version issues

When NOT to use

• SSH integration tests on remote instances → use a dedicated SSH test skill
• Creating new test files → use Code mode directly
• Running non-Maven tests (npm, etc.)

Required Inputs

Input	Source	Example
TICKET_KEY	Issue key or task ID	PROJECT-123
MODULE	Maven module name	module-a, module-b, persistence
TEST_CLASS	Fully qualified test class (optional)	com.example.service.MyServiceTest

Module Path Resolution

Module name	Maven -pl path
module-a	java/modules/cs-modules/module-a
module-b	java/modules/cs-modules/module-b
nested-module	java/modules/cs-modules/parent-group/nested-module
persistence	java/persistence
shared-lib	java/modules/shared-lib

If the module is not in this table, search for it:

find java/modules -name "pom.xml" -path "*/<MODULE>/*" | head -3

Workflow

1. Determine worktree path

WORKTREE="<your-repo-path>"
# Verify it exists
ls "$WORKTREE/java/pom.xml"

If no worktree exists, fall back to the main repo path

2. Resolve module path

Look up MODULE in the path resolution table above. Store as MODULE_PATH.

3. Run tests

All module tests:

cd <WORKTREE> && mvn test -pl <MODULE_PATH> -am -f java/pom.xml

Specific test class:

cd <WORKTREE> && mvn test -pl <MODULE_PATH> -am -Dtest="<TEST_CLASS>" -Dsurefire.failIfNoSpecifiedTests=false -f java/pom.xml

Specific test method:

cd <WORKTREE> && mvn test -pl <MODULE_PATH> -am -Dtest="<TEST_CLASS>#<methodName>" -Dsurefire.failIfNoSpecifiedTests=false -f java/pom.xml

4. Parse results

Look for these patterns in the output:

Pattern	Meaning
Tests run: N, Failures: F, Errors: E, Skipped: S	Surefire summary
BUILD SUCCESS	All tests passed
BUILD FAILURE	At least one test failed or compilation error
There are test failures	Link to surefire reports

If tests fail, read the surefire report:

find <WORKTREE>/<MODULE_PATH>/target/surefire-reports -name "*.txt" -exec grep -l "FAILURE\|ERROR" {} \;

5. Store results in BigMind

memory_store_fact(
    category="codebase",
    fact=f"{TICKET_KEY}: mvn test {MODULE} — {tests_run} run, {failures} failures, {errors} errors. {'BUILD SUCCESS' or 'BUILD FAILURE'}"
)

Building Fat JARs (for deployment)

Package a module with all dependencies:

cd <WORKTREE> && mvn package -pl :<ARTIFACT_ID> -am -DskipTests -f java/pom.xml -Drevision=1.0.0-TEST -o -q

Locate the built JAR:

find <MODULE_PATH>/target -name "*-jar-with-dependencies.jar" | head -1

Module artifact IDs (for -pl :NAME):

Module	Artifact ID	Fat JAR name
module-a	ModuleA	ModuleA-*-jar-with-dependencies.jar
module-b	ModuleB	ModuleB-*-jar-with-dependencies.jar
persistence	persistence	(no fat JAR)

Use :ARTIFACT_ID with -pl for single-module builds (faster than path-based).

Critical: Version Timestamp Issue

If the project uses a Maven ${revision} timestamp-based SNAPSHOT scheme (e.g. 1.0-DEV-SNAPSHOT-<timestamp>), the snapshot changes every minute; ensure dependent modules are rebuilt in the same run.

Problem: If you mvn install at 07:55 and then mvn test at 07:56, the version changed and artifacts can't be found.

Solutions:

1. Always use -am (also-make) — builds from source, no cached artifacts needed
2. Pin the version: -Drevision=1.0.0-TEST — stable across commands
3. Use -o (offline) — prevents remote lookups that fail on VPN/cert issues
4. Never use -pl without -am for test runs — dependencies won't resolve

Recommended command patterns:

# Compile check (fast)
mvn compile -pl :<ARTIFACT_ID> -am -f java/pom.xml -o -q

# Run specific test (reliable)
mvn test -pl :<ARTIFACT_ID> -am -f java/pom.xml \
  -Dtest="com.example.MyTest" \
  -Dsurefire.failIfNoSpecifiedTests=false \
  -Dmaven.test.skip=false -DskipTests=false \
  -Drevision=1.0.0-TEST -o

# Build fat JAR for deployment
mvn package -pl :<ARTIFACT_ID> -am -DskipTests -f java/pom.xml \
  -Drevision=1.0.0-TEST -o -q

Why -Dmaven.test.skip=false -DskipTests=false?

Some modules have <skipTests>true</skipTests> in their POM or parent POM. These flags override that to force test execution.

Troubleshooting

Problem	Solution
Could not find artifact	Add -am flag to build dependencies first
No tests were executed	Check test class path — use package-relative path, not fully qualified with src/test/java/
Compilation failure in dependency	Run mvn compile -pl <MODULE_PATH> -am -f java/pom.xml first to isolate
OOM during tests	Add -Xmx1g via MAVEN_OPTS: MAVEN_OPTS="-Xmx1g" mvn test ...
Test hangs	Add -Dsurefire.timeout=120 to kill stuck tests after 120s
Tests are skipped	Add -Dmaven.test.skip=false -DskipTests=false
Version mismatch (timestamp)	Pin with -Drevision=1.0.0-TEST
Certificate/SSL error on artifact download	Add -o (offline) — use local sources with -am
No tests matching pattern in dependency modules	Add -Dsurefire.failIfNoSpecifiedTests=false
Wrong module selected by -pl	Use artifact ID (:ModuleA) not path — check with grep '<artifactId>' <MODULE_PATH>/pom.xml