GameTest

GameTest or Game Test is an automated end-to-end (E2E) testing framework for testing aspects of Minecraft. Each test contains a structure, parameters for how the test gets executed, and optional code to further specify the test behavior.

Java Edition

Server.jar entry point

The net.minecraft.gametest.Main entry point is included in server.jar which starts a server, runs all available game tests and then exits.

You can invoke this entrypoint with:

$ java -DbundlerMainClass="net.minecraft.gametest.Main" -jar server.jar [<options>]

Command-line options

• --help - Shows usage information
• --packs <path> - Set a folder of datapacks to include in the world
  • Any zip file or folder with a pack.mcmeta file is included
• --report <path> - Exports results in a junit-like XML report at the given path
• --tests <selection> - Specify which tests to run with a selection - a wildcard expression matching namespace test instance IDs
  • If omitted, or used with an empty ID, runs all tests
• --universe <path> - The path to where the test server world will be created
  • Any existing folder will be replaced
  • Default: gametestserver
• --verify <boolean> - Enables test verification
  • Runs the tests specified with test or testNamespace 100 times for each 90 degree rotation step
  • Default: false

Exit code

The game will yield the following exit codes depending on the scenario:

Scenario	Exit code
All tests pass	0
Any test fails	(number of failures)
Server shut down without starting tests	-1
Game crashed	1

Test instance

UI of test instance block

Test instance can be defined in a datapack by creating a JSON file in the test_instance registry. You can inspect information about them using a test instance block. A test instance has the following properties:

• It belongs to a test environment, which groups the test and further specifies the environment in which the test is run in. ([NBT Compound / JSON Object][String] batch)
• It is associated with a [String] structure, which should contain all the blocks and entities it needs to be run. The structure can be easily altered with the test instance block.
• It can either be a block-based test or a function test. More information is available below.

There are more configuration available for test instances. For more information on the format, see test instance definition.

Block-based

In block-based tests, Test blocks are used inside the test structure to control the test logic using redstone signal.

• Start: A redstone pulse is triggered when the test starts.
• Log: Logs a message to the log file when powered by redstone.
• Fail: Fails the test when powered by redstone.
• Accept: Completes the test when powered by redstone.

If a race condition occurs, the first test block activated always wins.

Function

"Function" tests rely on built-in functions to determine a test's success or failure. They are meant to be used by Mojang internally and by mod developers.

The [String] function field in the test instance definition should contain the resource location of the test function.

It is recommended to use a mod loader and their respective API provided to use function tests. Currently, no major mod loaders support function tests.

Test environment

Test environment is a way to group up test instances and give them the right preconditions to run. It can be defined in a datapack by either creating a JSON file in the test_instance registry or directly specified the environment inline with the [NBT Compound / JSON Object] batch field.

Bedrock Edition

Building sets of GameTests requires a behavior pack, and writing some simple JavaScript code.

History

November 9, 2020							Henrik Kniberg demonstrated GameTest, a test framework used internally by Mojang, on the Agile with Jimmy YouTube channel.
[hide]Java Edition
1.15			19w34a				References to GameTest added in the game's code. Most of the framework is stripped, since the rest of the game does not depend on it.
1.17			21w13a				GameTest related code is now exposed for mod developers' use because unused parts of code are no longer removed.
1.21.5			25w03a				Overhauled the GameTest framework.
							Introduced for use with data packs.
[hide]Bedrock Edition
1.16.210			beta 1.16.210.60				Added GameTest framework.