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

シナリオ

シナリオの概念とその概要について説明しています。

概要​

シナリオとは, プラグインのテスト方法を step-by-step で定義したものです。

プラグインの開発者は, テストを実行するための前提環境や, テスト対象機能の発火, およびそれらの検証方法を１つのファイル（シナリオファイルという）に記述します。
Scenamatica は, プラグインに同梱されているシナリオファイルを読み込み, その内容に沿ってプラグインの機能を発火させ, テストの結果を検証・報告します。

「テストを実行するための前提環境」とは, シナリオに登場するエンティティ や模擬的なプレイヤ（アクタ）, そしてテストのためのワールド（ステージ）の３つを指します。 これらは, 同ファイルに定義されるコンテキストによって提供されます。

つまり, 発火条件となるアクションを実行し, それによってもたらされたプラグインの動作を検証し続けることで, シナリオテストが成立します。
Scenamatica はこのようなテストの需要に最適化されているのです。

参考：以下は, シナリオの概要を示す図です（エンティティは省略されています）。

シナリオの概要

例を用いた説明​

例えば, とある小さなプラグインについて考えてみましょう。
このプラグインは, 「プレイヤが村人をキルしたときに」（発火条件という） -> 「ダイアモンドがドロップする機能」（目標動作という）を実現しており, 今回はこの機能をテストしたいこと とします。 このテストは, Scenamatica の以下の機能を用いて達成できます。

  • コンテキスト - エンティティ 機能
    この機能は, テストに必要なエンティティ（e.g. 村人, ガーディアン, 牛 等）をテストの開始前に生成, および終了後に破棄します。
    発火条件で指定される, シナリオの遂行に必要な村人をスポーンさせるために使います。以下はその例です。 
    context:
      entities:
      - type: villager
  • コンテキスト - アクタ 機能
    この機能は, テストに必要な専用のプレイヤ（アクタという）を生成します。
    外部との通信を必要とせずに, サーバ内だけで完結する特別なプレイヤのモックです。
    発火条件にある村人をキルさせるのに使います。以下はその例です。 
    context:
      actors:
      - name: Actor001
  • アクションの実行 機能
    この機能は, テストに必要な一般的な動作（e.g. プレイヤのキル, 食料の消費, プレイヤの退室）を実行します。
    数あるアクションを組み合わせて利用し, プラグイン機能の発火・目標動作の検証を行います。
    動作の検証には, アクションの実行期待 機能を使用します。以下はその例です。 
    scenario:
    - type: execute
      action: player_death
      with:
        target: Actor001
    - type: expect
      action: entity_pickup_item
      with:
        target: Actor001
        item: diamond
備考

このドキュメント内で使用される「シナリオ」という語は, 以下の２つの意味を持ちます。

  1. コンテキスト や トリガー, アクションのフローとしてのシナリオ など, シナリオファイルの内容すべてを一般に指す語。
  2. プラグインの振る舞いを検証するためのアクションとその振る舞いの組。
# このファイル自体をシナリオファイルで記述された「シナリオ」と呼ぶ。

#...

scenario:
# ↓の一つ一つもまた「シナリオ」と呼ぶ。
- type: execute
  action: player_death
  with:
    target: Actor001 
- type: expect
  action: player_death
  with:
    target: Actor001

シナリオの構成要素​

シナリオテストを作成するためには, シナリオがどのような要素で構成されているかを知る必要があります。
シナリオを構成する要素については, 次のページで説明されています：

シナリオファイルの構文​

Scenamatica のシナリオは シナリオファイルと呼ばれる YAML ファイルで記述します。

シナリオファイルの構文については, 以下のページを参照してください。

シナリオの実行の流れ​

Scenamatica によるシナリオの実行の流れについて説明します。

まず, シナリオは記述されたトリガによって開始（発火）されます。
トリガとは, シナリオの実行を開始するための条件のことで, 様々な条件を設定できます。

発火されたシナリオは, 後述のシナリオセッションと呼ばれる単位で管理されます。
同じ事象で, かつ同時に発火されたシナリオが同じセッションに登録されます。 例えば, 同一プラグイン内にトリガ：プラグインのロードを持つ複数のシナリオが存在する場合, それらはプラグインの読み込み時にすべて同一セッションで実行されます。

Scenamatica は, セッション内のシナリオを順次実行し, セッション内のすべてのシナリオが終了するまで待機します。
シナリオの実行が終了すると, その結果が集計され, テスト結果として出力されます。

シナリオセッション​

シナリオセッションは, 複数のシナリオの実行をまとめて管理するための機能です。 １つのセッションは複数のシナリオを管理し, それらはセッション内で順序付けされて実行されます。
シナリオの実行結果（テストの実行結果）はセッションごとに集計され出力されます。

シナリオセッションは実行時に自動で構成されるため, 開発者が意識する必要はありません。

セッションへの登録

シナリオが同じトリガで, かつ同タイミングで発火した場合は, 同じセッションに登録されます。
例えば, シナリオの読み込み後に実行するトリガ (ON_LOAD) を持つシナリオが .jar ファイルに複数存在する場合は, 同じセッションで実行されます。

Session

シナリオの実行の状態​

Scenamatica のシナリオの実行状況は以下の状態に分類されます。
シナリオの実行が異常終了した場合は, 以下の状態一覧を参考にしてエラー原因を特定できます。

  • STAND_BY
    シナリオがコンパイルされ, 実行を待機している状態です。
  • CONTEXT_PREPARING
    シナリオの実行に必要なコンテキストを準備している状態です。
  • STARTING
    シナリオエンジンを初期化し, 起動を待機している状態です。
  • RUNNING_BEFORE（オプション）
    メインシナリオの実行前に実行されるシナリオを実行している状態です。
    トリガによっては実行されることがあります。
  • RUNNING_MAIN
    シナリオの実行を行っている状態です。
  • RUNNING_AFTER（オプション） シナリオの実行後に実行されるシナリオを実行している状態です。
    トリガによっては実行されることがあります。
  • CLEANING_UP
    シナリオの実行後の後処理を行っている状態です。
  • FINISHED
    シナリオの実行が終了した状態です。

Scenamaticaの実行フロー​

Flow

シナリオの実行フロー​

Scenario