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

最初のシナリオを書いてみる

あなたの最初のシナリオを書いてみましょう。

注意事項​

この項目では, 最も基本的なシナリオファイルを書く方法について説明します。
ここにない高度な機能についての説明や, その他の完全な構文についてはこちらを参照してください。

ステップ０. シナリオの概念について理解する​

Scenamatica は, シナリオと呼ばれるファイルを使用して, プラグインの動作をテストします。

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

ステップ１. ファイルを作成する​

まずは, シナリオファイルと呼ばれる YAML ファイルを作成します。
ファイルの拡張子は .yml もしくは .yaml です。これは, 一つのシナリオごとに一つ作成する必要があります。
場所に関しては, プラグインの最終的な .jar ファイルに配置されるのであればどこでも構いません。

この例では, test-hoge-success.yml というファイル名を使用します。

ファイル名のフォーマット​

ファイル名は, 特に技術的な制約等はありませんが, Scenamatica では, 以下のフォーマットを推奨しています。

  • ASCII の小文字のみ
  • ケバブケース（単語をハイフンでつなぐ）
  • 推奨フォーマット： test-<機能名>-<success|failure-with-[失敗内容]>.yml
    先頭を test-<機能名> とすることで, 特定の機能のテストであるということが分かりやすくなります。
    また, 正常に成功することを確認するテストの場合は success-<機能名>,
    異常入力等で失敗することを確認するテストの場合は failure-<機能名>-with-<失敗理由> というようにするとよいでしょう。

例： test-hoge-success.yml , test-hoge-failure-with-no-argument.yml

ステップ２. Scenamatica のバージョンを記述する​

シナリオファイルの先頭には, そのシナリオが対応している Scenamatica のバージョンをscenamatica キーを用いて記述します。
これは, シナリオが対応している Scenamatica のバージョンを明確に記述することで, 誤った（互換性のない） Scenamatica で実行することを防ぐことが目的です。

プラグインのデバッグ用のサーバに配置されている Scenamatica と同じバージョンを記述してください。

記述例：

scenamatica: "1.0.0"

ステップ３. 名前と説明を記述する​

シナリオファイルの次に, シナリオの名前と説明を記述します。

名前name は, シナリオの識別子として使用されます。プラグインの中で一意な命名をしてください。
説明description は, 人間が読みやすいような説明文を記述します。

記述例：

test-hoge-success.yml
scenamatica: "1.0.0"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

ステップ４. コンテキストを記述する​

コンテキストは, シナリオを実行するワールド（ステージという）の環境や, シナリオに登場する擬似的なプレイヤ（アクタという）, モブ（エンティティという）などのシナリオテストの実行に必要な前提環境を指定します。 これらはシナリオの実行前に生成され, 終了時に破棄されます。

今回のテストでは, /hoge コマンドの実行者としてアクタ Actor1 が存在することを想定しているので, 以下のように記述します。
また, ネザーで実行するようにもしてみましょう。

test-hoge-success.yml
scenamatica: "0.0.1"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

context:
  actors:
  - name: Actor1
  stage:
    env: NETHER

ステップ５. トリガを記述する​

各シナリオは, 発火されるためのトリガが必要です。
例えば, 「プラグインが有効されたときにシナリオを実行するトリガ」（on_load）などが該当します。

トリガは, onというキーでオブジェクトのリストで記述します。

今回は手動実行のみを想定しているので, 手動実行（manual_dispatch）というトリガを設定します。

test-hoge-success.yml
scenamatica: "0.0.1"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

context:
  actors:
  - name: Actor1
  stage:
    env: NETHER

on:
- type: manual_dispatch
ヒント

今回は上記のトリガのみ実装しましたが, ほかにもいろいろなトリガがあります。

詳しくはこちらを参照してください。

ステップ６. シナリオを記述する​

プラグインの機能と, それらを発火させるために必要な条件とをおおまかに考えて, シナリオ化して記述します。
例として, 今回のプラグインの機能について考えてみましょう。箇条書きにすると以下のようになります：

  • 機能の発火条件：コマンド /hoge が発行される。
  • 機能１：fuga というメッセージが 実行者 に表示される。
  • 機能２：実行者 がキルされる。

Scenamatica では, 上記のような振る舞いや動作を, 「アクション」と定義しています。
たくさん用意されているこれらを, 積み木のように組み合わせてシナリオを記述します。
この例では, それぞれ以下のアクションを使用すると実現できそうです：

また, それぞれのアクションは, 最大で３つの異なる振る舞いを持ちます。 これらは, 同時に記述されるシナリオタイプによって制御されます。 たとえば プレイヤの死亡以下のような振る舞いを持ちます：

シナリオタイプアクション プレイヤの死亡のふるまい
アクション実行(execute)プレイヤをキルする
アクション実行期待(expect)プレイヤがキルされるまで待機する（検知する）
条件要求(require)プレイヤが（もう既に）死亡していることを要求する

これらのシナリオタイプと使用するアクションを組み合わせて, シナリオを記述します。

これらをシナリオ化すると, 以下のようになります。

test-hoge-success.yml
scenamatica: "0.0.1"
name: "test-hoge-success"
description: "hoge 機能の正常系テスト"

context:
  actors:
  - name: Actor1
  stage:
    env: NETHER

on:
- type: manual_dispatch

scenario:
  # Actor1 が /hoge を実行する。
- type: execute
  action: command_dispatch
  with:
    command: "/hoge"
    sender: Actor1
  # fuga というメッセージが（Actor1 に）表示されることを期待する。
- type: expect
  action: message
  with:
    content: "fuga"
    recipient: Actor1
  # Actor1 がキルされることを期待する。
- type: expect
  action: player_death
  with:
    target: Actor1

ステップ７. シナリオを実行する​

シナリオが記述できたら, 実行してみましょう。

今回の例では手動実行のトリガを追加していますから, コマンド /scenamatica run <プラグイン名> test-hoge-success を実行します。

警告

シナリオを手動実行に対応させるためには, on に manual_dispatch が含まれている必要があります。

その他のトリガに関しては, こちらを参照してください。

ステップ８. 糸冬 了​

以上で基本的なチュートリアルは終了です。お疲れ様でした。

他の応用的なチュートリアルを読むにはこちらを参照してください。
シナリオファイルの完全な構文についてはこちらを参照してください。
CI/CD で Scenamatica を使用する方法についてはこちらを参照してください。