integration-test-verification

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

1. Identify the changed feature and affected server bands.
2. Prefer the narrowest version set that covers the compatibility boundary.
3. If the change touches packet handling, include a modern PacketEvents-covered version.
4. If the change touches legacy behaviour or Java 8 APIs, include 1.12 where practical.
5. 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.