feat: archive zoo_backup for home sync
This commit is contained in:
Patrick Plate
@@ -0,0 +1,173 @@
|
||||
---
|
||||
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` |
|
||||
Reference in New Issue
Block a user