Game Test API

.github/workflows/test.yml

@@ -17,7 +17,7 @@ jobs:
           java-version: ${{ matrix.java }}
           cache: 'gradle'
       - run: ./gradlew checkLicenses generateQmj --parallel --stacktrace
-      - run: ./gradlew check build publishToMavenLocal --stacktrace --parallel
+      - run: ./gradlew build publishToMavenLocal --stacktrace --parallel -Porg.gradle.parallel.threads=4
       - run: mkdir run && echo "eula=true" >> run/eula.txt
       - run: ./gradlew :runAutoAllTestServer --stacktrace
       - uses: actions/upload-artifact@v3

build-logic/src/main/groovy/qsl.module.gradle

@@ -136,6 +136,16 @@ loom {
 			server()
 			source(sourceSets.testmod)
 		}
+
+		gameTestServer {
+			inherit testmodServer
+			configName = "Game test server"
+
+			// Enable the game test runner.
+			property("quilt.game_test", "true")
+			property("quilt.game_test.report_file", "${project.buildDir}/game_test/report.xml")
+			runDir("build/game_test")
+		}
 	}
 }
 

build.gradle

@@ -165,6 +165,16 @@ loom {
 			configName = "Auto test server"
 			property("quilt.auto_test")
 		}
+
+		// Game test server, a server that executes tests using Minecraft's test framework.
+		gameTestServer {
+			inherit testmodServer
+
+			configName = "Game test server"
+			property("quilt.game_test", "true")
+			property("quilt.game_test.report_file", "${project.buildDir}/game_test/report.xml")
+			runDir("build/game_test")
+		}
 	}
 }
 
@@ -173,6 +183,11 @@ task runAutoAllTestServer {
 	description "Runs all the server-sided tests automatically.\nTypically ran by the CI server."
 }
 
+task runGameAllTestServer {
+	group "verification"
+	description "Runs all the server-sided game tests automatically.\nTypically ran by the CI server."
+}
+
 afterEvaluate {
 	def generateQmjForIdea = tasks.create("generateQmjForIdea")
 	project.subprojects.each {
@@ -202,6 +217,8 @@ afterEvaluate {
 	}
 
 	tasks.runAutoAllTestServer.dependsOn tasks.runAutoTestServer
+	tasks.runGameAllTestServer.dependsOn tasks.runGameTestServer
+	tasks.test.dependsOn tasks.runGameAllTestServer
 }
 
 task checkVersion {

library/block/block_content_registry/build.gradle

@@ -12,6 +12,7 @@ qslModule {
 		core {
 			api("qsl_base")
 			impl("resource_loader")
+			testmodOnly("game_test")
 		}
 		data {
 			api("registry_entry_attachment")

library/block/block_content_registry/src/testmod/java/org/quiltmc/qsl/block/test/BlockContentRegistryTest.java

@@ -16,30 +16,41 @@
 
 package org.quiltmc.qsl.block.test;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Optional;
 
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 import net.minecraft.block.AbstractBlock;
 import net.minecraft.block.Block;
+import net.minecraft.block.BlockState;
 import net.minecraft.block.Blocks;
 import net.minecraft.block.Oxidizable;
 import net.minecraft.block.OxidizableBlock;
+import net.minecraft.block.PillarBlock;
+import net.minecraft.item.ItemStack;
+import net.minecraft.item.Items;
 import net.minecraft.registry.Registries;
 import net.minecraft.registry.tag.BlockTags;
+import net.minecraft.test.GameTest;
 import net.minecraft.util.Identifier;
+import net.minecraft.util.math.BlockPos;
+import net.minecraft.util.math.Direction;
 
 import org.quiltmc.loader.api.ModContainer;
 import org.quiltmc.qsl.base.api.entrypoint.ModInitializer;
 import org.quiltmc.qsl.block.content.registry.api.BlockContentRegistries;
 import org.quiltmc.qsl.block.content.registry.api.FlammableBlockEntry;
 import org.quiltmc.qsl.block.content.registry.api.ReversibleBlockEntry;
+import org.quiltmc.qsl.game_test.api.QuiltGameTest;
+import org.quiltmc.qsl.game_test.api.QuiltTestContext;
 import org.quiltmc.qsl.lifecycle.api.event.ServerWorldTickEvents;
 import org.quiltmc.qsl.registry.attachment.api.RegistryEntryAttachment;
 import org.quiltmc.qsl.registry.attachment.api.RegistryExtensions;
 
-public class BlockContentRegistryTest implements ModInitializer {
+public class BlockContentRegistryTest implements ModInitializer, QuiltGameTest {
 	public static final String MOD_ID = "quilt_block_content_registry_testmod";
 	public static final Logger LOGGER = LoggerFactory.getLogger("BlockContentRegistryTest");
 
@@ -73,6 +84,35 @@ public void onInitialize(ModContainer mod) {
 		});
 	}
 
+	@GameTest(structureName = QuiltGameTest.EMPTY_STRUCTURE)
+	public void flatten(QuiltTestContext context) {
+		var tester = new TestHelper(new BlockPos(1, 1, 1), new ItemStack(Items.IRON_SHOVEL));
+
+		tester.push(Blocks.DIRT.getDefaultState(), Blocks.DIRT_PATH.getDefaultState());
+		tester.push(Blocks.GRASS_BLOCK.getDefaultState(), Blocks.DIRT_PATH.getDefaultState());
+		tester.push(Blocks.OAK_PLANKS.getDefaultState(), Blocks.OAK_SLAB.getDefaultState());
+
+		tester.run(context);
+	}
+
+	@GameTest(structureName = QuiltGameTest.EMPTY_STRUCTURE)
+	public void strip(QuiltTestContext context) {
+		var tester = new TestHelper(new BlockPos(1, 1, 1), new ItemStack(Items.IRON_AXE));
+
+		tester.push(Blocks.OAK_LOG.getDefaultState(), Blocks.STRIPPED_OAK_LOG.getDefaultState());
+		tester.push(
+				Blocks.OAK_LOG.getDefaultState().with(PillarBlock.AXIS, Direction.Axis.Z),
+				Blocks.STRIPPED_OAK_LOG.getDefaultState().with(PillarBlock.AXIS, Direction.Axis.Z)
+		);
+		tester.push(Blocks.QUARTZ_PILLAR.getDefaultState(), Blocks.PURPUR_PILLAR.getDefaultState());
+		tester.push(
+				Blocks.QUARTZ_PILLAR.getDefaultState().with(PillarBlock.AXIS, Direction.Axis.Z),
+				Blocks.PURPUR_PILLAR.getDefaultState().with(PillarBlock.AXIS, Direction.Axis.Z)
+		);
+
+		tester.run(context);
+	}
+
 	private <T> void assertValues(Block block, RegistryEntryAttachment<Block, T> attachment, T value) {
 		Optional<T> entry = attachment.get(block);
 		Identifier id = Registries.BLOCK.getId(block);
@@ -86,4 +126,43 @@ private <T> void assertValues(Block block, RegistryEntryAttachment<Block, T> att
 
 		LOGGER.info("Test for block " + id + " passed for REA " + attachment.id());
 	}
+
+	static class TestHelper {
+		private final List<Entry> entries = new ArrayList<>();
+		private final ItemStack tool;
+		private BlockPos nextPos;
+
+		TestHelper(BlockPos startPos, ItemStack tool) {
+			this.tool = tool;
+			this.nextPos = startPos;
+		}
+
+		void push(BlockState baseState, BlockState targetState) {
+			this.entries.add(new Entry(this.nextPos, baseState, targetState));
+
+			this.nextPos = this.nextPos.east();
+			if (this.nextPos.getX() > 7) {
+				this.nextPos = new BlockPos(1, 1, this.nextPos.getZ() + 1);
+			}
+		}
+
+		void run(QuiltTestContext context) {
+			this.entries.forEach(entry -> context.setBlockState(entry.pos(), entry.baseState()));
+
+			var player = context.createMockPlayer();
+			this.entries.forEach(entry -> {
+				context.useStackOnBlockAt(player, this.tool, entry.pos(), Direction.UP);
+			});
+
+			context.addInstantFinalTask(() ->
+					this.entries.forEach(entry ->
+							context.checkBlockState(entry.pos(), state -> state.equals(entry.targetState()),
+									() -> "Could not find state " + entry.targetState()
+							)
+					)
+			);
+		}
+
+		record Entry(BlockPos pos, BlockState baseState, BlockState targetState) {}
+	}
 }

library/block/block_content_registry/src/testmod/resources/quilt.mod.json

@@ -12,11 +12,15 @@
     "intermediate_mappings": "net.fabricmc:intermediary",
     "depends": [
       "quilt_loader",
-      "quilt_block_content_registry"
+      "quilt_block_content_registry",
+      "quilt_game_test"
     ],
     "entrypoints": {
       "init": [
         "org.quiltmc.qsl.block.test.BlockContentRegistryTest"
+      ],
+      "quilt:game_test": [
+        "org.quiltmc.qsl.block.test.BlockContentRegistryTest"
       ]
     }
   }

library/core/game_test/build.gradle

@@ -0,0 +1,25 @@
+plugins {
+	id("qsl.module")
+}
+
+qslModule {
+	name = "Quilt Game Test"
+	moduleName = "game_test"
+	id = "quilt_game_test"
+	description = "Utilites to assist in testing the game and mods."
+	library = "core"
+	moduleDependencies {
+		core {
+			api("qsl_base")
+			api("lifecycle_events")
+		}
+		management {
+			testmodOnly("command")
+		}
+	}
+	entrypoints {
+		init {
+			values = ["org.quiltmc.qsl.game_test.impl.QuiltGameTestImpl"]
+		}
+	}
+}

library/core/game_test/src/main/java/org/quiltmc/qsl/game_test/api/QuiltGameTest.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2022 QuiltMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.qsl.game_test.api;
+
+/**
+ * This interface can be optionally implemented on your test class.
+ */
+public interface QuiltGameTest {
+	/**
+	 * Use in {@link net.minecraft.test.GameTest} structureName to use an empty 8x8 structure for the test.
+	 */
+	String EMPTY_STRUCTURE = "quilt:empty";
+
+	/**
+	 * Represents the key of the game tests entrypoint to use in the {@code quilt.mod.json} file, whose value is {@value}.
+	 */
+	String ENTRYPOINT_KEY = "quilt:game_test";
+
+	/**
+	 * Override this method to implement custom logic to invoke the test method.
+	 * <p>
+	 * This can be used to run code before or after each test.
+	 * You can also pass in custom objects into the test method if desired.
+	 * The structure will have been placed in the world before this method is invoked.
+	 *
+	 * @param context the vanilla test context
+	 * @param method  the test method to invoke
+	 */
+	default void invokeTestMethod(QuiltTestContext context, TestMethod method) {
+		method.invoke(this, context);
+	}
+
+	/**
+	 * Override this method to register additional tests or conditional tests.
+	 *
+	 * @param context the test registration context
+	 */
+	default void registerTests(TestRegistrationContext context) {}
+}

library/core/game_test/src/main/java/org/quiltmc/qsl/game_test/api/QuiltTestContext.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2022 QuiltMC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.qsl.game_test.api;
+
+import org.jetbrains.annotations.NotNull;
+
+import net.minecraft.block.BlockState;
+import net.minecraft.entity.player.PlayerEntity;
+import net.minecraft.item.ItemStack;
+import net.minecraft.item.ItemUsageContext;
+import net.minecraft.test.GameTestState;
+import net.minecraft.test.TestContext;
+import net.minecraft.util.Hand;
+import net.minecraft.util.hit.BlockHitResult;
+import net.minecraft.util.math.BlockPos;
+import net.minecraft.util.math.Direction;
+import net.minecraft.util.math.Vec3d;
+
+/**
+ * Represents Quilt-provided extensions to {@link TestContext}.
+ * <p>
+ * This is the class that is passed in tests with default handling.
+ */
+public class QuiltTestContext extends TestContext {
+	public QuiltTestContext(GameTestState test) {
+		super(test);
+	}
+
+	/**
+	 * Expects the given block state at the given block position.
+	 *
+	 * @param state the expected block state
+	 * @param pos   the position to check for
+	 */
+	public void expectBlockState(@NotNull BlockState state, @NotNull BlockPos pos) {
+		this.checkBlockState(pos, s -> s.equals(state), () -> "Expected block state " + state + " at position " + pos.toShortString() + '.');
+	}
+
+	/**
+	 * Uses the given item stack on the specified position.
+	 *
+	 * @param player  the player who uses the item
+	 * @param stack   the item stack to use
+	 * @param pos     the position of the use hit
+	 * @param sideHit the side that's being hit for using the item
+	 */
+	public void useStackOnBlockAt(@NotNull PlayerEntity player, @NotNull ItemStack stack, @NotNull BlockPos pos, @NotNull Direction sideHit) {
+		var actualPos = this.getAbsolutePos(pos);
+		var blockHitResult = new BlockHitResult(Vec3d.ofCenter(actualPos), sideHit, actualPos, false);
+		var itemUsageContext = new ItemUsageContext(player, Hand.MAIN_HAND, blockHitResult);
+		stack.useOnBlock(itemUsageContext);
+	}
+}