Automatisiertes Testen

Diese Seite erklärt, wie man Code schreibt, um Teile des Mods automatisch zu testen. Es gibt zwei Möglichkeiten, deinen Mod automatisch zu testen: Unit Tests mit Fabric Loader JUnit oder Spieltests mit dem Gametest-Framework von Minecraft.

Unit-Tests sollten verwendet werden, um Komponenten deines Codes zu testen, wie z. B. Methoden und Hilfsklassen, während Spieltests einen tatsächlichen Minecraft-Client und -Server starten, um deine Tests auszuführen, was sie für das Testen von Funktionen und Gameplay geeignet macht.

Unit-Tests

Da Minecraft Modding auf Laufzeit-Bytecode-Modifikationswerkzeuge wie Mixin angewiesen ist, würde das einfache Hinzufügen und Verwenden von JUnit normalerweise nicht funktionieren. Aus diesem Grund bietet Fabric, Fabric Loader JUnit, ein JUnit-Plugin, das Unit-Tests in Minecraft ermöglicht.

Fabric Loader JUnit reinrichten

Zuerst müssen wir Fabric Loader JUnit zu der Entwicklungsumgebung hinzufügen. Füge folgendes zu deinem Dependencies-Block in deiner build.gradle-Datei hinzu:

testImplementation "net.fabricmc:fabric-loader-junit:${project.loader_version}"

Dann müssen wir Gradle anweisen, Fabric Loader JUnit zum Testen zu verwenden. Du kannst dies tun, indem du den folgenden Code zu deiner build.gradle-Datei hinzufügst:

test {
	useJUnitPlatform()
}

Tests schreiben

Nachdem du Gradle neu geladen hast, bist du bereit, Tests zu schreiben.

Diese Tests werden genau wie normale JUnit-Tests geschrieben, mit ein paar zusätzlichen Einstellungen, wenn du auf eine von einer Registry abhängigen Klasse wie ItemStack zugreifen willst. Wenn du mit JUnit vertraut bist, kannst du zu Registries einrichten übergehen.

Deine erste Testklasse erstellen

Tests werden im Verzeichnis src/test/java geschrieben.

Eine Namenskonvention besteht darin, die Paketstruktur der Klasse, die du testest, widerzuspiegeln. Zum Beispiel, um src/main/java/com/example/docs/codec/BeanType.java zu testen, würdest du eine Klasse src/test/java/com/example/docs/codec/BeanTypeTest.java erstellen. Beachte, dass wir Test an das Ende des Klassennamens angefügt haben. Dies ermöglicht dir den einfachen Zugang zu Paket-Privaten Methoden und Feldern.

Eine andere Namenskonvention ist ein test-Paket, wie src/test/java/com/example/docs/test/codec/BeanTypeTest.java. Dies verhindert einige Probleme, die bei der Verwendung desselben Pakets auftreten können, wenn du Java-Module verwendest.

Nachdem du die Testklasse erstellt hast, verwende ⌘/CTRL+N, um das Generate-Menü aufzurufen. Wähle Test und beginne mit der Eingabe deines Methodennamens, der normalerweise mit test beginnt. Drücke ENTER, wenn du fertig bist. Weitere Tipps und Tricks zur Verwendung der IDE findest du unter IDE Tipps und Tricks.

Du kannst die Methodensignatur natürlich auch von Hand schreiben, und jede Instanzmethode ohne Parameter und mit einem ungültigen Rückgabetyp wird als Testmethode identifiziert. Das Ergebnis sollte wie folgt aussehen:

Beachte die grünen Pfeilindikatoren in dem Zwischenraum: Du kannst ganz einfach einen Test ausführen, indem du sie anklickst. Alternativ dazu werden deine Tests automatisch bei jedem Build ausgeführt, einschließlich CI-Builds wie GitHub Actions. Wenn du GitHub Actions verwendest, solltest du unbedingt GitHub Actions einrichten lesen.

Nun ist es an der Zeit, den eigentlichen Testcode zu schreiben. Du kannst Bedingungen mit Hilfe von org.junit.jupiter.api.Assertions prüfen. Siehe dazu den folgenden Test an:

public class BeanTypeTest {
	private static final Gson GSON = new GsonBuilder().create();

	@BeforeAll
	static void beforeAll() {
		BeanTypes.register();
	}

	@Test
	void testBeanCodec() {
		StringyBean expectedBean = new StringyBean("This bean is stringy!");
		Bean actualBean = Bean.BEAN_CODEC.parse(JsonOps.INSTANCE, GSON.fromJson("{\"type\":\"example:stringy_bean\",\"stringy_string\":\"This bean is stringy!\"}", JsonObject.class)).getOrThrow();

		Assertions.assertInstanceOf(StringyBean.class, actualBean);
		Assertions.assertEquals(expectedBean.getType(), actualBean.getType());
		Assertions.assertEquals(expectedBean.getStringyString(), ((StringyBean) actualBean).getStringyString());
	}

	@Test
	void testDiamondItemStack() {
		// I know this isn't related to beans, but I need an example :)
		ItemStackTemplate diamondStack = new ItemStackTemplate(Items.DIAMOND, 65);

		Assertions.assertTrue(diamondStack.is(Items.DIAMOND));
		Assertions.assertEquals(65, diamondStack.count());
	}
}

Für eine Erklärung, was dieser Code tatsächlich tut, siehe Codecs.

Registries einrichten

Großartig, der erste Test war erfolgreich! Aber Moment, der zweite Test ist fehlgeschlagen? In den Logs wird einer der folgenden Fehler angezeigt.

java.lang.ExceptionInInitializerError
	at net.minecraft.item.ItemStack.<clinit>(ItemStack.java:94)
	at com.example.docs.codec.BeanTypeTest.testBeanCodec(BeanTypeTest.java:20)
	at java.base/java.lang.reflect.Method.invoke(Method.java:580)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)
Caused by: java.lang.IllegalArgumentException: Not bootstrapped (called from registry ResourceKey[minecraft:root / minecraft:game_event])
	at net.minecraft.Bootstrap.createNotBootstrappedException(Bootstrap.java:118)
	at net.minecraft.Bootstrap.ensureBootstrapped(Bootstrap.java:111)
	at net.minecraft.registry.Registries.create(Registries.java:238)
	at net.minecraft.registry.Registries.create(Registries.java:229)
	at net.minecraft.registry.Registries.<clinit>(Registries.java:139)
	... 5 more

Not bootstrapped (called from registry ResourceKey[minecraft:root / minecraft:game_event])
java.lang.IllegalArgumentException: Not bootstrapped (called from registry ResourceKey[minecraft:root / minecraft:game_event])
	at net.minecraft.Bootstrap.createNotBootstrappedException(Bootstrap.java:118)
	at net.minecraft.Bootstrap.ensureBootstrapped(Bootstrap.java:111)
	at net.minecraft.registry.Registries.create(Registries.java:238)
	at net.minecraft.registry.Registries.create(Registries.java:229)
	at net.minecraft.registry.Registries.<clinit>(Registries.java:139)
	at net.minecraft.item.ItemStack.<clinit>(ItemStack.java:94)
	at com.example.docs.codec.BeanTypeTest.testBeanCodec(BeanTypeTest.java:20)
	at java.base/java.lang.reflect.Method.invoke(Method.java:580)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1596)

Dies liegt daran, dass wir versuchen, auf die Registry oder eine Klasse zuzugreifen, die von der Registry abhängt (oder, in seltenen Fällen, von anderen Minecraft-Klassen wie SharedConstants), aber Minecraft wurde noch nicht initialisiert. Wir müssen es nur ein wenig initialisieren, damit die Registries funktionieren. Fügen einfach den folgenden Code an den Anfang deiner Methode beforeAll.

SharedConstants.tryDetectVersion();
Bootstrap.bootStrap();

Github Actions einrichten

INFO

In diesem Abschnitt wird davon ausgegangen, dass du den standardmäßigen GitHub Action-Workflow verwendest, der in dem Beispielmod und in der Mod-Vorlage enthalten ist.

Deine Tests werden nun bei jedem Build ausgeführt, auch bei denen von CI-Anbietern wie GitHub Actions. Was aber, wenn ein Build fehlschlägt? Wir müssen die Logs als Artefakt hochladen, damit wir die Testberichte ansehen können.

Füge dies, unterhalb des Schrittes ./gradlew build, zu deiner Datei .github/workflows/build.yaml hinzu.

- name: Store reports
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: reports
    path: |
      **/build/reports/
      **/build/test-results/

Spiel-Tests

Minecraft bietet ein Test-Framework für das Testen serverseitiger Funktionen. Fabric bietet zusätzlich Client-Spiel-Tests zum Testen clientseitiger Funktionen, ähnlich einem Ende-zu-Ende-Test.

Spiel-Tests mit Fabric Loom einrichten

Sowohl Server- als auch Client-Spiel-Tests können manuell oder mit Fabric Loom eingerichtet werden. Dieser Leitfaden wird Loom nutzen.

Um Spiel-Tests zu deinem Mod hinzuzufügen, füge das Folgende zu deiner build.gradle hinzu:

fabricApi {
	configureTests {
		createSourceSet = true
		modId = "example-mod-test-${project.name}"
		enableGameTests = true // Default is true
		enableClientGameTests = true // Default is true
		eula = true // By setting this to true, you agree to the Minecraft EULA.
	}
}

Um alle verfügbaren Optionen zu sehen, siehe die Loom-Dokumentation zu Tests.

Spiel-Tests-Verzeichnis einrichten

INFO

Du benötigst diesen Abschnitt nur, wenn du die Option createSourceSet aktiviert hast, was empfohlen ist. Du kannst natürlich auch deine eigene Gradle-Magie anwenden, aber dann bist du auf dich allein gestellt.

Wenn du createSourceSet wie im obigen Beispiel aktiviert hast, wird dein Spiel-Test in einem separaten Quellensatz mit einer separaten fabric.mod.json sein. Der Modulname ist standardmäßig gametest. Erstelle eine neue fabric.mod.json in src/gametest/resources/ wie gezeigt:

{
  "schemaVersion": 1,
  "id": "example-mod-test",
  "version": "1.0.0",
  "name": "Example mod",
  "icon": "assets/example-mod/icon.png",
  "environment": "*",
  "entrypoints": {
    "fabric-gametest": ["com.example.docs.ExampleModGameTest"],
    "fabric-client-gametest": ["com.example.docs.ExampleModClientGameTest"]
  }
}

Beachte, dass diese fabric.mod.json einen Server-Spiel-Test unter src/gametest/java/com/example/docs/ExampleModGameTest erwartet, und einen Client-Spiel-Test unter src/gametest/java/com/example/docs/ExampleModClientGameTest.

Spiel-Tests schreiben

Du kannst jetzt Server- und Client-Tests im Verzeichnis src/gametest/java erstellen. Hier ist ein grundlegendes Beispiel für jedes:

Server

package com.example.docs;

import java.lang.reflect.Method;

import net.minecraft.gametest.framework.GameTestHelper;
import net.minecraft.world.level.block.Blocks;

import net.fabricmc.fabric.api.gametest.v1.CustomTestMethodInvoker;
import net.fabricmc.fabric.api.gametest.v1.GameTest;

public class ExampleModGameTest implements CustomTestMethodInvoker {
	@GameTest
	public void test(GameTestHelper context) {
		context.assertBlockPresent(Blocks.AIR, 0, 0, 0);
		context.succeed();
	}

	@Override
	public void invokeTestMethod(GameTestHelper context, Method method) throws ReflectiveOperationException {
		context.setBlock(0, 0, 0, Blocks.AIR);
		method.invoke(this, context);
	}
}

Client

package com.example.docs;

import net.fabricmc.fabric.api.client.gametest.v1.FabricClientGameTest;
import net.fabricmc.fabric.api.client.gametest.v1.context.ClientGameTestContext;
import net.fabricmc.fabric.api.client.gametest.v1.context.TestSingleplayerContext;

@SuppressWarnings("UnstableApiUsage")
public class ExampleModClientGameTest implements FabricClientGameTest {
	@Override
	public void runTest(ClientGameTestContext context) {
		try (TestSingleplayerContext singleplayer = context.worldBuilder().create()) {
			singleplayer.getClientLevel().waitForChunksRender();
			context.takeScreenshot("example-mod-singleplayer-test");
		}
	}
}

Für weitere Informationen siehe die entsprechenden Javadocs in der Fabric API.

Spieltests ausführen

Server-Spieltests werden automatisch mit dem build Gradle Task ausgeführt. Du kannst Client Spiel-Tests mit dem runClientGameTest Gradle Task ausführen.

Spieltests bei GitHub Actions ausführen

Bestehende GitHub Action-Workflows, die build verwenden, führen automatisch die Server-Spieltests durch. Um Client-Spieltests mit GitHub Actions auszuführen, füge den folgenden Ausschnitt zu deiner build.gradle-Datei und den folgenden Job zu deinem Workflow hinzu. Das Gradle-Snippet führt Client-Spieletests mit Looms Produktionslauf-Aufgaben durch, und der Job führt die Produktionslauf-Aufgabe in dem CI aus.

WARNING

Derzeit kann der Spieltest aufgrund eines Fehlers im Netzwerksynchronisierer auf GitHub Actions fehlschlagen. Wenn dieser Fehler auftritt, kannst du -Dfabric.client.gametest.disableNetworkSynchronizer=true zu den JVM-Argumenten in deiner Deklaration Produktionslauf-Aufgaben hinzufügen.

dependencies {
  productionRuntimeMods "net.fabricmc.fabric-api:fabric-api:${fabricApiVersion}"
}

tasks.register("runProductionClientGameTest", net.fabricmc.loom.task.prod.ClientProductionRunTask) {
	jvmArgs.add("-Dfabric.client.gametest")
	// Whether to use XVFB to run the game, using a virtual framebuffer. This is useful for headless CI environments.
	// Defaults to true only on Linux and when the "CI" environment variable is set.
	// XVFB must be installed, on Debian-based systems you can install it with: `apt install xvfb`
	useXVFB = true
}

client_game_test:
  runs-on: ubuntu-24.04
  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-java@v4
      with:
        distribution: temurin
        java-version: 25
    - run: ./gradlew runProductionClientGameTest
    - if: always()
      uses: actions/upload-artifact@v4
      with:
        path: build/run/clientGameTest/screenshots