tomevault-io Build and Test
This skill provides commands and patterns for building and testing the Dongting project.
Quick Reference
Build Commands
| Command | Purpose |
|---|---|
mvn clean package -DskipUTs |
Full build (skips unit tests) |
mvn clean package -DskipUTs -PminimalDist |
Minimal dist (no slf4j/logback) |
mvn clean package -DskipUTs -PaddJRE |
Dist with trimmed JRE (jlink) |
mvn clean package -DskipUTs -PminimalDist,addJRE |
Minimal dist with trimmed JRE (no slf4j/logback/java.xml) |
mvn clean compile test-compile |
Compile with protobuf |
Unit Testing
| Command | Purpose |
|---|---|
mvn clean test -Dtick=3 |
Run all unit tests, takes about 25 seconds to run. It is recommended to redirect to a temporary file, as the large amount of output will be truncated otherwise. |
mvn -pl module -am test -Dtest=ClassName -Dtick=3 -Dsurefire.failIfNoSpecifiedTests=false |
Run single test class |
mvn -pl module -am test -Dtest=ClassName#method -Dtick=3 -Dsurefire.failIfNoSpecifiedTests=false |
Run single test method |
Tip: Use -Dtick=3 to increase test stability.
Integration Testing
| Command | Purpose |
|---|---|
mvn verify -DskipUTs -Dtick=3 |
Run all integration tests, takes about 100 seconds to run. It is recommended to redirect to a temporary file, as the large amount of output will be truncated otherwise. |
mvn -pl it-test -am verify -DskipUTs=true -Dit.test=ClassName -Dtick=3 |
Run single integration test |
Note: Package must be completed before running integration tests. After modifying code, always run mvn clean package -DskipUTs first.
Compilation Notes
Due to the project's complex build process (multiple compilation phases in pom.xml, protobuf compilation), Java LSP may frequently show compilation errors. Use the following approach:
- If IntelliJ-IDEA MCP is available (recommended): Use it for accurate code analysis and building. See the idea-mcp skill for usage instructions.
- Otherwise (e.g., IDEA not running): Use Maven commands directly.
BugLog in Unit Tests
The project uses BugLogExtension to check BugLog state after each test. If BugLog was triggered, the test fails with "BugLog count should be 0".
Key Points
- BugLog state is global - One test not resetting BugLog causes ALL subsequent tests to fail
- Only fix the FIRST failing test - When multiple tests fail due to BugLog, find and fix only the first one; the others will pass automatically
- Not all time adjustments trigger BugLog - Only operations that cause "nanoTime go back" or other error conditions trigger BugLog
- Reset immediately after the triggering code - Don't wrap the entire test in try-finally; reset right after the code that triggers BugLog
When to Reset BugLog
Reset BugLog only in tests that intentionally trigger error conditions:
- Tests that call
TestUtil.updateTimestamp()to simulate time passage (may cause "nanoTime go back") - Tests that intentionally create invalid states to test error handling
- Tests that throw mock exceptions to test retry logic
Example
@Test
void testLockExpiration() {
// ... test code ...
TestUtil.updateTimestamp(ts, ts.nanoTime + 100_000_000L, ts.wallClockMillis + 100);
// ... operations that cause Timestamp.refresh() or update() to detect "nanoTime go back" ...
// The time adjustment + subsequent operations trigger BugLog
BugLog.reset();
// ... more test code ...
}
Rules
- DO reset immediately after the code that triggers BugLog
- DO add a brief comment explaining why BugLog might be triggered
- DO NOT reset in
@BeforeEach/@AfterEach/@BeforeAll/@AfterAll- this hides problems - DO NOT reset in test base classes
- DO NOT wrap entire test methods in try-finally just for BugLog.reset()
Build Requirements
- Java version: Java 11 for server, Java 8 for client module
- Build tool: Maven
- Module structure: Multi-module Maven project
See project-structure.md for module details.
Source: dtprj/dongting — distributed by TomeVault.