Skip to content

Test behavior with GameTest

This guide writes a GameTest for PathWear once, in common code, runs it on Fabric and Forge, and checks that two steps on one block count 2.

The test class is plain common code against vanilla’s GameTest API, kept out of the mod’s jar in a source set of its own (see Add a GameTest run). Add WearGameTests, the first class of the testing quick start, to the common project’s src/gametest/java. Its one test clears a block’s count in PathWear, the saved data from the saved data quick start, steps on it twice, and checks that the count is 2.

GameTestFunctions’ Javadoc says how it names a test and which structure a test without a template runs in: for this one, the mod’s empty structure.

Save the mod’s empty structure, of air, at the size the GameTestFunctions section gives, as data/mymod/structures/empty.nbt in the common project’s src/gametest/resources. To make it in a creative world, place a structure block in Save mode, name the structure mymod:empty, set its size to that size over air, and press Save; the game writes it under the world’s generated/mymod/structures/ folder.

Fabric runs the tests a fabric-gametest entry point returns. Add MyFabricGameTests, the Fabric class of the testing quick start, to the Fabric project’s src/gametest/java. List the class in that source set’s own fabric.mod.json, a small mod that loads only in GameTest runs; your.namespace.modid stands for your package. Save it in the Fabric project’s src/gametest/resources:

Declare the Fabric GameTest entry point in a test-only mod
{
"schemaVersion": 1,
"id": "mymod-gametest",
"version": "0.0.0",
"environment": "*",
"entrypoints": {
"fabric-gametest": ["your.namespace.modid.MyFabricGameTests"]
},
"depends": { "mymod": "*", "fabric-gametest-api-v1": "*" }
}

Forge runs the tests of @GameTestHolder classes in the namespaces a run enables. Add MyForgeGameTests, the Forge class of the testing quick start, to the Forge project’s src/gametest/java.

Each loader’s project needs a gametest source set that compiles the common tests together with that loader’s own, against the mod’s classes. In each loader’s build.gradle.kts:

build.gradle.kts (Fabric and Forge)
val main = sourceSets["main"]
val gametest = sourceSets.create("gametest") {
java.srcDirs(project(":common").file("src/gametest/java"), file("src/gametest/java"))
resources.srcDirs(project(":common").file("src/gametest/resources"), file("src/gametest/resources"))
compileClasspath += main.compileClasspath + main.output
runtimeClasspath += main.runtimeClasspath + main.output
}

This is the usual Architectury layout, with common code in a common subproject. In a build whose common code sits in the root project, use rootDir.resolve("src/gametest/java") and rootDir.resolve("src/gametest/resources") for the common folders instead.

Then tell Loom which folders make up each mod in development, and add a run that starts a GameTest server with the source set. In the Fabric project, the GameTest classes are a mod of their own, mymod-gametest, which only the GameTest run’s classpath holds:

build.gradle.kts (Fabric)
loom {
mods {
create("mymod") { sourceSet(main) }
create("mymod-gametest") { sourceSet(gametest) }
}
runs {
create("gametest") {
server()
name("Game Test")
source(gametest)
runDir("build/gametest")
// Fabric API runs the tests, writes a JUnit report, and stops the server.
vmArgs("-Dfabric-api.gametest", "-Dfabric-api.gametest.report-file=../junit-gametest.xml")
}
}
}

In the Forge project, with Architectury Loom, the @GameTestHolder classes belong to the mod itself. Forge builds each development mod from the folders its list names, not from a run’s classpath, so each run lists the folders it loads:

build.gradle.kts (Forge)
loom {
mods {
create("mymod") {
sourceSet(main)
sourceSet(gametest)
}
}
runs {
// Without lists of their own, the plain runs would load the test classes too.
for (plain in listOf("client", "server")) {
getByName(plain).mods.create("mymod") { sourceSet(main) }
}
create("gametest") {
server()
name("Game Test")
source(gametest)
runDir("build/gametest")
environment("gameTestServer")
forgeTemplate("gameTestServer")
// Forge runs only the @GameTestHolder classes of the namespaces listed here.
vmArgs("-Dforge.enabledGameTestNamespaces=mymod")
// Without a list of its own, Forge can load a copy of the mod without the tests.
mods.create("mymod") {
sourceSet(main)
sourceSet(gametest)
}
}
}
}

Each run becomes a Gradle task. From the loader’s project:

Run the GameTests
./gradlew runGametest

The server runs every test, logs each result with its message, and stops.

As tests grow, split them into classes and return them all from one generator per loader, as the GameTestFunctions section shows.