Ward

A testing framework for Minecraft datapacks using mcfunction.

Ward lets you write automated tests for your datapacks as plain .mcfunction files in a test/ folder, executed through Minecraft's GameTest framework on a real server — in-game, headless in CI, or live-reloading in daemon mode while you develop.

Ward is two pieces that work together:

• The mod (Modrinth) — a Fabric mod adding the test commands (/assert, /await, /fail, /succeed, /dummy) and a headless test server that streams results live.
• The tooling (PyPI) — the mcward CLI that installs test servers, runs your packs against one or several Minecraft versions with a live display, plus a beet plugin adding beet test.

Quick start

Write tests in your datapack under data/<namespace>/test/:

# @timeout 100
summon minecraft:armor_stand ~ ~ ~ {Tags: ["target"]}
assert entity @e[tag=target]
await not entity @e[tag=target]

Test files support directives (# @timeout, # @optional, # @dummy, # @template, # @environment, # @skyaccess) and the full command set:

Console

uv tool install mcward[cli]   # or: pip install mcward[cli]
mcward test                   # discovers datapacks, picks compatible versions, runs

In-Game

• /test run <name> - Run a specific test
• /test runall [namespace] - Run all tests (optionally filtered by namespace)
• /test runfailed - Re-run previously failed tests
• /test runthis - Run the closest test
• /test runthese - Run all tests within 200 blocks

Documentation

• Test commands — /assert, /await, /fail, /succeed
• Directives — # @timeout, # @environment, ...
• Dummies — fake players and the /dummy command
• Test environments — world setup/teardown around tests
• Command-line tooling — the mcward CLI and beet test

Commands

mcward test [-v <version>]... [-p <pack>]... [selector]   # run tests (default command)
mcward install [version]                                  # install a test server
mcward start / stop / status                              # manage the test daemon
mcward list [--remote]                                    # installed / available versions
beet test                                                 # build the beet project and test it