Agent Testing Loop

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 InteractionApi 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, bootstrap, 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.InteractionApi.* --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.treewoodcutter.* --console plain
.\gradlew.bat test --tests com.n3plugins.tutorialisland.* --console plain

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
Unit test failure	Behavior drift or stale expectation	Reproduce with the focused test, then inspect the changed contract
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
Bootstrap block	Active automation did not register its bootstrap owner, or setup is incomplete	Call requireAccountBootstrap(owner) while active, gate on its return value, and release the owner when idle/stopped
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

Automated tests can prove local contracts. They cannot prove OSRS server state, live widgets, packet delivery, account restrictions, or RuneLite revision behavior. Report those as pending unless you observed them in-client during this change.