Minecraft:GameTest

Template:Redirect Template:Redirect GameTest is an automated Template:Wikipedia framework for Template:Wikipedia aspects of Minecraft:Minecraft. Each test contains a structure, parameters for how the test gets executed, and optional code to further specify the test behavior.

Java Edition

Test instance

File:Test instance block UI.png

UI of test instance block

Test instance can be defined in a datapack by creating a Minecraft:JSON file in the Template:Cd registry. Players can inspect information about them using a Template:BlockLink. 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. (Template:NbtTemplate:Nbt)
• It is associated with a Template:Nbt, 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 Minecraft:test instance definition.

Block-based

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

• Template:BlockSprite Start: A Minecraft:redstone pulse is triggered when the test starts.
• Template:BlockSprite Log: Logs a message to the log file when powered by redstone.
• Template:BlockSprite Fail: Fails the test when powered by redstone.
• Template:BlockSprite 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 test functions to determine a test's success or failure. They are meant to be used by Mojang internally and by Minecraft:mod developers.

The game provides the GameTest framework interfaces through the net.minecraft.gametest.framework package (Mojang mapping). Minecraft:Mod loaders typically to provide their own testing API for developers to use the GameTest framework, there are documentation available for Fabric and NeoForge.

A test function must be registered in the test_function registry to be referenced in the test instance. The Template:Nbt field in the test instance definition should contain the Minecraft:resource location of the test function.

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 Minecraft:JSON file in the Template:Cd registry or directly specified the environment inline with the Template:Nbt field. It can also use the test environment of the vanilla data package Template:Cd, which is empty preconditions.

Test command

Template:Main The Template:Cmd command exists to execute and manage block-based tests. Some notable sub-commands include:

• /test (run|runmultiple) <tests> ... sub-commands can run specific test(s) for a number of times by their identifier.
• /test (runclosest|runthat|runthese) ... sub-commands can run test(s) based on the player's location.
• /test (resetclosest|resetthat|resetthese) sub-commands reset the test structures for any tests.
• /test locate <tests> locates test in loaded chunks.

Server.jar entry point

The net.minecraft.gametest.Main entry point is included in Minecraft:server.jar which starts a server, runs all available game tests and then exits. It can be invoked in the command line, such as:

<syntaxhighlight lang="bash"> java -DbundlerMainClass="net.minecraft.gametest.Main" -jar server.jar [<options>] </syntaxhighlight>

Command-line options

• Template:Cd - Shows usage information
• Template:Cd - Set a folder of datapacks to include in the world
  • Any zip file or folder with a Template:Cd file is included
• Template:Cd - Exports results in a junit-like XML report at the given path
• Template:Cd - 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
• Template:Cd - The path to where the test server world will be created
  • Any existing folder will be replaced
  • Default: Template:Cd
• Template:Cd - Enables test verification
  • Runs the tests specified with Template:Cd or Template:Cd 100 times for each 90 degree rotation step
  • Default: Template:Cd

Exit code

The game will yield the following Template:Wikipedia 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

Bedrock Edition

The GameTest framework can be accessed through the @minecraft/server-gametest module from the Minecraft:Script API. The module must be added as a dependency in the Minecraft:manifest.json. It contains many Template:Ws used for Template:W of any game objects' behaviors and interactions in a controlled testing environment.<ref>Template:Cite</ref> Developers can use these interfaces for:

• Asserting certain conditions for Minecraft:blocks, Minecraft:entities, and other game objects;
• Getting in-game information such as Minecraft:dimension, Minecraft:position, entities and blocks information;
• Modifying the testing environment by setting block permutation (block type and states data), sending Minecraft:redstone interactions, etc;
• Spawning entities controlled by the script with predictable mob behaviors;
• Creating simulated Minecraft:players for testing behaviors and interactions with other game objects;<ref>Template:Cite</ref>
• And other testing functionalities, further reading.

A testing environment can be created from a unit test (also called a GameTest), which contains a test function registered from the script, and a reference to a Minecraft:.mcstructure file exists in the behavior pack.<ref>Template:Cite</ref><ref name="registration-builder"/> Users can register a new unit test using GameTest#register(testClassName, testName, testFunction) method with additional builder parameters, such as .maxTicks(ticks) that indicates the test may take amount of ticks to run, .maxAttempts(attempts) which specifies how many attempt the test can run, and more.<ref name="registration-builder">Template:Cite</ref>

After the unit test is registered, it is loaded in the world, and can be run using the Template:Cmd command, referenced by <testClassName>:<testName>. When ran, the game spawns the test structure and calls the test function previously defined in the script. The unit test may succeed or fail depending on the test function, which usually contain instructions for testing behaviors and interactions in the testing environment.

History