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

@Experimental package net.fabricmc.fabric.api.client.gametest.v1
Provides support for client gametests. To register a client gametest, add an entry to the fabric-client-gametest entrypoint in your fabric.mod.json. Your gametest class should implement FabricClientGameTest.

Loom provides an API to configure client gametests in your build.gradle. It is recommended to run gametests from a separate source set and test mod: 

     
     fabricApi.configureTests {
         createSourceSet = true
         modId = 'your-gametest-mod-id'
     }

Lifecycle

Client gametests are run sequentially. When a gametest ends, the game will be returned to the title screen. When all gametests have been run, the game will be closed.

Threading

Client gametests run on the client gametest thread. Use the functions inside ClientGameTestContext and other test helper classes to run code on the correct thread. Exceptions are transparently rethrown on the test thread, and their stack traces are mutated to include the async stack trace, to make them easy to track. You can disable this behavior by setting the fabric.client.gametest.disableJoinAsyncStackTraces system property.

The game remains paused unless you explicitly unpause it using various waiting functions such as ClientGameTestContext.waitTick(). A side effect of this is that the results of your code may not be immediate if the game needs a tick to process them. A big example of this is key bindings, although some key binding methods have built-in tick waits to mitigate the issue. See the TestInput documentation for details. Another pseudo-example is effects on the server need a tick to propagate to the client and vice versa, although this is related to packets more than the fact the game is suspended (see the network synchronization section below). A good strategy for debugging these issues is by taking screenshots, which capture the immediate state of the game.

A few changes have been made to how the vanilla game threads run, to make tests more reproducible. Notably, there is exactly one server tick per client tick while a server is running (singleplayer or multiplayer). There is also a limit of one client tick per frame.

Network synchronization

Network packets are internally tracked and managed so that they are always handled at a consistent time, always before the next tick. Calling waitTick() is always enough for a server packet to be handled on the client or vice versa.

If your mod interacts with the network code at a low level, such as by directly hooking into the Netty pipeline to send or handle packets, you may need to disable network synchronization. You can do this by setting the fabric.client.gametest.disableNetworkSynchronizer system property.

Default settings

The client gametest API adjusts some default settings, usually for consistency of tests. These settings can always be changed back to the default value or a different value inside a gametest.

Game options

Setting name Gametest default Vanilla default Reason
Tutorial step NONE MOVEMENT Consistency of tests
Cloud render mode OFF FANCY Consistency of tests
Onboard accessibility false true Would cause the game test runner to have to click through the onboard accessibility prompt
View distance 5 10 Speeds up loading of chunks, especially for functions such as TestClientWorldContext.waitForChunksRender()
Music volume 0.0 1.0 The game music is annoying while running gametests

World creation options

These adjusted defaults only apply if the world builder's consistent settings have not been set to false.
Setting name Gametest default Vanilla default Reason
World type FLAT DEFAULT Creates cleaner test cases
Seed 1 Random value Consistency of tests
Generate structures false true Consistency of tests and creates cleaner tests
Do daylight cycle false true Consistency of tests
Do weather cycle false true Consistency of tests
Do mob spawning false true Consistency of tests

Dedicated server properties

Setting name Gametest default Vanilla default Reason
online-mode false true Allows the gametest client to connect to the dedicated server without being logged in to a Minecraft account
sync-chunk-writes true on Windows, false on other operating systems true Causes world saving and closing to be extremely slow (on the order of many seconds to minutes) on Unix systems. The vanilla default is set correctly in singleplayer but not on dedicated servers.
spawn-protection 0 16 Spawn protection prevents non-opped players from modifying the world within a certain radius of the world spawn point, a likely source of confusion when writing gametests
max-players 1 20 Stops other players from joining the server and interfering with the test