Skip to content
server

GitHub Action

testermc

v2.0.3 Latest version

testermc

server

testermc

Tests a Minecraft Plugin on a Minecraft Server

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: testermc

              
  uses: gmitch215/[email protected]
Learn more about this action in gmitch215/TestMC

Choose a version

🔬 TestMC

A GitHub Action to test Minecraft Plugins on a Server for a Specific Version

A GitHub Action that sets up a Minecraft Server/Server Proxy to test your mods and plugins on.

Note

By using this GitHub Action you agree to the official Minecraft EULA.

This GitHub Action is not affiliated with Mojang or Microsoft.

📦 Setup

Warning

Because of the way the server exists, it is impossible to determine when the server crashes or an error is detected in the server. This is planned to be changed in a future release.

Example Files

Simple Build

jobs:
  test:
    # ...
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
      - uses: gmitch215/TestMC@v2
        with:
          # Runs Latest Version
          path: 'path/to/plugin.jar'
          runtime: 'paper'
          time: 120

Globs are also supported, in which case the first result is used:

jobs:
  test:
    # ...
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
      - uses: gmitch215/TestMC@v2
        with:
          path: 'path/to/plugin/myplugin-*.jar'
          runtime: 'paper'
          version: '1.21.1' # Specify a Version
          time: 240

Using Matrix Builds

Tip

Building a server (especially using buildtools) takes 3-5 minutes, on top of the additional server runtime. It is recommended that you utilize matrix builds to speed up runtime.

jobs:
  test:
    strategy:
      matrix:
        runtime: ['paper', 'spigot']
        version: ['1.20.1', '1.20.2', '1.20.4', '1.20.6']
    # ...
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'
      - uses: gmitch215/TestMC@v2
        with:
          path: 'path/to/plugin.jar'
          runtime: ${{ matrix.runtime }}
          version: ${{ matrix.version }}
          time: 120
          commands: |
            version

Using a Directory

You can copy a directory into the server directory before the server starts. This can be useful for specifying a server.properties, custom world files, etc:

jobs:
  test:
    # ...
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '21'
      - uses: gmitch215/TestMC@v2
        with:
          path: 'path/to/plugin.jar'
          runtime: 'purpur'  
          version: '1.21'
          time: 360
          files: | # Supports Globs; Can contain anything you want to copy
            .github/test-server/* 
            server.properties
          commands: |
            customplace 0 10 0 stone
            kill @e[type=!player]

All Options

Option Name Description Required Default Value
path The path to the plugin to test. true
runtime The runtime option to use. true
version The runtime (Minecraft) version to use. false latest version
time How long the server should run for, in seconds. false 120
build Optionally specify a specific build number for your inputted runtime. on fabric servers latest build
flags Additional Flags to pass to the server jar. false ''
experimental Whether to allow experimental versions. false false
use-similar-versions Whether to find a similar version (determined by its protocol version) to use if the inputted version is not available. false true
commands Commands to execute on the server after startup has finished. false ''
files A directory to copy into the server directory, before it starts. false ''

📕 Platforms

Versions

Minimum Version: 1.8

Latest Version: 1.21.3 (11-1-2024)

Latest Experimental Version: 1.18-rc3 (1-31-2024)

Warning

The following versions are not guaranteed to be available:

  • 1.8.1, 1.8.2, 1.8.9
  • 1.9.1, 1.9.3,
  • 1.10.1
  • 1.16

Runtimes

Servers

  • CraftBukkit (craftbukkit)
  • SpigotMC (spigot)
    • Runtimes using BuildTools (craftbukkit and spigot) will download the latest similar version of the runtime. For example, if you specify 1.21, it will download the latest similar version, such as 1.21.1.
  • Paper (paper)
  • Purpur (purpur)
  • Fabric (fabric)
    • Your build option is required and should be specified as loader version/installer version (e.g. 0.15.11/1.0.1).
    • To find your build, visit the Server Downloader.

Server Proxies

🧑🏾‍💻 License

This project is licensed under the LGPL-3.0 License, similar to other Bukkit projects.