Markdownでテスト仕様書を書けるGaugeを試してみる

E2EテストやATDDについて調べていたら、 Markdown でテスト仕様書を書ける Gauge を知り、ちょっと試してみたのでメモ。

• 環境
• Gauge とは
• インストール
• 使い方
  • プロジェクトの作成
    • Specification の実行
    • テスト結果の確認
  • Specification の記述
    • 見出しとシナリオ
    • データテーブル
    • ステップ
    • タグ
    • コンテキストステップ
    • ティアーダウンステップ
    • コメント
    • コンセプト
  • Taiko でのテストコード実装
    • ステップとの紐づけ
• 実装例
• 振り返り

環境

Gauge v1.1.5。テストは Node.js v14.15.0 で記述。

Gauge とは

インテグレーションテスト用の仕様 (Specification) を Markdown で記述し、それに紐づけたテストを実行して結果などを管理するフレームワーク。

テスト仕様書を Markdown で記述することで、読み取りが容易となり、再利用性を高められ、また実装を切り分けられる。

テストの実装は、開発元が同じ Taiko や Selenium 、またツールを使わずスクレイピングしたりと任意。言語も複数選択可能。

インストール

公式のインストールページを参照。

Windows の場合、Chocolatey でもインストールできるが、バージョンが古いため、公式の手順でインストールを推奨。

2020/11/15 時点で、Chocolatey でインストールできる Gauge は v1.1.1 だが、リリース済みバージョンは v1.1.5。v1.1.1 では、 VSCode からプロジェクトを作成しようとするとエラーが発生する。 ( gauge template が実行されるが、 v1.1.1 時点で template コマンドが未実装)

エディタやIDEとの連携用のプラグインがあるが、公式のインストールページでは、Visual Studio Code しか選択できない。 Intellij IDEA 用のプラグインはあるが、Eclipse 用のプラグインはサードパーティ製のものしかない模様。

• Visual Studio Code: https://marketplace.visualstudio.com/items?itemName=getgauge.gauge
• Intellij: https://plugins.jetbrains.com/plugin/7535-gauge
• Eclipse: https://github.com/getgauge-contrib/Gauge-Eclipse
  • 2015 年で止まっている

使い方

前述のインストールページで指定した OS, Language, IDE/Editor で、それ以降の説明が変わる模様。

プロジェクトの作成

https://docs.gauge.org/getting_started/create-test-project.html

VSCode からテスト用のプロジェクトを作成。

コマンドパレットに create project を入力し、 Gauge: Create a new Gauge Project を選択。

コマンド gauge template --list --machine-readable を実行し、言語と説明、テンプレートの ZIP ファイルの URL を JSON で取得していた。

v1.1.5 の時点で、言語およびプロジェクト管理ツールや Selenium との組み合わせで 12 種類。

• .Net Framework (dotnet)
• Java (java, java_gradle, java_maven, java_maven_selenium)
• JavaScript (js, js_simple)
  • js にはブラウザ操作の自動化ツールとして Taiko がバンドルされる
• Python (python, python_selenium)
• Ruby (ruby, ruby_selenium)
• TypeScript (ts)

今回は js を選択。

続いて展開先のディレクトリ選択、最後にプロジェクト名の入力となる。

「展開先ディレクトリ/プロジェクト名」にテンプレート ZIP ファイルが展開され、VSCode の新しいウィンドウで開かれる。

js プロジェクトの場合、ウィンドウが開くまでに npm install が実行されるため、そのまま実行が可能。

Specification の実行

https://docs.gauge.org/getting_started/running-a-specification.html

specs/example.spec を開くと、Markdown 形式のファイルとなっており、最上部に Run Spec | Debug Spec が表示されている。

Run Spec をクリックすると、 npm test が実行され、あらかじめ用意されている spec の実行が可能。

テスト結果の確認

https://docs.gauge.org/getting_started/view-a-report.html

reports/html-report/index.html に、テストレポートが出力される。

Specification の記述

https://docs.gauge.org/writing-specifications.html

Markdown でテスト仕様書を記述できる。

ファイル拡張子は .spec が仕様、 .cpt がコンセプトとなり、 specs/ ディレクトリ配下に保存する。

保存先ディレクトリは env/default/default.properties で変更可能。詳しくはこちら。

見出しとシナリオ

h1 タグで仕様の見出しを、h2 タグでシナリオ名を記述。シナリオ配下に、ワークフローを記述していく。

データテーブル

見出しと最初のシナリオの間に、テーブルを記述すると、データテーブルとして扱える。

後述のステップで <テーブルヘッダ名> を記述すると、そのヘッダ名の列の値を動的パラメータとして扱える。

また、シナリオ単位でテーブルを記述してパラメーター化テストを行うこともできるが、実験的機能の模様。

ステップ

順序なしリストをシナリオ配下に記述すると、それぞれがステップとなる。ただ、VSCode 上では * しかステップとして判断されず、 -|+ ではエラーとなる模様。

ステップに " 2 つ、または < と > で囲んだ文字列を記述すると、実装コードに引数として渡される。

このため、 " , < , > を単純なテキストとしては記述できない。

" 2 つで囲まれた文字列は静的パラメータとなり、そのまま実装コードに渡される。

< と > で前述のデータテーブルのヘッダ名を囲むと動的パラメータとなり、データテーブルから値を取得して実装コードに渡される。

タグ

見出しやシナリオには、 Tags: タグ名[, タグ名] でタグ付けが可能。

記述例では、見出しには Tags: search, admin としてそのテストの分類や対象を、シナリオには成功を期待するテストに Tags: successful がつけられていた。

見出しに付けられたタグは仕様自体のタグとなり、その仕様に含まれるシナリオ全てにも付与される。

コンテキストステップ

見出しと最初のシナリオの間に、ステップを記述すると、コンテキストステップとなる。

各シナリオの実行前にコンテキストステップが実行される。

ティアーダウンステップ

最後のシナリオの後にアンダースコア 3 つ、 ___ で区切り、その後に記述したステップはティアーダウンステップとなる。

各シナリオの実行前にティアーダウンステップが実行される。

コメント

単純なテキストなど、前述の記述以外はすべてコメントとなる。

コンセプト

再利用可能な記述を拡張子 .cpt のファイルに記述可能。

h1 タグでコンセプトヘッダを記述する、そこに <パラメータ名> を含めることが可能。

その直下に順序なしリストでコンセプトステップを記述することで、仕様からコンセプトヘッダを呼び出すことが可能となる。

Taiko でのテストコード実装

• document
• API Reference
• テストランナーとの統合

Taiko は REPL (Read-Eval-Print Loop) で対話形式に実行可能。ブラウザには Google Chrome が使われる。

yarn global add taiko でインストールし、 taiko でインタラクティブレコーダーを実行。

.api でAPI一覧を表示。

コマンドを実行後、 .code [ファイルパス] で実行コマンドを出力 (ファイルパス未指定ではコンソール出力)。

また、 .step で Gauge のステップとして実行可能なコードを出力できる。

.exit で終了。

ツールとしては、スマートセレクター、動的コンテンツのロード待ち、 interceptによるスタブ化・モック化などの特徴がある。

コマンドプロンプトで実行した場合、タブでのコード補完が効いたり、なかなか使い勝手はいいが、いかんせん情報が少ないのが難点か。

ステップとの紐づけ

js テンプレートの場合、 step('ステップに記述したテキスト', async <function>); を記述すると、ステップから実行できる。

VSCode上で、Specification のステップに対応するテストがない場合はエラーとなったり、テストの step が何か所から実行されるかが分かるようになっている。

パラメータを使用している場合、該当部分を < と > で囲み、関数の引数にできる。

実装例

以下の Markdown を spec/search.spec に保存。

# 検索エンジンを開く

Tags: example, search

検索エンジンを開く

   |url                    |
   |-----------------------|
   |https://www.google.com/|
   |https://www.bing.com/  |
   |https://yahoo.com/     |

## 検索エンジンを開く

本当は、タイトルの確認くらいはしたかったが、Taikoでタイトルを取得する方法がわからなかったため、ページを開くだけにする

* URL <url> を開く

続いて、 tests/search.js にテストを保存して実行...したら、ブラウザ起動に失敗するようになった。

ファイル名にルールがあるのか、1ファイルしか書けないのか、原因がわからなかったため、デフォルトで用意されている tests/step_implementation.js に以下を追記。

step('URL <url> を開く', async (url) => {
  await goto(url);
});

この状態で、 gauge run specs や npm test を実行すると、テストが実行された。

振り返り

Gauge 自体は非常に使いやすい印象。開発前のユースケースの段階で、自然言語でテスト仕様を記述できる。

一方、 Taiko は情報が少なく、公式のドキュメントを読むしかない状態で、使いこなせれば高機能だと思うが、簡単なテストを書きたいレベルでは、やや扱いにくかった。複数ファイルを tests/ に配置してエラーになったのも、書き方が悪いのか設定で回避できるのか、はたまた仕様かの判断がつけられなかったが、仮に tests/step_implementation.js しか書けないのであれば、ちょっとテストファイルが肥大化しそう。(「テストランナーとの統合」を見ると、ファイル固定っぽい気がする)

既存のテストコードとしては、Selenium を使った Python や Javaのコードが多いので、他言語でのテストプロジェクト作成を試してみたい。

Selenide のような Page Object Pattern との相性は良さそうな気がする。