Agent Testing Loop

Verification boundary

Static validation does not certify revision-sensitive RuneLite UI, packet, or in-game outcomes; treat those as live-client verification pending unless the page records direct evidence.

Use this loop after docs, prompts, SDK, plugin, widget, walker, workflow, or state-machine changes. Run the narrowest check that can catch the risk, then broaden.

Validation Ladder

1. Static sanity: inspect diff and scan for stale paths, bad docs links, generated artifacts, and accidental broad rewrites.
2. Focused tests: run the package or class touched by the change; Gradle compiles its source dependencies.
3. Compile-only: run .\gradlew.bat compileJava --console plain only when no selected test or verification task compiles the changed source.
4. API coverage: run .\gradlew.bat test --tests com.n3plugins.ApiJavadocCoverageTest --console plain when public declarations under Api or sdk change.
5. Full tests: .\gradlew.bat test --console plain when shared behavior changed.
6. Build and jar checks: run .\gradlew.bat build --console plain once when resources, registration, packaging, or public API changed. build owns full tests, normal/fat-jar assembly, and packaging tests.
7. Live client: verify RuneLite behavior when widgets, packets, GE, movement, combat, branding, or revision-sensitive flows changed.

Docs-only changes usually need compile only when examples or prompt instructions mention source symbols that could drift. Otherwise run link/catalog checks and inspect the diff.

Focused Commands

.\gradlew.bat test --tests com.n3plugins.Api.* --console plain
.\gradlew.bat test --tests com.n3plugins.sdk.* --console plain
.\gradlew.bat test --tests com.n3plugins.ApiJavadocCoverageTest --console plain
.\gradlew.bat test --tests com.n3plugins.PacketUtils.* --console plain
.\gradlew.bat test --tests com.n3plugins.marketalcher.* --console plain
.\gradlew.bat test --tests com.n3plugins.tutorialisland.* --console plain

Tutorial Island changes that touch transition IDs, setup widgets, bank/poll behavior, settings, loop priority, or recovery must also update and validate:

`docs/_internal/tutorial-island.md`
`docs/_internal/tutorial-island-transition-catalogue.md`
current revision validation evidence under `docs/validation/` (use `tutorial-island-rev239.md` only as historical baseline)

Static tests do not promote a catalogue row to LIVE_VERIFIED; record the observed live postcondition in the revision matrix.

See Agentic Testing Loop Internals for the Windows launcher and hidden-wrapper contract. The latest Tutorial Island replay evidence is Tutorial Island live run - 2026-07-28.

Use the SOT validation section for the current full command set.

Evidence To Capture

For local validation:

• Command.
• Exit result.
• Failing test names or compiler errors.
• Changed files inspected.
• Diff risk that remains.

For live RuneLite validation:

• Client revision and plugin version.
• Starting account state and location.
• Plugin config.
• Expected action sequence.
• SuiteRuntimeStatus.snapshot() when relevant.
• WidgetExplorer output for widget-sensitive failures.
• PacketTrace summary when packet sends matter.
• Screenshot or log tail when it helps explain the state.
• Clear note that server and client state can still change outcomes.

Failure Taxonomy

Failure	Likely cause	Next step
Compile error	Signature drift, import mismatch, Java 11 violation	Read the live source, fix the smallest mismatch
Mockito setup failure	Inline/static mocking, mock created inside thenReturn(...), final class issue	Refactor to injected collaborators or assign mocks to locals first
Widget miss	Hidden widget, wrong group/child, text tag mismatch, client revision drift	Use WidgetExplorer, require visibility, and compare against live UI
Pacing stall	Driver consumes ActionPacer, missing recordAction, or double tick owner	Re-check PacketUtilsPlugin ownership and action-layer pacing
Walker stall	Plugin owns walker tick, stale route, missing transport requirement, unreachable target	Inspect WalkerPath status and shared walker docs
Packet/runtime mismatch	Client revision or obfuscated mapping drift	Run revision health checks and verify in-client
Docs mismatch	SOT or source changed after prose was written	Re-read source and update docs/catalog together

Iteration Limits

Fix one root cause per loop. If the same validation fails three times, stop and write the current evidence, suspected cause, and next options. Do not stack speculative fixes.

Live Verification Boundary

Without an attached authenticated RuneLite/OSRS client, report Live client verification: pending. Unit tests can prove deterministic routing, action priority, selectors, retry policy, and postcondition predicates; they cannot prove that the current game exposes the expected object, widget, menu action, route, timing, morph, or destination state.