Run the Minecraft client inside your CI/CD pipeline.
Mc-Runtime-Test | HMC | HMC-Specifics | HMC-Optimizations
Warning
NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.
This action runs the Minecraft client inside your CI/CD pipeline.
When coding Minecraft mods many bugs can only be caught at runtime. Between many different versions and modloaders manual testing becomes laborious. Additionally, many (e.g. mapping or mixin related) bugs only occur when running against a Minecraft instance that has been launched by a launcher, instead of some IDE or gradle task.
This action runs the Minecraft client using the HeadlessMC launcher. It uses Xvfb as a virtual framebuffer that allows us to run the game headlessly. HeadlessMC can also be used to patch the lwjgl library.
This project also provides mods for several versions, which all do one thing: join a single-player world, wait for chunks to load, and then quit the game after a few seconds. This way you can already run simple boot tests, checking whether the game will boot with your mod. Mods for newer versions also execute all gametests registered.
Mc-Runtime-Test currently supports the following Minecraft versions and modloaders:
You can configure it to use any other version, but in that case you need to set mc-runtime-test
to none
and provide another way for the game to exit, or the workflow will run indefinitely.
Version | Forge | Fabric | NeoForge |
---|---|---|---|
1.21 | ✅ | ✅ | ✅ |
1.20.2 - 1.20.6 | ✅ | ✅ | ✅ |
1.20.1 | ✅ | ✅ | |
1.19 - 1.19.4 | ✅ | ✅ | - |
1.18.2 | ✅ | ✅ | - |
1.17.1 | ✅ | ✅ | - |
1.16.5 | ✅ | ✅ | - |
1.12.2 | ✅ | - | |
1.8.9 | ✅ | - | |
1.7.10 | ✅ | - |
Versions marked with
name: Run the MC client
on:
workflow_dispatch:
jobs:
run:
runs-on: ubuntu-latest
steps:
# ... run actions to build your client
# Copy the jar that you build to the mods folder
- name: Copy mod jar to mods
run: mkdir -p run/mods && cp build/libs/<your-mod>.jar run/mods
# Call this Action to run the client
- name: Run the MC client
uses: 3arthqu4ke/mc-runtime-test@2.2.0
with:
mc: 1.20.4
modloader: fabric
regex: .*fabric.*
mc-runtime-test: fabric
java: 17
An example workflow in action can be found here.
mc
: The MC version to use, e.g.1.20.4
.modloader
: The modloader to install with HeadlessMC (forge
,neoforge
orfabric
).regex
: A Regex to match the MC version to launch (can in most cases just be.*<modloader>.*
, like.*fabric.*
, very old versions of forge might start with an uppercaseForge
).java
: The Java version to use, e.g.17
.java-distribution
: The Java distribution to use, by default we use the adopt distribution.dummy-assets
: HeadlessMC will use dummy assets to not download all the MC assets. Can be disabled by setting this tofalse
.mc-runtime-test
: The MC-Runtime-Test jar to download (none
,lexforge
,fabric
orneoforge
). When usingnone
you need to provide a way for the game to exit or the action will run indefinitely and time out.xvfb
: Iftrue
(default), runs the game with Xvfb, if false, you should probably use the -lwjgl option in headlessmc.headlessmc-command
: Allows you to customize the arguments of the headlessmc command.fabric-api
: Downloads the fabric-api. (Default is none, an example value would be 0.97.0, to download 0.97.0+<mc>)fabric-gametest-api
: Downloads the fabric-gametest-api to run gametests. (Default is none, an example value would be 1.3.5+85d85a934f).download-hmc
: Whether to download headlessmc or not, if not you need to supply a headlessmc-launcher.jar. Default istrue
.hmc-version
: The headlessmc version to download.
MC-Runtime-Test does not provide a framework for full integration tests.
You can, however,
use Minecrafts own Game-Test Framework.
MC-Runtime-Test will basically execute the /test runall
command after joining the world.
On Neoforge/Lexforge gametest discovery does really not work in production, you might need to register
them themselves and use other hacks
to get the structure templates correctly, but we are working on it.
You can also use the headlessmc-command
input to specify additional SystemProperties with the --jvm
flag.
E.g. -DMcRuntimeGameTestMinExpectedGameTests=<int>
to specify how many gametests you expect to be executed
at minimum and otherwise fail if not enough gametests have been found.
unimined by wagyourtail, a gradle plugin allowing us to support multiple modloaders, has greatly accelerated the development of mc-runtime-test