CWL の準拠度テストについて (v1.2 対応版)

4 min read読了の目安(約3700字

この記事は 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-32,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.shRUNNER--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 フィールドに記載されているタグごとに出力されます。生成したバッジの貼り方については過去記事を参照してください。

参考リンク

脚注
  1. 6日目の記事として書いてる途中に問題を発見しましたが、PR を送ったらサクッとマージされました。ありがたや ↩︎

  2. 未サポートの機能に対しては 33 をリターンコードとして返すことで、run_test.sh がそれを認識して unsupported features に振り分けてくれます。 ↩︎