Skip to main content

Validation

Verification boundary

This page documents the committed source. Treat revision-sensitive RuneLite UI, packet, or in-game outcomes as pending live-client verification unless the page records direct evidence.

Run validation from the n3plugins repo root. N3PLUGINS_SOURCE_OF_TRUTH.md owns the full canonical command list; this page keeps the common validation flow and jar checks.

Choose commands for the shell that you are actually running. The repository target is Java 11 and the wrapper pins Gradle 8.5. In cloud workspaces, verify those versions before a Gradle task; use the wrapper after downloading it.

Common validation​

Windows PowerShell​

.\gradlew.bat test --tests com.n3plugins.Api.debug.* --console plain
.\gradlew.bat test --tests com.n3plugins.sdk.query.* --console plain
.\gradlew.bat build --console plain

Linux / Cloud Workspaces​

./gradlew test --tests 'com.n3plugins.Api.debug.*' --console plain
./gradlew test --tests 'com.n3plugins.sdk.query.*' --console plain
./gradlew build --console plain

Focused tests compile their source dependencies. The aggregate build task owns the full test suite, normal and fat jars, and packaging-only tests, so do not schedule standalone compileJava, test, or FatJar alongside it.

Shortest-path resource cache​

Walker tests and the aggregate build read the same external resource cache that the Packet Utils-owned shortest-path runtime initializes. We intentionally do not package the large collision, transport, and destination files in the jar. On a clean Linux/cloud workspace environment, populate the cache from the exact SHA pinned by VendorResourceDownloader before running those tests:

UPSTREAM_SHA="$(sed -n 's/^upstreamSha=//p' src/main/resources/com/n3plugins/sdk/walker/shortestpath/vendor.properties)"
CACHE_DIR="$HOME/.runelite/n3Plugins/shortestpath"
TEMP_DIR="$(mktemp -d)"
curl --fail --location --retry 3 -o "$TEMP_DIR/shortest-path.zip" \
  "https://github.com/Skretzo/shortest-path/archive/${UPSTREAM_SHA}.zip"
unzip -qq "$TEMP_DIR/shortest-path.zip" \
  "shortest-path-${UPSTREAM_SHA}/src/main/resources/collision-map.zip" \
  "shortest-path-${UPSTREAM_SHA}/src/main/resources/transports/*" \
  "shortest-path-${UPSTREAM_SHA}/src/main/resources/destinations/*" \
  -d "$TEMP_DIR/extracted"
mkdir -p "$CACHE_DIR"
cp -a "$TEMP_DIR/extracted/shortest-path-${UPSTREAM_SHA}/src/main/resources/." "$CACHE_DIR/"
touch "$CACHE_DIR/version-${UPSTREAM_SHA}.txt"
rm -rf "$TEMP_DIR"

This is environment preparation only: do not add the extracted files to src/main/resources, commit them, or alter the pinned SHA merely to make a build pass. The runtime downloader and resource cache remain the authority; see walker.md.

Walker transport validation​

For imported transport dispatch, context lookup, handler state, or shortcut recovery changes, run the focused transport tests before the broader walker suite:

.\gradlew.bat test --tests com.n3plugins.sdk.walker.PluginTransportActionResolverTest --tests com.n3plugins.sdk.walker.NpcWalkerActionTest --tests com.n3plugins.sdk.walker.CanoeWalkerActionTest --console plain
.\gradlew.bat test --tests com.n3plugins.PacketUtils.PacketUtilsConfigTest --tests com.n3plugins.PacketUtils.logging.IssuedActionClipboardTest --console plain
.\gradlew.bat test --tests com.n3plugins.sdk.walker.* --console plain
./gradlew test --tests com.n3plugins.sdk.walker.PluginTransportActionResolverTest --tests com.n3plugins.sdk.walker.NpcWalkerActionTest --tests com.n3plugins.sdk.walker.CanoeWalkerActionTest --console plain
./gradlew test --tests com.n3plugins.PacketUtils.PacketUtilsConfigTest --tests com.n3plugins.PacketUtils.logging.IssuedActionClipboardTest --console plain
./gradlew test --tests 'com.n3plugins.sdk.walker.*' --console plain

These commands verify source-level dispatch and deterministic state behavior; they do not replace the live acceptance checklist in walker-transports.md.

Focused regression suites​

.\gradlew.bat test --tests com.n3plugins.Api.* --console plain
.\gradlew.bat test --tests com.n3plugins.walkassistant.* --console plain
.\gradlew.bat test --tests com.n3plugins.dialoguehelper.* --console plain
.\gradlew.bat test --tests com.n3plugins.muleplugin.* --console plain
.\gradlew.bat test --tests com.n3plugins.codeconsole.* --console plain
.\gradlew.bat test --tests com.n3plugins.marketalcher.* --console plain
.\gradlew.bat test --tests com.n3plugins.combatawareness.* --console plain
.\gradlew.bat test --tests com.n3plugins.guardiansrift.* --console plain
.\gradlew.bat test --tests com.n3plugins.gebuyer.* --console plain
.\gradlew.bat test --tests com.n3plugins.fighter.* --console plain
.\gradlew.bat test --tests com.n3plugins.tutorialisland.* --console plain
.\gradlew.bat test --tests com.n3plugins.questingassistant.* --console plain
.\gradlew.bat test --tests com.n3plugins.inventorysetups.* --console plain
.\gradlew.bat test --tests com.n3plugins.autolooter.* --console plain
.\gradlew.bat test --tests com.n3plugins.bankstander.* --console plain
.\gradlew.bat test --tests com.n3plugins.javashell.* --console plain
.\gradlew.bat test --tests com.n3plugins.PacketUtils.N3PluginListBrandingTest --tests com.n3plugins.ui.brand.N3BrandingTest --console plain

On Linux/cloud workspaces, replace .\gradlew.bat with ./gradlew and retain the same task and test selectors. Do not run the Windows wrapper from a Linux shell.

Documentation checks​

Run the documentation checks after changing docs, sidebars, public SDK/API references, or generated documentation inputs:

./gradlew auditDocs checkDocDrift --console plain
npm --prefix docs-site run build

auditDocs checks every page under docs/ for frontmatter, navigation, local links, anchors, and MDX hazards. checkDocDrift compares documented fully qualified SDK/API names and stable IDs with the generated source index. The Docusaurus build renders the complete site and catches route or MDX regressions. On Windows, use .\gradlew.bat for the Gradle commands.

Packaging-only validation without the broader build lifecycle:

.\gradlew.bat packagingTest --console plain

Jar inspection:

jar tf build\libs\n3Plugins-5.5-all.jar | Select-String "runelite-plugin.properties|com/n3plugins/sdk|com/n3plugins/PacketUtils|com/n3plugins/Api"
jar tf build\libs\n3Plugins-5.5.jar | Select-String "com/n3plugins/ui/brand/n3.png"

Required entries:

  • runelite-plugin.properties
  • com/n3plugins/PacketUtils/PacketUtilsPlugin.class
  • com/n3plugins/PacketUtils/N3PluginListBranding.class
  • com/n3plugins/sdk/client/N3Client.class
  • com/n3plugins/Api/actions/BankActions.class
  • com/n3plugins/ui/brand/n3.png
  • com/n3plugins/ui/brand/N3Branding.class
  • each native user-facing plugin class listed in runelite-plugin.properties

Notes:

  • Offline validation depends on the local Gradle/RuneLite dependency cache.
  • Packet Utils is the only required shared enabled companion plugin.
  • User-facing n3 plugins are native manifest entries, not loader-managed child modules.
  • Plugin-list image branding still needs live RuneLite validation for refresh/search/open/close behavior, tooltips, and pinned plugin state.
  • Shared amber UI visual validation should cover at least one N3PluginPanel such as Market Alcher.

Manual Verification Checklist​

The following items are revision-sensitive and require direct in-client observation on RuneLite:

The Live Interaction Test Catalogue maintains the complete executable coverage inventory for widgets, interfaces, tabs, menu actions, packet families, enum-backed destinations, and plugin-owned UI assumptions.

  • Packet Utils: Verify the plugin starts successfully on target revision, bootstrap reaches ready state (fixed view mode, high-action warning threshold adjusted, level-up messages disabled).
  • Packet Mappings: Controlled packet tests for mouse clicks, movements, widgets, objects, NPCs, players, ground items, dialogues, and sailing.
  • Native Menu Resolution: On a standard client without a custom Client.menuAction mixin, verify a cold-cache CC_OP, a cache-hit restart, stale-revision invalidation, and WIDGET_CLOSE. Follow menu-action-dispatch.md.
  • Client/Vanilla Correlation: Confirm vanilla vs injected gamepack checks on revision updates.
  • Plugin Registry: Ensure each registered n3 plugin loads in the RuneLite plugin panel list without needing the loader.
  • Branding Assets: Verify the bundled amber branding icon replaces the legacy [n3] prefix at runtime without refresh anomalies or duplications.
  • Shared Amber UI: Inspect N3PluginPanel headers to confirm consistent theme style, status layouts, and action pills.
  • Isolation Rules: Test that toggling or configuring one plugin does not impact independent modules.
  • Walker Engine: Check Shortest Path routing settings, path overlays, POH options, modern transport row executions, and destination-side gangplank recovery in the live client. Confirm a failed crossing makes at most one disembarkation attempt before replanning.
  • Walk Assistant: Confirm the sidebar bank/city buttons, hotkeys, cancel navigation, Shortest Path Set Target/Start Path flow, and ownership-safe path replacement.
  • Dialogue Helper: Automated spacebar continue and Quest Helper [N] dialogue option parsing.
  • Questing Assistant: Verify automation flows for dialogue steps, NPC trades, object picking, item routing, and recovery from an NPC/object/navigation walking failure while the player remains on a vessel. Confirm the controller attempts one nearby disembarkation for the active step and does not enter a repeated two-tick failure loop.
  • Mule Plugin: Validate authenticated RuneLite Party synchronization, trade requests, and secure item exchanges.
  • Combat Awareness: Reminders, re-attacks, and humanizer anti-ban gestures.
  • Code Console: Run controlled command DSL scripts from the Swing panel and verify queued steps, stop behavior, and output.
  • Java Shell: Groovy evaluator startup, RuneLite/n3 API bindings, editor autocomplete, output capture, and client-thread execution.
  • Agent Server API: Test tool discovery (n3_describe_api), tool execution logs, config updates, live screenshots, and MCP actions.
  • SDK Query/API Mappings: Confirm widget and item states, production quantifiers, Grouping minigame parameters, and camera calculations.
  • Fighter Plugin: Profile setups, combat anchors, loadout matching, loot priority, and health thresholds.
  • Market Alcher: GE reconciliation, nature restocks, target browser updates, and pricing buffers. Start with an eligible fire staff in inventory while another side tab is selected; confirm the plugin opens Inventory on one tick, waits for observed tab convergence, requests Wield on a later tick, and completes only after the exact inventory-to-equipment delta.
  • GE Flipper: Flipping Copilot overlay discovery, semantic widget-owner resolution, quantity/price entry, price-warning confirmation, Break Handler pause, and offer-state postconditions after each accepted action.
  • Power Skiller: Forestry targeting, ground item checks, tool requirements, and fast dropping.
  • Tutorial Island: Validate the full varp table, setup-root/functional-child routing, pending-action priority, exact transition IDs, approach-before-interact behavior, bank-space-modal precedence, poll use only after bank close, optional settings fail-open, restart recovery, manual transition stepping, and observed postconditions through COMPLETE. Record every live result in current revision validation evidence under docs/validation/ (use the revision-239 matrix only as historical baseline); an accepted action alone is not LIVE_VERIFIED.
  • Guardians of the Rift: Cell deposits, altar selections, barrier walks, and pouch repairs.
  • Break Handler: Planned break triggers, logging out, profile re-login cycles, and PIN inputs.
  • Bank Stander: Bank standing loops, Make-X product configurations, and item actions.
  • Inventory Setups: Apply setups from bank profiles, equipment swapping, slot restorations, and cancel actions.