exo/mc-test-harness
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
should not work
1 commit 1 branch 0 tags 32 KiB
  • Shell 83.3%
  • Python 16.7%
Find a file
Exact
Exo d9ca6488d7
 Initial commit — carve out from voxy-vulkan-mac 
Standalone copy of the auto-test.sh + bin2png.py harness so other Minecraft
mod projects can reuse it without taking on Voxy or Vulkan dependencies.

100% original work — no Voxy code, no MCRcortex copyright. Released MIT.

Adapted-for-other-mods notes in README.
2026-04-27 14:53:28 +02:00
scripts Initial commit — carve out from voxy-vulkan-mac 2026-04-27 14:53:28 +02:00
LICENSE Initial commit — carve out from voxy-vulkan-mac 2026-04-27 14:53:28 +02:00
README.md Initial commit — carve out from voxy-vulkan-mac 2026-04-27 14:53:28 +02:00

README.md

mc-test-harness

Generic, headless test harness for Fabric Minecraft mods. Carved out of the voxy-vulkan-mac project so other mod work can reuse it without dragging in Voxy or Vulkan dependencies.

What it does

  • scripts/auto-test.sh — boots a Fabric MC instance via ./gradlew runClient with offline auth + --quickPlaySingleplayer pointed at a deterministic test world, lets it run for N seconds, and reports diagnostic log lines + screenshots back to the caller.
    • EXIT/INT/TERM trap guarantees the MC process always dies, even on crash / set -e bail / ^C. No more zombie MC instances eating your CPU.
    • Polls the MC log for early-fail markers and bails immediately on init/composite errors instead of waiting for the timeout.
    • devworld.template mechanism: keep a clean snapshot world, restore from it before each run for deterministic state.
    • Screenshot mode: writes raw RGBA bins via the mod's GameRenderer TAIL hook, then converts to PNG.
    • Panorama mode: rotates the player yaw 0/90/180/270 over four spaced frames, captures each.
  • scripts/bin2png.py — converts the harness's VOXSHOT-headered raw RGBA dumps into PNGs (bottom-up flip, no external deps).

Requirements

  • macOS or Linux
  • bash 4+
  • python 3.6+
  • The mod under test must:
    • Use Fabric Loom + offer a runClient Gradle task
    • Implement an end-of-frame screenshot capture (the harness expects bins at run/logs/voxy-vk-shot*.bin — adapt the path for your mod)
    • Print a diagnostic log line per Nth frame so the harness can confirm the mod is rendering

Adapt for your mod

The script as-shipped is hardcoded for the voxy-vulkan-mac project. To adapt:

  • Change the PROJECT path at the top of auto-test.sh
  • Update EXTRA_PROPS to match your mod's -P flag conventions
  • Update the EXPECTED_SHOTS array if your screenshot filenames differ
  • Update the early-fail regex if your mod logs different markers

A future v2 should make these all CLI flags or an auto-test.config file. PRs welcome.

License

MIT — see LICENSE.