| Approach | \nBest For | \nRequires Game? | \n
|---|---|---|
| JUnit 5 (pure unit tests) | \nLogic, data structures, NBT serialization | \nNo | \n
| MockBukkit | \nBukkit/Paper plugin events, commands, inventory | \nNo (mocked server) | \n
| NeoForge GameTests | \nIn-game block/entity/world interaction | \nYes (test environment) | \n
| Fabric GameTests | \nIn-game block/entity/world interaction | \nYes (test environment) | \n
| Integration server | \nFull plugin/mod lifecycle | \nYes (dedicated test server) | \n
Use Java 25 for current 26.x projects. Keep legacy 1.21.x examples on Java 21\nand Forge 1.20.1 on Java 17. Do not combine source layouts or APIs across lanes.
\nUse when: the task is designing or implementing automated tests (unit, mock, gametest, CI test jobs) for Minecraft projects.Do not use when: the task is implementing gameplay features rather than testing them (minecraft-modding, minecraft-plugin-dev, minecraft-datapack).Do not use when: the task is release automation or publishing pipelines (minecraft-ci-release).references/test-layouts.md./scripts/validate-test-layout.sh --root <project>Use the validator before copying a test layout into a real project. It checks\nvisible static dependencies, metadata, and literal structure references. It does\nnot compile the project or prove a Game Test can run.
\ntasks.test {\n useJUnitPlatform()\n testLogging {\n events(\"passed\", \"skipped\", \"failed\")\n }\n}\nFor Fabric code that needs loader setup, use Fabric Loader JUnit rather than\nassuming ordinary JUnit initialized Minecraft:
\ndependencies {\n testImplementation \"net.fabricmc:fabric-loader-junit:${project.loader_version}\"\n}\n\ntest {\n useJUnitPlatform()\n}\nWhen a unit test reaches registry-dependent Minecraft classes, initialize only\nthe required bootstrap in test setup. The current Fabric guide uses\nSharedConstants.tryDetectVersion() and Bootstrap.bootStrap() for that case.
import org.junit.jupiter.api.Test;\nimport static org.junit.jupiter.api.Assertions.*;\n\nclass CooldownManagerTest {\n\n @Test\n void cooldown_tracksPlayersIndependently() {\n var manager = new CooldownManager(500L); // 500ms cooldown\n manager.startCooldown(\"steve\");\n assertTrue(manager.isOnCooldown(\"steve\"));\n assertFalse(manager.isOnCooldown(\"notExisting\"));\n }\n\n @Test\n void cooldown_throwsIllegalArgument_onNegativeDuration() {\n assertThrows(IllegalArgumentException.class,\n () -> new CooldownManager(-1L));\n }\n}\nbuild.gradle.ktsrepositories {\n maven(\"https://repo.papermc.io/repository/maven-public/\")\n mavenCentral()\n}\n\ndependencies {\n compileOnly(\"io.papermc.paper:paper-api:26.2.build.+\")\n testImplementation(\"org.junit.jupiter:junit-jupiter:6.1.3\")\n testImplementation(\"org.mockbukkit.mockbukkit:mockbukkit-v26.2:4.116.1\")\n testRuntimeOnly(\"org.junit.platform:junit-platform-launcher\")\n}\n\ntasks.test {\n useJUnitPlatform()\n}\nimport org.mockbukkit.mockbukkit.MockBukkit;\nimport org.mockbukkit.mockbukkit.ServerMock;\nimport org.mockbukkit.mockbukkit.entity.PlayerMock;\nimport org.junit.jupiter.api.*;\n\nclass MyPluginTest {\n\n private static ServerMock server;\n private static MyPlugin plugin;\n\n @BeforeAll\n static void setUp() {\n // Start mock Bukkit server and load your plugin\n server = MockBukkit.mock();\n plugin = MockBukkit.load(MyPlugin.class);\n }\n\n @AfterAll\n static void tearDown() {\n MockBukkit.unmock();\n }\n}\n@Test\nvoid playerJoin_getsWelcomeMessage() {\n PlayerMock player = server.addPlayer(\"Steve\");\n player.simulateJoin(); // fires PlayerJoinEvent\n\n // Assert the player received the expected message component\n player.assertSaid(\"Welcome, Steve!\");\n // Or for Adventure components:\n assertTrue(player.nextMessage().contains(\"Welcome\"));\n}\n\n@Test\nvoid onBlockBreak_cancelledForNonOp() {\n PlayerMock player = server.addPlayer();\n player.setOp(false);\n\n Block block = player.getWorld().getBlockAt(0, 64, 0);\n block.setType(Material.STONE);\n BlockBreakEvent event = new BlockBreakEvent(block, player);\n server.getPluginManager().callEvent(event);\n\n assertTrue(event.isCancelled(), \"Non-op should not be able to break blocks\");\n}\n@Test\nvoid mypluginInfo_returnsVersion() {\n PlayerMock player = server.addPlayer(\"Admin\");\n player.setOp(true);\n\n boolean result = server.dispatchCommand(player, \"myplugin info\");\n\n assertTrue(result);\n player.assertSaid(\"Version: \" + plugin.getDescription().getVersion());\n}\n\n@Test\nvoid mypluginReload_requiresOp() {\n PlayerMock player = server.addPlayer(\"NonOp\");\n player.setOp(false);\n\n server.dispatchCommand(player, \"myplugin reload\");\n\n player.assertSaid(\"No permission.\");\n}\n@Test\nvoid giveKitCommand_givesPlayerItems() {\n PlayerMock player = server.addPlayer();\n \n server.dispatchCommand(player, \"kit starter\");\n \n // Check inventory\n assertTrue(player.getInventory().contains(Material.STONE_SWORD));\n assertTrue(player.getInventory().contains(Material.BREAD, 16));\n}\n@Test\nvoid repeatingTask_firesAfterDelay() {\n PlayerMock player = server.addPlayer();\n \n // Execute 40 ticks worth of scheduled tasks\n server.getScheduler().performTicks(40L);\n \n // Assert expected side effect happened\n assertEquals(2, plugin.getTaskCount());\n}\nMockBukkit does not emulate Folia's region-threaded runtime. The safe pattern is to\nwrap scheduling behind your own interface and unit test the abstraction boundary.
\ninterface SchedulerFacade {\n void runPlayerTask(Player player, Runnable task);\n void runAsync(Runnable task);\n}\n\n@Test\nvoid playerTask_delegatesThroughFacade() {\n List<String> calls = new ArrayList<>();\n SchedulerFacade facade = new SchedulerFacade() {\n @Override\n public void runPlayerTask(Player player, Runnable task) {\n calls.add(\"player\");\n task.run();\n }\n\n @Override\n public void runAsync(Runnable task) {\n calls.add(\"async\");\n task.run();\n }\n };\n\n facade.runPlayerTask(server.addPlayer(), () -> calls.add(\"ran\"));\n assertEquals(List.of(\"player\", \"ran\"), calls);\n}\nimport java.util.ArrayList;\nimport org.bukkit.damage.DamageSource;\nimport org.bukkit.damage.DamageType;\nimport org.bukkit.entity.LivingEntity;\n\n@Test\nvoid pdcKillCount_incrementsOnKill() {\n PlayerMock player = server.addPlayer();\n NamespacedKey key = new NamespacedKey(plugin, \"kills\");\n\n // EntityDeathEvent requires a living victim and an explicit damage source.\n LivingEntity victim = (LivingEntity) server.addMockEntity(EntityType.ZOMBIE);\n DamageSource damageSource = DamageSource.builder(DamageType.GENERIC)\n .withCausingEntity(player)\n .withDirectEntity(player)\n .build();\n EntityDeathEvent deathEvent = new EntityDeathEvent(\n victim, damageSource, new ArrayList<>(), 0\n );\n server.getPluginManager().callEvent(deathEvent);\n\n int kills = player.getPersistentDataContainer()\n .getOrDefault(key, PersistentDataType.INTEGER, 0);\n assertEquals(1, kills);\n}\nThis dispatches a synthetic death event. For player attribution, the listener\nunder test should read event.getDamageSource().getCausingEntity(); test actual\ncombat attribution separately on a real server.
@Test\nvoid itemPdc_roundTripsCustomId() {\n NamespacedKey key = new NamespacedKey(plugin, \"custom_id\");\n ItemStack item = new ItemStack(Material.STICK);\n\n item.editMeta(meta -> meta.getPersistentDataContainer().set(\n key, PersistentDataType.STRING, \"wand\"\n ));\n\n String value = item.getItemMeta().getPersistentDataContainer()\n .get(key, PersistentDataType.STRING);\n assertEquals(\"wand\", value);\n}\nNeoForge 1.21.5 and later uses data-driven test environments and test instances,\nnot the old @GameTestHolder method-registration API. Store resources under\ndata/<namespace>/test_environment/ and data/<namespace>/test_instance/.\nA test_instance selects its environment, structure, timing, and either a\nregistered function or a block-based test.
{\n \"environment\": \"minecraft:default\",\n \"structure\": \"examplemod:example_structure\",\n \"max_ticks\": 200,\n \"setup_ticks\": 0,\n \"required\": true,\n \"type\": \"minecraft:function\",\n \"function\": \"examplemod:example_function\"\n}\nRegister the Consumer<GameTestHelper> with a DeferredRegister for the\ncurrent BuiltInRegistries.TEST_FUNCTION registry, then attach that register to\nthe mod event bus. The function below makes the JSON reference above usable.\nUse RegisterGameTestsEvent only when registering environments and test\ninstances in code instead of data files. Keep the referenced structure in\ndata/<namespace>/structure/<path>.nbt and mark success explicitly.
import java.util.function.Consumer;\nimport net.minecraft.core.registries.BuiltInRegistries;\nimport net.minecraft.gametest.framework.GameTestHelper;\nimport net.minecraft.world.level.block.Blocks;\nimport net.neoforged.bus.api.IEventBus;\nimport net.neoforged.fml.common.Mod;\nimport net.neoforged.neoforge.registries.DeferredHolder;\nimport net.neoforged.neoforge.registries.DeferredRegister;\n\n@Mod(ExampleGameTests.MOD_ID)\npublic final class ExampleGameTests {\n public static final String MOD_ID = \"examplemod\";\n private static final DeferredRegister<Consumer<GameTestHelper>> TEST_FUNCTIONS =\n DeferredRegister.create(BuiltInRegistries.TEST_FUNCTION, MOD_ID);\n public static final DeferredHolder<Consumer<GameTestHelper>, Consumer<GameTestHelper>>\n EXAMPLE_FUNCTION = TEST_FUNCTIONS.register(\n \"example_function\", () -> ExampleGameTests::exampleTest\n );\n\n public ExampleGameTests(IEventBus modBus) {\n TEST_FUNCTIONS.register(modBus);\n }\n\n public static void exampleTest(GameTestHelper helper) {\n helper.assertBlockPresent(Blocks.AIR, 0, 0, 0);\n helper.succeed();\n }\n}\nRun ./gradlew runGameTestServer; the server exits with the count of required\nfailed tests. This command is for a real project, not this skills repository.
Use Fabric Loom's dedicated Game Test source set. Configure it in the existing\nfabricApi block and keep its metadata and code under src/gametest, separate\nfrom ordinary unit tests.
fabricApi {\n configureTests {\n createSourceSet = true\n modId = \"example-mod-test-${project.name}\"\n enableGameTests = true\n enableClientGameTests = true\n eula = true\n }\n}\nPlace fabric.mod.json in src/gametest/resources/ and register server tests\nunder fabric-gametest; use fabric-client-gametest for client tests. Implement\nserver methods with Fabric's net.fabricmc.fabric.api.gametest.v1.GameTest and,\nwhen setup is needed before a method runs, CustomTestMethodInvoker.
package com.example.mymod;\n\nimport java.lang.reflect.Method;\nimport net.fabricmc.fabric.api.gametest.v1.CustomTestMethodInvoker;\nimport net.fabricmc.fabric.api.gametest.v1.GameTest;\nimport net.minecraft.gametest.framework.GameTestHelper;\nimport net.minecraft.world.level.block.Blocks;\n\npublic final class ExampleGameTest implements CustomTestMethodInvoker {\n @GameTest\n public void testBlock(GameTestHelper context) {\n context.assertBlockPresent(Blocks.AIR, 0, 0, 0);\n context.succeed();\n }\n\n @Override\n public void invokeTestMethod(GameTestHelper context, Method method)\n throws ReflectiveOperationException {\n method.invoke(this, context);\n }\n}\nsrc/gametest/resources/fabric.mod.json{\n \"entrypoints\": {\n \"fabric-gametest\": [\n \"com.example.mymod.ExampleGameTest\"\n ]\n }\n}\nKeep the fabric-gametest entrypoint in sync with the concrete Game Test class.\nFabric's server Game Tests run with build; use runClientGameTest for client\ntests. Follow the current Fabric documentation for project-specific Loom options\nand headless client CI.
Keep annotation-based tests isolated to an explicit 1.21.3 lane. The class can\nbe registered by either @GameTestHolder(MOD_ID) or a\nRegisterGameTestsEvent listener. Do not register a @GameTestHolder class\nagain with modEventBus.register(MyGameTests.class).
import net.minecraft.gametest.framework.GameTest;\nimport net.minecraft.gametest.framework.GameTestHelper;\nimport net.neoforged.neoforge.gametest.GameTestHolder;\nimport net.neoforged.neoforge.gametest.PrefixGameTestTemplate;\n\n@GameTestHolder(\"examplemod\")\n@PrefixGameTestTemplate(false)\npublic final class ExampleGameTests {\n @GameTest(template = \"example_structure\")\n public static void smoke(GameTestHelper helper) {\n helper.succeed();\n }\n}\nFor RegisterGameTestsEvent, register the class on the mod event bus and set\ntemplateNamespace = MOD_ID on each @GameTest. Legacy templates are .nbt\nfiles under data/<namespace>/structure/; @PrefixGameTestTemplate(false)\ncontrols whether the class name is added to the template path. When template\nis omitted, the path uses the lowercase method name and, unless that prefix is\ndisabled, the lowercase simple class name followed by a dot. template is the\npath name only; configure its namespace through templateNamespace or\n@GameTestHolder.
Keep fast unit/mock tests separate from a loader's Game Test task, and select\nthe Java version by lane: 25 for 26.x, 21 for 1.21.x, and 17 for Forge 1.20.1.\nUpload test reports when a runtime-facing job fails. Do not assume a task name\nfrom another loader: Fabric server Game Tests run with build, while NeoForge\nuses runGameTestServer. MockBukkit does not prove Folia thread safety or real\nserver bootstrap.