| name | integration-test-verification |
| description | Use when running, selecting, authoring, or triaging integration tests, Kotest specs, Gradle matrix tasks, FakePlayer-backed test cases, or compact test-result files; do not use for unrelated production-only edits, release publishing, or general PR prose. |
Integration Test Verification
Use this skill for the repository's Paper-backed integration-test harness and for deciding how to validate a change without opening large server logs by default.
When to use
- Selecting
./gradlew integrationTest versus a version-limited matrix run.
- Adding or changing Kotlin integration tests under
src/integrationTest/kotlin.
- Registering a new spec in
KotestRunner.
- Triaging
checkTestResults<version> output or plugins/OldCombatMechanicsTest/test-failures.txt.
- Reasoning about tests that use
FakePlayer, synthetic Bukkit events, PacketEvents wrappers, or direct module handler calls.
When not to use
- Do not use for release asset, Hangar, CurseForge, or licence checks; use
release-readiness-review.
- Do not use for module assignment or config migration design unless the task is specifically about test coverage; use
module-config-change.
- Do not use for broad Java 8/NMS design unless the immediate question is test-harness behaviour; use
compatibility-strategy.
Non-negotiable rules
- Root and user-facing agents must not read
build/integration-test-logs/*.log directly; log inspection is allowed only by subagents, and only when needed for integration-test triage or when explicitly requested.
- Prefer compact console output and
plugins/OldCombatMechanicsTest/test-failures.txt first for failure triage.
- Do not disable, skip, weaken, or version-gate tests as a way to make validation pass. Fix the root cause, or report the failure as a blocker unless the user explicitly approves a coverage reduction.
- New integration specs must be added to
KotestRunner.withClasses(...); autoscan is disabled.
- Keep paths relative to the repository root, plugin data folder, or server run directory.
- Avoid starting servers for documentation-only or opencode-config-only changes.
Harness quick reference
- Full matrix:
./gradlew integrationTest.
- Selected matrix:
./gradlew integrationTest -PintegrationTestVersions=1.19.2,1.21.11,1.12.
- Wrapper helper:
scripts/run-integration-matrix.sh -v 1.19.2,1.21.11 [-s '*SpecName*'] [-t '*test name*'] keeps Gradle and Kotest filter arguments consistent.
- Compact result summary:
scripts/summarise-integration-results.sh reads only run/*/plugins/OldCombatMechanicsTest/test-results.txt and test-failures.txt; it does not open full server logs.
- Matrix suggestion helper:
scripts/suggest-integration-matrix.sh [changed-path ...] gives a conservative starting point for versions and filters.
- Individual task names follow
integrationTest<version> with punctuation mapped to underscores, for example integrationTest1_19_2.
- Test plugin entrypoint:
kernitus.plugin.OldCombatMechanics.OCMTestMain.
- Success handoff:
plugins/OldCombatMechanicsTest/test-results.txt contains PASS.
- Failure summary:
plugins/OldCombatMechanicsTest/test-failures.txt contains a compact list, capped for CI readability.
- Java 11+ server targets use Kotest 6 (
KotestRunner, KotestProjectConfig).
- Java 8 targets use
LegacyTestRunner, currently only a smoke path.
Validation selection template
- Identify the changed feature and affected server bands.
- Prefer the narrowest version set that covers the compatibility boundary.
- If the change touches packet handling, include a modern PacketEvents-covered version.
- If the change touches legacy behaviour or Java 8 APIs, include
1.12 where practical.
- If the change is documentation or opencode-only, run filesystem/schema checks rather than server tests.
Example recommendation:
Run: ./gradlew integrationTest -PintegrationTestVersions=1.19.2,1.21.11
Reason: covers modern Paper plus the PacketEvents path affected by the change.
Avoid: opening build/integration-test-logs from a root or user-facing agent; use a subagent only when compact failure output is insufficient or log inspection is explicitly requested.
Known shortcut patterns
Some tests intentionally exercise module code without fully realistic gameplay plumbing:
GoldenAppleIntegrationTest, OldPotionEffectsIntegrationTest, OldArmourDurabilityIntegrationTest, PlayerKnockbackIntegrationTest, SwordBlockingIntegrationTest, and SwordSweepIntegrationTest use synthetic events in places.PlayerKnockbackIntegrationTest and SwordSweepIntegrationTest directly invoke module handlers.- Packet cancellation tests construct and dispatch PacketEvents events directly for deterministic coverage.
Treat these shortcuts as design choices unless the task asks for end-to-end realism.
References
- Historical integration and regression notes:
references/relocated-agents-notes.md.
