When a test begins to run, the game will place the structure associated with the test in the world. This happens before the first tick. The structure name is derived from the name of the class containing the test method (converted to lower case), separated by a period from the lower case method name. The method name can be overriden by specifying the name in the template parameter of the @GameTest annotation.
Examples:
Test is defined in class mypackage.MyTests, method testABC, no template is specified: The structure name is minecraft:mymod.testabc (without Fabric), or mymod:mytests.testabc (with Fabric and mod id mymod).
If template is mystructure, then the structure name would be minecraft:mytests.mystructure (without Fabric), or mymod:mytests.mystructure (with Fabric).
Fabric Specific:
When fabric-gametest is used, the structure name will be prefixed by your mod's resource namespace by default (mymod:). If the template name is specified in the annotation, Fabric will not add the prefix automatically.
A test can specify a number of setup ticks. During these ticks, no further action will be taken by the testing framework and everything else in the test will be delayed accordingly. Specifying setup ticks automatically shifts all other tick numbers in the test accordingly.
The is useful for testing fluids or redstone contraptions that should settle first before running assertions in the test code.
The number of setup ticks is 0 by default but can be set in the @GameTest annotations setupTicks attribute.
On the first tick after placing the structure and after any specified setup ticks, the actual test method will be executed. It takes a GameTestHelper as its only argument, which is used to define assertions more easily.
The test method can make assertions immediately, or it can use the test helper to assert at a later time.
Test sequences in total may not run for longer than the timeoutTicks specified on the @GameTest annotation (timeoutTicks).
The GameTestHelper offers runAtTickTime, which runs an action once on a given tick relative to the first tick of the test (excluding setup ticks).
There's also failIfEver, which will run a given action on every tick until the last tick of the test (see timeoutTicks). The action should contain some form of assertion that will fail the test if it ever fails on any subsequent tick.
Sequences of actions and assertions (both with delays) can be created via GameTestHelper.startSequence.
If a test has any sequences, one of them has to flag the test as done (either by failing or suceeding the test via the helper) before the timeout tick is reached, otherwise the test will fail.
The steps in a sequence will be executed in order without waiting until the next tick. But if a step throws an exception, the sequence will be suspended until the next tick, and then retried. If this persists until the timeout, the last thrown exception is reported as a test failure.
The @GameTest annotation allows specifying a number of attempts / required successes to help with flaky tests that rely on some form of randomness or are flaky for other reasons. This section needs to be expanded upon.