Package net.fabricmc.fabric.api.gametest.v1

package net.fabricmc.fabric.api.gametest.v1
Provides support for GameTest framework.

What is GameTest?

GameTest is a framework, bundled in the game and originally designed for unit-testing of game code. This can be used by mod developers to test their code.

GameTest runs as a special dedicated server that automatically calls the defined "test methods". The test result can then be written as an XML file.

Creating a test

First, make an empty class and register it under the fabric-gametest entrypoint in the fabric.mod.json file.

Each "test method" represents a set of code that sets up the testing site and checks the behavior of the code - for example, it could check that using a flint and steel on a creeper causes explosion, or that hoppers can insert items into barrels. A test method is always annotated with GameTest. For most cases you can set the GameTest.templateName() as FabricGameTest.EMPTY_STRUCTURE. For complex tests, you can also save a structure as an SNBT file under modid/gametest/structures/ in the test mod's data pack and reference that structure. It will then be loaded before the test.

Test methods are instance methods (i.e. not static) and take exactly one argument - TestContext. This provides access to the world and additionally provides dozens of assertions, utility methods, and more. Test methods should end with TestContext.complete().

Example of a test method:

 public class MyTest {
 	public void testSomething(TestContext context) {
 		context.assertTrue(MyMod.getSomeValue(context.getWorld()) > 0, "SomeValue should be positive.");
 	    context.complete(); // do not forget!

Running GameTest

To run the server with GameTest enabled, add -Dfabric-api.gametest to the JVM arguments. The server works like the usual dedicated server, except that all experimental features are turned on by default.

To export the test result, set property to the output file path.

Example of a Gradle run config to launch GameTest:

 loom {
 	runs {
 		gametest {
 			inherit testmodServer
 			name "Game Test"
 			vmArg "-Dfabric-api.gametest"
 			vmArg "${project.buildDir}/junit.xml"
 			runDir "build/gametest"
See Also:
  • Interfaces
    This interface can be optionally implemented on your test class.