Minecraft プラグインのテストを GitHub Actions に組み込む

はじめに

私は普段 Paper API を利用してプラグインを作成しているのですが、これのテストがどうにも面倒くさくて仕方ありません。MockBukkit を筆頭にいくつかモックライブラリが存在するようですが、全ての要素を完璧にカバーしているわけではないのでちょくちょく困ってしまいます。

何をしたの

そんなわけでモックライブラリに頼らずプラグインのテストをする方法として、 GitHub Actions 内にて動作させた Minecraft サーバー上で実行する方法を採ることにしました。

構成

ワークフローファイル (長いので折りたたんでいます)

name: PaperMC Plugin Test

on:
  pull_request_target:
    types:
      - closed

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Set up JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: 'maven'

      - name: Build plugin with Maven
        run: mvn clean package

      - name: Create server directory
        run: mkdir server

      - name: Download PaperMC 1.21.3
        working-directory: ./server
        run: wget https://api.papermc.io/v2/projects/paper/versions/1.21.3/builds/83/downloads/paper-1.21.3-83.jar -O paper.jar

      - name: Accept EULA
        working-directory: ./server
        run: echo "eula=true" > eula.txt

      - name: Create plugins directory and copy plugin
        working-directory: ./server
        run: |
          mkdir plugins
          cp ../target/*.jar ./plugins/

      - name: Run PaperMC server and wait for plugin to shut it down
        working-directory: ./server
        env:
          PLATFORM: "github-actions" # 環境変数を設定
        run: |
          echo "Starting PaperMC server for plugin tests..."
          java -Xms1G -Xmx1G -jar paper.jar nogui
          echo "PaperMC server process ended."

      - name: Evaluate test results
        working-directory: ./server
        run: |
          TEST_RESULTS_FILE="plugin-test-results.txt"
          if [ ! -f "$TEST_RESULTS_FILE" ]; then
            echo "Error: Test results file '$TEST_RESULTS_FILE' not found. This indicates the plugin test did not run or output correctly."
            exit 1 
          fi

          echo "Content of $TEST_RESULTS_FILE:"
          cat "$TEST_RESULTS_FILE"
          echo "--- End of $TEST_RESULTS_FILE ---"

          if grep -q "Failed" "$TEST_RESULTS_FILE"; then
            echo "Tests FAILED: The word 'Failed' was found in '$TEST_RESULTS_FILE'."
            exit 1 
          else
            echo "Tests PASSED: The word 'Failed' was NOT found in '$TEST_RESULTS_FILE'."
          fi

起動条件

プルリクエストが閉じたとき、プルリクエストのマージ先のブランチの内容で実行される

Set up JDK 21

プラグインのビルドに必要な JDK 21 と Maven の設定を行います

Build plugin with Maven

maven のコマンドを発行してプラグインをビルドします

Create server directory

サーバーのためのディレクトリを作成します

Download PaperMC 1.21.3

プラグインが必要とするバージョンの PaperMC の jar をダウンロードします。
私が今回テストしようとしている Custom Crafter というプラグインは API バージョン 1.21.3 で構築されているので、 1.21.3 の最新ビルドを決め打ちしてダウンロードしています。

最新バージョンの jar ファイルを落としてきたり、特定バージョンの最新ビルドを落としてくるには Paper Download API を利用すると良いでしょう。

Accept EULA

サーバー初回起動時の EULA チェックをパスするために eula=true を eula.txt に書き込んでいます

Create plugins directory and copy plugin

plugins ディレクトリを作成し、ビルドしたプラグインの jar ファイルをそこへコピーします

Run PaperMC server and wait for plugin to shut it down

プラグイン内で利用する環境変数を設定し、 java -jar コマンドでサーバーを起動しています。

プラグインがここで指定した環境変数を検知してテスト専用のフェーズに入るようにしています。
そのため java コマンドを実行するだけで

• サーバーの起動
• テストの実行
• テスト結果をファイルに書き込み
• サーバーの終了

を行えるようになっています。

テスト中にエラーが発生したときは失敗扱いにしてサーバーが落ちるようにしてください。
(テストが終わらず GitHub Actions の実行可能時間を食いつぶす恐れがあります。)

Evaluate test results

プラグインがテスト結果を出力したファイルの中身を grep でざっくり検査して Failed が含まれている場合はコード 1 でアクションを失敗させ、そうでない場合は正常に終了するようにしています

実行結果の例

おわりに

ItemStack などのテストが全然出来なかったので、この方法を採用することでテスト出来るようになったのは大変助かります。モックライブラリがバージョンアップに対応するまで待たなくても良いのも利点として挙げられますね。

ただ Player などプレイヤーが参加できない環境では利用が難しい機能のテストを行う場合は、モックを利用するか設計を見直すなどの対応が求められそうです。

条件を変更して開発ブランチではコミットごとに実行されるようにすると、ローカルでのテストと体験が近くなって更に便利になるかもしれません。(実行時間と月ごとの利用制限(無料枠で月 2000 分)には十分ご注意ください)

宣伝

それと一番最後になりますが、この記事にも登場しているカスタムレシピのための API を提供する Custom Crafter を是非利用してみてください！

複数素材の組み合わせや定形・不定形レシピのサポートなど他にも数多くのカスタムレシピを作成・提供するのを助ける API が利用できます。
詳しい利用方法は README.md や GitHub 内の Wiki をご参照ください

それでは良きプラグインライフを！