mc-runtime-test

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

⚠️ 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:

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.