Mc-Runtime-Test

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.21.3	✅	✅	✅
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 ⚠️ have not been tested yet, due to not being supported by HeadlessMC, e.g. fabric legacy versions.

Example

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/[email protected]
        with:
          mc: 1.20.4
          modloader: fabric
          regex: .*fabric.*
          mc-runtime-test: fabric
          java: 17

An example workflow in action can be found here. An example for a large matrix workflow which tests 20 different versions of Minecraft at once can be found here.

Inputs

• mc: The MC version to use, e.g. 1.20.4.
• modloader: The modloader to install with HeadlessMC (forge, neoforge or fabric).
• 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 uppercase Forge).
• 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 to false.
• mc-runtime-test: The MC-Runtime-Test jar to download (none, lexforge, fabric or neoforge). When using none you need to provide a way for the game to exit or the action will run indefinitely and time out.
• xvfb: If true (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 is true.
• hmc-version: The headlessmc version to download.

Running your own tests

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.

Credits

unimined by wagyourtail, a gradle plugin allowing us to support multiple modloaders, has greatly accelerated the development of mc-runtime-test