CWL の準拠度テストについて (v1.2 対応版)
この記事は CWL Advent Calendar 2020 の7日目の記事です[1]。
2018年に書かれた記事を、CWL の最新規格 (v1.2) に合わせて更新したものになります。
はじめに
CWL では仕様が公開されているため、自分で CWL 準拠のワークフローエンジン(e.g.,「僕の考えた最強のワークフローエンジン」)を作成することも可能です。
また Github のリポジトリで準拠度を計るためのテスト集 (以下では conformance tests と呼びます) も公開されているため、自作したエンジンの準拠度を調べることも可能です。
この記事ではワークフローエンジンの準拠度を確認できる conformance tests の実行方法を解説します。
注意！
この記事は CWL に対応したワークフローエンジンを実装する人向けの記事です！
CWL を書いて利用する一般の方は、お茶でも飲みながら軽い気持ちで読んでいただければ幸いです。
Conformance tests の実行方法
事前準備
$ git clone --depth=1 https://github.com/common-workflow-language/cwl-v1.2.git
$ cd cwl-v1.2
$ pip install cwltest # テスト実行コマンドをインストール
$ pip install cwl-runner # cwl-runner の準拠度を調べる場合
どう使うの
困ったときは --help で使用方法が出てきます(-h では出てこないので注意)。
$ ./run_test.sh --help
run_test.sh: Run common workflow tool description language conformance tests.
Syntax:
...
とにかく全部テストしたい
$ ./run_test.sh
デフォルトでは cwl-runner (通常はリファレンス実装である cwltool) を用いて conformance_tests.yaml に書かれたテストを実行します。
出力は以下の形式になります。
$ ./run_test.sh
...
153 tests passed, 13 failures, 29 unsupported features
1 tool tests failed
この例は、195個のテスト中153個はパス、13個は失敗、29個のテストは処理系が未サポートの機能を含むためスキップされた[2]ことを示しています。
特定のテストだけ実行したい
$ ./run_test.sh -n=1
この例では一番最初のテストのみ実行します。-n には 1-3 や 2,4,6 などの記法で、複数のテスト項目を指定することもできます。
また以下のように --tags オプションを用いることで、指定したタグが tags フィールドに含まれているテストのみを実行することができます。
# 実装が必須 (`required`) か、InlineJavascriptRequirement (`inline_javascript`) が用いられているテストのみ実行
$ ./run_test.sh --tags=required,inline_javascript
conformance_tests.yaml のテスト項目の読み方については過去記事を参照してください。
自作のワークフローエンジンのテストをしたい
$ ./run_test.sh RUNNER=/path/to/your-own-engine
RUNNER 変数で指定したワークフローエンジンの準拠度テストを行います。run_test.sh は RUNNER に --quiet オプションと入力の CWL ファイル、パラメータが書かれた YAML (or JSON) ファイルを与えて実行します。自作のワークフローエンジンを run_test.sh で実行させるのに必要なその他のオプションについては、公式で提供しているエンジンのツール定義を参照してください。
テストの実行が遅い
$ ./run_test.sh -j=32
-j オプションを使うことで複数のテストを同時に実行できます。しかし各テストのエラー表示等も同時に出力されてしまうため、標準出力で確認する場合には使いにくいです。--junit-xml=foobar.xml を使うことで JUnit 形式の出力を foorbar.xml に出力してくれるため、こちらと併用するのが良さそうです。
テスト結果のサマリーをユーザーに見せたい
$ ./run_test.sh --badgedir=badges
--badgedir=DIR を指定することで、DIR ディレクトリにバッジ生成用のファイル群が生成されます。これをどこかのサーバー(Github のリポジトリなど)に保存して Markdown に貼り付けることで、例えば ep3 のように、README.md や各リリースページから準拠度を確認することができるようになります。
バッジ生成用の JSON ファイルは、テスト項目の tags フィールドに記載されているタグごとに出力されます。生成したバッジの貼り方については過去記事を参照してください。
参考リンク
- 公式サイトでの Conformance tests に関する説明
-
cwltest
-
run_test.shが内部で使用している CWL のテスト用フレームワーク
-
Discussion