Run the Minecraft client inside your CI/CD pipeline.

MC-Runtime-Test | HMC | HMC-Specifics | HMC-Optimizations

This is not an official Minecraft product. It is not approved by or associated with Mojang or Microsoft.

---

MC-Runtime-Test is a mod that boot-tests the Minecraft client. Manual testing for different Minecraft versions and modloaders can be time-consuming, especially when bugs occur only in runtime environments launched via a Minecraft launcher. This project helps streamline that process by automating the client launch and basic test execution.

Features

• Utilizes HeadlessMC for headless Minecraft launches.
• Employs Xvfb for virtual framebuffer support.
• Includes a lightweight mod that:
  • Join a single-player world.
  • Wait for chunks to load.
  • Quit the game after a few seconds.
• Supports Minecraft’s GameTest Framework to run registered tests for newer versions.

Supported Minecraft Versions and Modloaders

Version	Forge	Fabric	NeoForge
26.1 - 26.2	✔️	✔️	✔️
1.21 - 1.21.11	✔️	✔️	✔️
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 a warning symbol have limited or untested support.

---

Quickstart Example

Below is a basic workflow example to run the Minecraft client using MC-Runtime-Test.

---
name: Run Minecraft Client

on:
  workflow_dispatch:

env:
  java_version: 25

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Install Java
        uses: actions/setup-java@v4
        with:
          java-version: ${{ env.java_version }}
          distribution: "temurin"

      - name: [Example] Build mod
        run: ./gradlew build

      - name: [Example] Stage mod for test client
        run: |
          mkdir -p run/mods
          cp build/libs/<your-mod>.jar run/mods

      - name: Run MC test client
        uses: headlesshq/mc-runtime-test@4.5.1 
        with:
          mc: 26.1.1
          modloader: fabric
          regex: .*fabric.*
          mc-runtime-test: fabric
          java: ${{ env.java_version }}

More examples:

• Fabric Workflow Example
• Matrix Workflow Testing Multiple Versions

---

Inputs

The following table summarizes the available inputs for customization:

Input	Description	Required	Example
mc	Minecraft version to run	Yes	1.20.4
modloader	Modloader to install	Yes	forge, neoforge, fabric
regex	Regex to match the modloader jar	Yes	.*fabric.*
java	Java version to use	Yes	8, 16, 17, 21
mc-runtime-test	MC-Runtime-Test jar to download	Yes	none, lexforge, neoforge, fabric
dummy-assets	Use dummy assets during testing		true, false
xvfb	Runs the game with Xvfb		true, false
headlessmc-command	Command-line arguments for HeadlessMC		--jvm "-Djava.awt.headless=true"
fabric-api	Fabric API version to download or none		0.97.0, none
fabric-gametest-api	Fabric GameTest API version or none		1.3.5+85d85a934f, none
download-hmc	Download HeadlessMC		true, false
hmc-version	HeadlessMC version		2.10.0, 1.5.0
cache-mc	Cache .minecraft (true defaults to blacksmith)		github, blacksmith, true, false

---

Caching

MC-Runtime-Test optionally caches .minecraft to improve execution time. By default cache-mc is set to github, which uses actions/cache. Set cache-mc to false to disable caching.

Another option is blacksmith for blacksmith/cache. Simply follow the instructions here to enable blacksmith for your repositories and enable the cache-mc input.

Running Your Own Tests

MC-Runtime-Test supports Minecraft’s Game-Test Framework. It executes /test runall upon joining a world.

Tip: Currently, Forge and NeoForge GameTest discovery may require additional setup, hacks, or other modifications to register structure templates correctly. We expect to simplify this for future releases.

You can also use the headlessmc-command input to specify a JVM argument to enforce the minimum number of GameTests you expect to be executed:

-DMcRuntimeGameTestMinExpectedGameTests=1

---

Acknowledgments

Special thanks to wagyourtail for the unimined Gradle plugin, which enabled multi-modloader support and accelerated development of this project.

---