PackTest

PackTest provides developers with the ability to create game tests directly within data packs. Tests are *.mcfunction files located in a special test folder. This tool is perfect for verifying the functionality of custom data packs.

Usage Example

data/example/test/foo.mcfunction

#> Summons an armor stand and verifies its presence
# @template example:small_platform
# @optional

summon armor_stand ~1.5 ~1 ~1.5
execute positioned ~1.5 ~1 ~1.5 run assert entity @e[type=armor_stand,dx=0]

assert predicate example:test

setblock ~1 ~1 ~1 grass_block
execute if block ~1 ~1 ~1 stone run succeed

fail "Oh no"

Asynchronous Testing

Test functions support asynchronous execution using the await keyword!

setblock ~ ~ ~ stone
summon item ~ ~6 ~

await entity @e[type=item,distance=..2]

await delay 1s

data merge entity @e[type=item,distance=..2,limit=1] {Motion: [0.0, 0.01, 0.0]}

Running Tests

Tests can be run directly in the game using the test command:

• test runall — runs all available tests
• test runall <namespace> — executes tests from the specified namespace
• test run <test> — runs a specific test by name
• test runfailed — repeats all previously failed tests
• test runthis — runs the nearest test
• test runthese — executes all tests within a 200-block radius

Automatic Test Server

Tests can also be run automatically, for example, in a continuous integration environment. When the -Dpacktest.auto parameter is set, the game test server automatically starts with loaded tests. The process terminates after all tests are completed, and the exit code corresponds to the number of failed tests.

The -Dpacktest.auto.annotations parameter generates GitHub annotations for all testing errors and resource loading issues.

Testing Commands

fail

• fail <text_component> — fails the current test and exits the function

succeed

• succeed — always succeeds the current test and exits the function

assert

• assert <condition> — if the condition fails, fails the test
• assert not <condition> — if the condition succeeds, fails the test

await

• await <condition> — similar to assert, but retries the check every tick until success or timeout
• await not <condition> — retries the check until the condition fails
• await delay <time> — waits for the specified amount of time with unit

Check Conditions

• block <position> <block> — checks if the block at the specified position matches
• data ... — checks NBT data using the execute if score syntax
• entity <selector> — checks for entities matching the selector
• predicate <predicate> — checks a predicate in the data pack
• score ... — checks scores using the execute if score syntax
• chat <pattern> [<receivers>] — checks if a chat message matches the regex pattern

Test Players (Dummies)

Artificial players are created using the /dummy command. Dummies do not save data to disk and do not load skins.

Main dummy management commands:

• dummy <name> spawn — creates a new dummy
• dummy <name> respawn — respawns the dummy after death
• dummy <name> leave — removes the dummy from the server
• dummy <name> jump — makes the dummy jump
• dummy <name> sneak [true|false] — enables/disables sneak mode
• dummy <name> sprint [true|false] — enables/disables sprint
• dummy <name> drop [all] — drops the item from hand
• dummy <name> swap — swaps items between hands
• dummy <name> selectslot — selects a different hotbar slot
• dummy <name> use item — uses the item in hand
• dummy <name> use block <position> [<direction>] — uses the item on a block
• dummy <name> use entity <entity> — uses the item on an entity
• dummy <name> attack <entity> — attacks an entity
• dummy <name> mine <position> — mines a block

Testing Directives

Tests can be customized using special comments at the beginning of the function:

• @template — specifies the structure template for the test (default: empty 1x1x1 structure)
• @timeout — sets the test timeout (default: 100)
• @optional — allows the test to fail (default: false)
• @dummy — creates a dummy at the start of the test and sets @s to it
• @batch — test batch name (default: packtestBatch)
• @beforebatch — command to run before the test batch
• @afterbatch — command to run after the test batch