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/structure/ 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 {
 	@GameTest(templateName=FabricGameTest.EMPTY_STRUCTURE)
 	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 fabric-api.gametest.report-file 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 "-Dfabric-api.gametest.report-file=${project.buildDir}/junit.xml"
 			runDir "build/gametest"
 		}
 	}
 }
 
See Also:
  • Interfaces
    Class
    Description
    This interface can be optionally implemented on your test class.