mcward 1.0.0

A testing framework for Minecraft datapacks using mcfunction.

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

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

• Test commands — /assert, /await, /fail, /succeed
• Directives — # @timeout, # @environment, ...
• Test environments — world setup/teardown around tests
• Dummies — fake players and the /dummy command
• 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

Development

Requires uv, just, a JDK, and Gradle (wrapper included).

uv sync --all-extras          # set up the workspace
just check                    # lint + types + unit tests
just verify                   # build the mod and run the full integration suite

Layout: the Fabric mod lives in src/, the Python packages in packages/ (mcward-core, mcward-cli, mcward-beet), tooling in tools/, and the integration fixture datapacks in tests/packs/. Releases are automated from the versions committed to the tree — see CONTRIBUTING.md for the guidelines and workflow.

License

MPL-2.0