feat: add gametest demonstration

README.md

@@ -14,6 +14,20 @@ A simple example plugin for Sponge, demonstrating SpongeGradle.
 To build a plugin, simply run `./gradlew build`. While working on your plugin, 
 run `./gradlew runServer` to get a development server with your plugin installed!
 
+### Gametests
+
+`sponge { gameTests() }` in `build.gradle.kts` runs Minecraft gametests against your plugin on a headless
+SpongeVanilla server: `./gradlew test`, or the run icon beside a test in your IDE. Tests live in `src/test` and
+never ship in your plugin's jar; see `ExampleGameTests` for the shape of one.
+
+- A test class is annotated `@GameTestGroup`, and each test is an instance method annotated `@GameTest` that takes
+  only a `GameTestHelper`. Tests are named `<plugin id>.<group>.<method_name>`.
+- A test ends when it calls `succeed()` or its `succeedWhen(...)` check holds; otherwise it fails once `maxTicks`
+  run out.
+- `GameTestHelper` positions are relative to the test's own space; convert them with `absolutePos` before
+  passing them to the Sponge API.
+- Tests in a group run at the same time on one server, so keep shared state, like static fields, out of them.
+
 Read more about Sponge plugin development at *(docs not yet written)*
 
 Read more about Gradle from Gradle's [documentation and tutorials](https://docs.gradle.org/current/userguide/getting_started.html)

build.gradle.kts

@@ -2,11 +2,12 @@ import org.spongepowered.gradle.plugin.config.PluginLoaders
 import org.spongepowered.plugin.metadata.model.PluginDependency
 
 plugins {
-    val spongeGradleVersion = "2.2.0"
+    val spongeGradleVersion = "2.4.0"
 
     `java-library`
     id("org.spongepowered.gradle.plugin") version spongeGradleVersion
     id("org.spongepowered.gradle.ore") version spongeGradleVersion // for Ore publishing
+    id("org.spongepowered.gradle.vanilla") version "0.2.2" // Minecraft classes for gametests
 }
 
 group = "org.spongepowered"
@@ -18,6 +19,7 @@ repositories {
 
 sponge {
     apiVersion("12.0.0")
+    minecraftVersion("1.21.1")
     license("CHANGEME")
     loader {
         name(PluginLoaders.JAVA_PLAIN)
@@ -40,6 +42,12 @@ sponge {
             optional(false)
         }
     }
+    // Runs the gametests under src/test on a headless SpongeVanilla server through the test task
+    gameTests()
+}
+
+minecraft {
+    version("1.21.1")
 }
 
 val javaTarget = 21

gradle.properties

@@ -0,0 +1,2 @@
+# VanillaGradle prepares the Minecraft jars for gametests, which needs more than the default 512 MiB heap
+org.gradle.jvmargs=-Xmx2G

settings.gradle.kts

@@ -1 +1,11 @@
+pluginManagement {
+    repositories {
+        gradlePluginPortal()
+        // VanillaGradle's own dependencies are published here
+        maven("https://repo.spongepowered.org/repository/maven-public/") {
+            name = "sponge"
+        }
+    }
+}
+
 rootProject.name = "sponge-plugin-template"

src/test/java/org/spongepowered/example/ExampleGameTests.java

@@ -0,0 +1,32 @@
+package org.spongepowered.example;
+
+import net.minecraft.core.BlockPos;
+import net.minecraft.gametest.framework.GameTestHelper;
+import net.minecraft.world.level.block.Blocks;
+import org.spongepowered.api.Sponge;
+import org.spongepowered.common.test.gametest.GameTest;
+import org.spongepowered.common.test.gametest.GameTestGroup;
+
+/**
+ * Gametests run on a headless SpongeVanilla server with this plugin loaded, through {@code ./gradlew test} or the run
+ * icon beside a test. Each is named {@code example.<group>.<method_name>}, here {@code example.basics.*}.
+ */
+@GameTestGroup("basics")
+public final class ExampleGameTests {
+
+    // The plugin registers /greet during RegisterCommandEvent, so it is there once the server runs the test
+    @GameTest
+    void greetCommandIsRegistered(final GameTestHelper helper) {
+        helper.succeedWhen(() -> helper.assertTrue(
+            Sponge.server().commandManager().knownAliases().contains("greet"), "the greet command is registered"));
+    }
+
+    // Positions are relative to the test's own 3x3x3 space. A test passes once it calls succeed() or its
+    // succeedWhen(...) check holds, and fails if neither happens within maxTicks (20 by default).
+    @GameTest
+    void placedBlockIsThere(final GameTestHelper helper) {
+        final BlockPos pos = new BlockPos(1, 1, 1);
+        helper.setBlock(pos, Blocks.STONE);
+        helper.succeedWhen(() -> helper.assertBlockPresent(Blocks.STONE, pos));
+    }
+}