| name | starsector-testing |
| description | Guidelines for JUnit, jqwik property-based testing, SpotBugs static analysis, and verification rules. |
Starsector Ship Editor — Testing, Verification & Validation
Skill Directory Structure
This skill is organized as follows:
SKILL.md: Main instructions (this file).resources/: Configurations and templates.
examples/: Code references.
scripts/: Automation.
- run_checks.sh: Helper script to build, test, and perform static analysis.
1. Test Frameworks
| Framework | Version | Scope | Purpose |
|---|
| JUnit Jupiter | 5.10.3 | test | Standard test runner and assertions |
| jqwik | 1.9.0 | test | Property-based testing with random input generation |
Both are executed via maven-surefire-plugin (3.2.5).
2. Existing Test Suite
The test suite is focused on mathematical correctness of utility functions that underpin coordinate transformations and data display. Two test files exist:
UtilityPropertiesTest
UtilityPropertiesTest.java — Property-based tests for core mathematical utilities.
| Property | What It Validates |
|---|
testParseIntegerOrDefault | Utility.parseIntegerOrDefault() returns parsed int for valid strings, default for invalid/empty |
testParseDoubleOrDefault | Utility.parseDoubleOrDefault() returns parsed double for valid strings, default for invalid/empty |
testClampAngleWithRounding | Result is always in [0, 360) for any input in [-1e9, 1e9] |
testFlipAngle | Flipping twice returns the normalized original (within 0.0001 delta) |
testRound | Utility.round(value, decimalPlaces) produces a result for all finite values |
testTransformAngle | Utility.transformAngle() output is always in [-90, 270) |
Why jqwik here: These functions are called thousands of times per frame for coordinate display and point placement. A single edge case (e.g., NaN, negative zero, very large values) would corrupt the viewport or produce nonsensical coordinates. Property-based testing with random inputs catches edge cases that handwritten examples miss.
CoordinatesFormatterPropertiesTest
CoordinatesFormatterPropertiesTest.java — Property-based tests for coordinate rounding.
| Property | What It Validates |
|---|
testRoundMaintainsValue | CoordinatesFormatter.round() produces results within 0.005 of input for normal values, handles NaN and Infinity correctly, and doesn't overflow for very large values |
testRoundPointMaintainsValue | CoordinatesFormatter.roundPoint() preserves NaN propagation for both X and Y |
Quirk — Overflow Guard: The test explicitly handles the case where Math.abs(value) >= Long.MAX_VALUE / 1000.0, because the rounding implementation internally converts to long for fixed-point math. For values exceeding this threshold, the test relaxes the precision requirement to 1% of the input value.
3. What Is NOT Tested (and Why)
No GUI Tests
There are no automated Swing/AWT UI tests. The PrimaryViewer, PaintOrderController, and all painter classes require:
- A live OpenGL context (GPU required)
- A visible X11/Wayland window
- Swing EDT initialization
These are impractical in CI environments. Visual verification is done manually.
No Jackson Parsing Tests
The JsonProcessor.straightenMalformed() pipeline is not unit-tested. This is a gap — the complex regex and character-by-character state machine are prime candidates for property-based testing with fuzzed Starsector JSON inputs.
No Database Tests
DatabaseManager and DatabaseQueryService are not tested in isolation. The schema, PRAGMAs, and query correctness are validated implicitly by the full-application launch test.
4. Static Analysis: SpotBugs
Plugin: spotbugs-maven-plugin 4.8.3.1
Configuration: effort=Max, threshold=Low, xmlOutput=true
This is the strictest possible SpotBugs configuration. It catches:
- Null pointer dereferences
- Unclosed resources (streams, connections)
- Concurrency issues (race conditions, unsynchronized access)
- Mutable object exposure
Annotation-Guided Analysis
The spotbugs-annotations dependency (4.8.3) provides @NonNull, @Nullable, @SuppressFBWarnings, etc.
Deliberate Suppressions (Quirks):
@SuppressFBWarnings({"EI_EXPOSE_REP", "EI_EXPOSE_REP2", "MS_EXPOSE_REP"}) is used extensively on PrimaryViewer, PaintOrderController, UndoOverseer, and DrawUtilities. These classes intentionally expose mutable internal state for performance. SpotBugs would flag every getter that returns a mutable list or map.
5. Build Pipeline as Validation Gate
The command mvn clean package acts as the primary validation gate. It executes:
- Compile — Enforces Java 17 language level. Annotation processors run (Lombok, Log4j2).
- Test — Surefire executes JUnit Jupiter and jqwik tests.
- SpotBugs — Static analysis runs (if configured in a reporting or verify phase).
- Package — JAR creation.
- Shade — Uber-JAR generation with transformer verification.
Shade Plugin Validation (Quirk)
If the Log4j2PluginCacheFileTransformer is missing or misconfigured, the shaded JAR will start but Log4j2 will silently fall back to NullAppender, producing zero log output. This is a silent failure — the application appears to work but cannot be debugged. The transformer merges Log4j2Plugins.dat cache files from all dependencies.
Similarly, if ServicesResourceTransformer is missing, JDBC driver auto-discovery fails and DatabaseManager.getConnection() throws ClassNotFoundException for org.sqlite.JDBC (which is why the explicit Class.forName() fallback exists).
6. Runtime Verification
Manual Launch Test
The editor is launched via:
mvn exec:exec
or directly:
java -Xmx512m -XX:+UseG1GC -XX:+UseStringDeduplication \
-XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 \
-cp <classpath> shipeditor.Main
Verification checklist:
GPU-Specific Quirk
On Linux with multiple GPUs (e.g., integrated + discrete), the editor must use the correct GPU. The DRI_PRIME=1 environment variable or explicit /dev/dri/card0 mapping may be needed to target the discrete GPU for adequate OpenGL 3.3 support.
7. .jqwik-database
A .jqwik-database file exists in the project root. This is jqwik's internal database for tracking which random seeds have been tested and which have found failures. It enables shrinking (finding minimal failing inputs) and replay (re-running previously failing seeds). The file is currently 4 bytes, indicating minimal or no persisted failure history.
8. Compiler and IDE Warning Resolutions
When writing and refactoring Java code, adhere to these conventions to keep the build completely warning-free:
Null pointer warnings on conditional check variables (false-positives)
Avoid saving state to a boolean variable before performing null checks. Static analyzers (like Eclipse/ECJ) fail to link the boolean state to the null state of the original object.
- Bad:
boolean present = selected != null && selected.getPainter() != null;
if (!present) return;
selected.getPainter().doSomething();
- Good:
if (selected == null || selected.getPainter() == null) return;
selected.getPainter().doSomething();
Autoboxing/Unboxing type safety in generic Consumers
When passing method references to generic containers/spinners that expect wrapper types (e.g. Consumer<Integer> or Consumer<Boolean>), do not use method references targeting primitives (e.g. void setFluxVents(int)). This triggers "Null type safety" warnings under strict ECJ compilation. Use lambdas with explicit null-safe defaults instead.
- Bad:
ventsSpinner.enableSpinner(layer, variant.getFluxVents(), maxVents, variant::setFluxVents);
- Good:
ventsSpinner.enableSpinner(layer, variant.getFluxVents(), maxVents, val -> variant.setFluxVents(val != null ? val : 0));
Redundant Suppressions
Avoid leaving @SuppressWarnings("unused") or similar compiler overrides on classes/methods unless there is a specific, active reason to silence a compiler error. Redundant suppressions cause ECJ warnings about unused annotations.
