Ward

Ward lets you write automated tests for your datapacks as plain .mcfunction files in a test/ folder.

Ward is two pieces that work together:

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

Quickstart

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

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:

Command	Purpose
assert [not] block/entity/data/score/chat/biome/predicate/items ...	Assert immediately
await [not] ...	Retry every tick until true or timeout
await delay <time>	Pause the test
fail [message] / succeed	End the test explicitly
dummy <player> spawn/leave/jump/use/attack/mine/...	Control fake players

Documentation

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

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

Acknowledgements

Ward is heavily inspired by packtest by misode.

Ward implements packtest's full command set, so existing packtest tests run unmodified under Ward. On top of that, Ward adds a few extra commands, a CLI with multi-version runs and a live test display, and a beet test plugin.

Development

See CONTRIBUTING.md for the guidelines and workflow.

License

MPL-2.0