---
name: build-and-test
description: Build/test commands, and unit testing key points including BugLog handling guidelines.
---

# 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:

1. **If IntelliJ-IDEA MCP is available** (recommended): Use it for accurate code analysis and building. See the [idea-mcp skill](../idea-mcp/SKILL.md) for usage instructions.
2. **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

1. **BugLog state is global** - One test not resetting BugLog causes ALL subsequent tests to fail
2. **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
3. **Not all time adjustments trigger BugLog** - Only operations that cause "nanoTime go back" or other error conditions trigger BugLog
4. **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

```java
@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](references/project-structure.md) for module details.