メインコンテンツまでスキップ

プラグインのテスト

テストの実行についての概要を説明しています。

概要​

この機能は, あらかじめ定義されたシナリオを実行し, 実行に成功したかどうかを判定してプラグインの正常性を検証して, プラグイン開発者がプラグインの品質を継続的に維持することを支援します。

Scenamatica では, シナリオテスト と呼ばれるテスト手法を実現できます。 シナリオテストはプレイヤの操作をシナリオ通りに再現し, それによってプラグインの正常性を検証するものです。

テストの考え方​

プラグインのテストは, プラグインの機能が正常に動作するかどうかを確認するために行います。
例えば, 個々のメソッドやクラスのテストは, JUnit や Mockito などのユニットテストフレームワークを使って行います。また E2E テストに置いても, 例えば Web 分野では Selenium などのツールを使って行います。
しかしながら, PaperMC プラグインのテストは, これらのツールやフレームワークのみでは十分なテストを行うことができません。
そこで Scenamatica によるシナリオテストを用いることで, 安心安全なプラグインを開発できます。

シナリオ​

テストを始めるには, まずテストをしたいプラグインの機能ごとに シナリオファイルを記述する必要があります。

Scenamatica はあなたが作成した機能の発火条件や, それらにどのような結果が期待されているかを知りせん。 ですから, プラグインの開発者が, プラグインの正しい動作（期待される動作）を Scenamatica に教える必要があります。
驚くことに, シナリオファイルの記述は JUnit のテストコードの記述と同じくらいかんたんです。

詳しくは以下のドキュメントを参照してください：

ヒント

新規機能を追加する際には, その機能を実装する前にシナリオファイルを作成し, それに沿って実装を進めるとよいでしょう。
プラグインにおけるテスト駆動開発の始まりです。

テストの実行​

テストの実行は, そのプラグインのシナリオを実行するだけで, 自動的に行われます。 シナリオの実行結果はそのままテスト結果にエスカレーションされます。

テスト（シナリオ）を手動で実行するには, /scenamatica scenario startコマンドを実行します。

宣伝

CI/CD パイプラインと連携すると, テストサーバの用意からテストの実行, そして結果のレポートまで全て自動で行えます。

詳しくは以下のドキュメントを参照してください：

Scenamatica が対応するバージョン​

Scenamatica は, 以下の PaperMC サーバ・バージョンで動作します。以下に記載していないバージョンでは絶対に動作しません：

  • 1.13.2
  • 1.14.x
  • 1.15.x
  • 1.16.x
  • 1.17.x

しかしながら, これら以上のバージョン向けのプラグインをテストしたい場合もあるかもしれません。
ところで Bukkit はかなり高い後方互換性を持っているため, これらのバージョンで動作するプラグインは, 別のバージョンで動作する可能性が高いです。
したがって, より高いバージョンのプラグインをテストする場合は, ターゲットのバージョンに最も近い 他の PaperMC サーバを用いてテストを行うことをお勧めします。

例えば 1.18.x のプラグインをテストしたい場合は, 1.17.x の PaperMC サーバを用いることで（大抵の場合は）問題なくテストできるでしょう。

条件付き実行​

シナリオに実行条件を指定することで, テストの実行に条件を持たせられます。
特別な条件とは例えば, あらかじめ定義したフラグ（マイルストーン）が建っているかどうか, といったものです。

条件が満たされない場合は, テストは実行されずにスキップされる（条件 SKIPPED で終了する）ため, テストの実行に失敗したとはみなされません。

自動再試行​

この機能を使用することで, 失敗したテスト（シナリオ）を自動で再試行できます。

この機能が有効な状態でシナリオの実行に失敗すると, キューの末尾にシナリオを追加して再実行を試みます。 この動作はコンフィグに設定された最大試行回数まで繰り返されます。

また, 再試行時は初回実行時のトリガと同じ種類かつ同じ値が使われます。
初回実行で一度失敗し, かつ再試行時に成功したシナリオは 不安定なシナリオ としてマークされ, flakes としてレポートされます。

ヒント

テストのサマリには, この機能によって追加されたシナリオも含まれます。
また, 失敗したシナリオの一覧表示出力では, 同名（再試行された）シナリオはまとめられて出力されます。

テストの結果​

Scenamatica によるテストを実行すると, 以下のような結果が得られます。

テスト結果

これは, テストの実行結果の種別と, 詳細ないくつかの情報を含めたものです。 種別は以下の列挙型の値を取ります。

テストに成功する結果​

  • PASSED
    全てのテスト項目を正常に通過し, シナリオが正常に終了したことを示します。

テストに失敗する結果​

  • CONTEXT_PREPARATION_FAILED
    シナリオの実行に必要なコンテキストの準備に失敗したことを示します。
    これはサーバの状態や Scenamatica の問題であるため, 時間をおいて再実行することで解決する可能性があります。

  • ACTION_EXECUTION_FAILED
    アクションの実行が, エラーの発生やその他予期しない事由によって失敗したことを示します。

  • ACTION_EXPECTATION_JUMPED
    実行を期待すしていたクションよりも先に, 他のアクションが実行されたことを示します。
    これについての詳細はこちらを参照してください。

  • SCENARIO_TIMED_OUT
    実行を期待するアクションやシナリオが, 所定の時間内に実行されなかったことを示します。

  • ILLEGAL_CONDITION
    条件要求タイプのシナリオなどで指定された条件と実際の状態が異なることを示します。

  • UNRESOLVED_REFERENCE 変数・定数の定義と参照機能によって参照された変数や定数が解決できなかったことを示します。

  • RUN_TIMED_OUT
    シナリオ（ファイル）全体の実行が（所定の時間内に）終了しなかったことを示します。

  • INTERNAL_ERROR
    内部エラーが発生したことを示します。

テストが中断する結果​

この結果は, テストの実行がユーザまたはシステムなどの外的要因よって中断されたことを示します。
テストの実行に失敗したとはみなされません。

  • CANCELLED
    シナリオの実行がキャンセルされたことを示します。
  • SKIPPED
    シナリオの実行が何らかの要因によってスキップされたことを示します。
SCENARIO_TIMED_OUT と RUN_TIMED_OUT の違いについて

RUN_TIMED_OUT は, シナリオファイルを構成するアクション全ての実行が所定の時間内に終了しなかったことを示すのに対し,
SCENARIO_TIMED_OUT は, その中の個々のシナリオが, それぞれに指定された所定の時間内に終了しなかったことを示します。