---
name: mvn-test
description: 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:
```bash
find java/modules -name "pom.xml" -path "*/<MODULE>/*" | head -3
```

## Workflow

### 1. Determine worktree path

```bash
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:**
```bash
cd <WORKTREE> && mvn test -pl <MODULE_PATH> -am -f java/pom.xml
```

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

**Specific test method:**
```bash
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:
```bash
find <WORKTREE>/<MODULE_PATH>/target/surefire-reports -name "*.txt" -exec grep -l "FAILURE\|ERROR" {} \;
```

### 5. Store results in BigMind

```python
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:
```bash
cd <WORKTREE> && mvn package -pl :<ARTIFACT_ID> -am -DskipTests -f java/pom.xml -Drevision=1.0.0-TEST -o -q
```

### Locate the built JAR:
```bash
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:

```bash
# 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` |