test: cover Archaeo behaviour and fix bugs the tests exposed

.github/workflows/build.yml

@@ -68,3 +68,11 @@ jobs:
           name: unit-test-reports-${{ github.run_id }}-${{ github.run_attempt }}
           path: target/surefire-reports/
           if-no-files-found: error
+
+      - name: Upload coverage report
+        if: ${{ !cancelled() && hashFiles('target/site/jacoco/jacoco.xml') != '' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-report-${{ github.run_id }}-${{ github.run_attempt }}
+          path: target/site/jacoco/
+          if-no-files-found: error

README.md

@@ -32,6 +32,34 @@ them before they ever reach the surface.
 
 Technical documentation is maintained in [TF-Minecraft/Docs](https://github.com/TF-Minecraft/Docs).
 
+## Tests
+
+With Java 21 and Maven installed, run `mvn clean verify`. Tests exercise domain
+rules, YAML persistence, and plugin workflows using JUnit, Mockito, and MockBukkit.
+JaCoCo measures all production classes and writes its HTML report to
+`target/site/jacoco/index.html` and machine-readable results to
+`target/site/jacoco/jacoco.xml`. The build workflow uploads the coverage report.
+
+Tests should assert gameplay behavior, data preservation, or failure handling.
+Do not add tests solely to execute a line or manufacture unreachable states to
+increase coverage. MockBukkit tests do not replace testing on a real Paper server
+with the optional ItemsAdder and MMOItems integrations installed.
+
+Adapter contract tests can also run against locally supplied plugin jars:
+
+```sh
+mvn -Ppack-api-tests clean verify \
+  -Ditemsadder.jar=/path/to/ItemsAdder.jar \
+  -Dfastnbt.jar=/path/to/FastNbt-jar.jar \
+  -Dmmoitems.jar=/path/to/MMOItems.jar \
+  -Dmythiclib.jar=/path/to/MythicLib.jar
+```
+
+These tests bind the actual API classes and mock their external operations; they
+do not start those plugins. The jars remain outside this repository and are used
+only on the test runtime classpath. Use the FastNbt version declared by your
+ItemsAdder jar. The ordinary test suite needs none of these files.
+
 ## License
 
 Copyright (c) 2026 TF-Minecraft contributors.

pom.xml

@@ -24,6 +24,18 @@
   </repositories>
 
   <dependencies>
+    <dependency>
+      <groupId>org.mockbukkit.mockbukkit</groupId>
+      <artifactId>mockbukkit-v1.21</artifactId>
+      <version>4.95.0</version>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.mockito</groupId>
+      <artifactId>mockito-core</artifactId>
+      <version>5.20.0</version>
+      <scope>test</scope>
+    </dependency>
     <dependency>
       <groupId>junit</groupId>
       <artifactId>junit</artifactId>
@@ -38,7 +50,62 @@
     </dependency>
   </dependencies>
 
+  <profiles>
+    <profile>
+      <id>pack-api-tests</id>
+      <build>
+        <plugins>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <configuration>
+              <includes>
+                <include>**/*Test.java</include>
+                <include>**/*IT.java</include>
+              </includes>
+              <additionalClasspathElements>
+                <additionalClasspathElement>${itemsadder.jar}</additionalClasspathElement>
+                <additionalClasspathElement>${fastnbt.jar}</additionalClasspathElement>
+                <additionalClasspathElement>${mmoitems.jar}</additionalClasspathElement>
+                <additionalClasspathElement>${mythiclib.jar}</additionalClasspathElement>
+              </additionalClasspathElements>
+            </configuration>
+          </plugin>
+        </plugins>
+      </build>
+    </profile>
+  </profiles>
+
   <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>3.5.4</version>
+        <dependencies>
+          <dependency>
+            <groupId>org.apache.maven.surefire</groupId>
+            <artifactId>surefire-junit4</artifactId>
+            <version>3.5.4</version>
+          </dependency>
+        </dependencies>
+      </plugin>
+      <plugin>
+        <groupId>org.jacoco</groupId>
+        <artifactId>jacoco-maven-plugin</artifactId>
+        <version>0.8.15</version>
+        <executions>
+          <execution>
+            <goals><goal>prepare-agent</goal></goals>
+          </execution>
+          <execution>
+            <id>coverage-report</id>
+            <phase>verify</phase>
+            <goals><goal>report</goal></goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
     <finalName>archaeo-${project.version}</finalName>
     <sourceDirectory>${project.basedir}/src/main/java</sourceDirectory>
     <resources>

src/main/java/net/tfminecraft/archaeo/ArcheologyPlugin.java

@@ -172,11 +172,10 @@ public void onEnable() {
                 autoRuins,
                 campClosure,
                 sitePurge);
+        // plugin.yml in this jar declares the command, so Bukkit always returns it.
         PluginCommand pluginCommand = getCommand("archaeo");
-        if (pluginCommand != null) {
-            pluginCommand.setExecutor(command);
-            pluginCommand.setTabCompleter(command);
-        }
+        pluginCommand.setExecutor(command);
+        pluginCommand.setTabCompleter(command);
         getLogger().info("Archaeo enabled. Loaded sites: " + sites.all().size());
     }
 
@@ -186,34 +185,17 @@ public void onEnable() {
      * @param matcher detected APIs, or vanilla-only
      */
     public void bindItemMatcher(ItemMatcher matcher) {
+        // Callers (enable, reload, the pack-plugin hook) run only after onEnable built every item.
         ItemMatcher bound = matcher == null ? ItemMatcher.vanillaOnly() : matcher;
-        if (trackerItem != null) {
-            trackerItem.setMatcher(bound);
-        }
-        if (prospectItem != null) {
-            prospectItem.setMatcher(bound);
-        }
-        if (establishItem != null) {
-            establishItem.setMatcher(bound);
-        }
-        if (brushItem != null) {
-            brushItem.setMatcher(bound);
-        }
-        if (sketchSupplies != null) {
-            sketchSupplies.setMatcher(bound);
-        }
-        if (digTools != null) {
-            digTools.setMatcher(bound);
-        }
-        if (recoveredFindItem != null) {
-            recoveredFindItem.setMatcher(bound);
-        }
-        if (sketch != null) {
-            sketch.setMatcher(bound);
-        }
-        if (museum != null) {
-            museum.setMatcher(bound);
-        }
+        trackerItem.setMatcher(bound);
+        prospectItem.setMatcher(bound);
+        establishItem.setMatcher(bound);
+        brushItem.setMatcher(bound);
+        sketchSupplies.setMatcher(bound);
+        digTools.setMatcher(bound);
+        recoveredFindItem.setMatcher(bound);
+        sketch.setMatcher(bound);
+        museum.setMatcher(bound);
     }
 
     /**