Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
206 lines (140 sloc) 10.3 KB

Japanese in UTF-8

ttap: ファイルシステム階層によるテスティングフレームワーク

ttap はテストスクリプト群のディレクトリ構成のフレームワークです. 実行可能なテストスクリプトファイル群のディレクトリ構成を定義し, ファイルシステム階層を元にテストスクリプト群を実行します.

使用法

テストの実行

以下のようなテストスクリプト群があったとします. 以降, ttap で実行されるテストスクリプト群のことをテストスイートと呼びます.

test-simple
├── test_not_ok.sh
└── test_ok.sh

テストスイートのルートディレクトリを指定して ttap コマンドを実行すると, テストスイートが実行されます. ttap コマンドは, すべてのスクリプトの実行に成功した場合にはステータスコード 0 で終了し, 失敗したスクリプトがあった場合にはステータスコード 1 で終了します.

テストの結果はコンソールに出力されます.

$ ttap sample/test-simple
✗ test_not_ok.sh
✓ test_ok.sh

cases            : 2
succeeded        : 1
failed           : 1
time taken [sec] : 0

FAILURE

- test_not_ok.sh

--format tap オプションを指定すると, TAP (Test Anything Protocol) フォーマットで結果を出力します.

$ ttap sample/test-simple --format tap
not ok 1 test_not_ok.sh
ok 2 test_ok.sh
1..2

xUnit 風の出力も --format xunit オプションから利用できます。

$ ttap sample/test-simple --format xunit
F.

Failures:
 - test_not_ok.sh

2 cases, 1 failures

テストの結果は, -o オプションで指定されたディレクトリにも出力されます. result.txt は TAP フォーマットのテスト結果です. *.out はそれぞれのスクリプトの標準出力および標準エラー出力です.

$ ttap sample/test-simple -format silent -o result
$ ls result
result.txt  test_not_ok.sh.out  test_ok.sh.out

テストスクリプトの書き方

テストスクリプトには, どのプログラミング言語も利用可能です. それぞれのスクリプトは以下の条件を満たす必要があります.

テストスクリプトのファイルは Unix 上で実行できる必要があります. すなわち, 読み込みと実行のパーミッションが付与されていなければなりません. パーミッションを持たないスクリプトはスキップされます. また, Shebang(#! で始まるヘッダ)を忘れないでください.

テストスクリプトはテストが失敗した場合には非ゼロのステータスコードで終了しなければなりません. ttap はそれぞれのテストが成功・失敗をステータスコードから判断します.

テストスクリプトは, それぞれのスクリプトが存在するディレクトリをワーキングディレクトリとした状態で実行されることに注意してください. ttap はスクリプト実行時にワーキングディレクトリを変更します. もしワーキングディレクトリを変更されたくない場合は, --no-change-dir オプションを指定してください.

テストスクリプトの実行時には以下の環境変数が設定されており, スクリプトから利用できます.

  • TTAP_EXEC_DIR 変数には, ttap コマンドが実行されたワーキングディレクトリが含まれます.
  • TTAP_ROOT_DIR 変数には, ttap コマンドに指定されたテストスイートのルートディレクトリが含まれます.
  • TTAP_OUTPUT_DIR 変数には, ttap コマンドに -o オプションで指定されたテスト結果が出力されるディレクトリが含まれます.

テストスクリプトの出力を TAP (Test Anything Protocol) フォーマットとすると, 1つのファイルに複数のテストを記述できます. 例えば, Bats が利用できます. ファイル名の末尾が .bats.t であるスクリプトは TAP フォーマットでテスト結果を出力することが期待されます. これらの拡張子は --tap-regex オプションで変更することができます.

ディレクトリ構成

テストスイートが満たすべき命名規約およびディレクトリ構成を示します.

テストスイートに含まれるファイルおよびディレクトリはノードと呼ばれます. 6種のノードが定義されています:

  • Test ノード,
  • Run ノード,
  • Before ノード,
  • After ノード,
  • Init ノード,
  • Final ノード.

ノードの種別はファイル名で判別されます. 各ノード種別のファイルはそれぞれ, test, run, before, after, init, finalで始まります. これらは次のオプションで変更できます:--test-regex, --run-regex, --before-regex, --after-regex, --init-regex, --final-regex.

ノードがディレクトリであった場合には, 配下に子ノードを持つことができます. ディレクトリのノードが実行された時には, 再帰的に子ノードが実行されます.

次にそれぞれのノードについて説明します.

Test ノード

Test ノードとなっているスクリプトにテストされるべき操作が記述されます.

同じディレクトリ配下の Test ノードは順序を持ちません. 各 Test ノードは独立しているべきです. 「テストスイートの品質向上のために」の節を参照してください.

Run ノード

Run ノードは他のノードの子ノードとして利用されます. Before, After, Init, Final ノードは配下に Run ノード以外のノードを持つことはできません. また、同一ディレクトリ内に Run ノードと他のノード種別を含むことはできません.

Test ノードと異なり, 同一ディレクトリ内の Run ノードには順序があります. Run ノードは昇順に実行されます.

Before / After ノード

Before ノード・After ノードはそれぞれ, 各 Test ノードの前処理, 後処理を行います. JUnit4 の @Before@After アノテーションが付与されたメソッドのように, 各 Test ノードが実行される前後に実行されます.

前処理は昇順, 後処理は降順で実行されます.

以下は実行例です.

$ ttap --tree sample/test-before-after
test-before-after
├── before1.sh
├── before2.sh
├── test1.sh
├── test2.sh
├── after2.sh
└── after1.sh
$ ttap --format tap sample/test-before-after
ok 1 before1.sh.1
ok 2 before2.sh.1
ok 3 test1.sh
ok 4 after2.sh.1
ok 5 after1.sh.1
ok 6 before1.sh.2
ok 7 before2.sh.2
ok 8 test2.sh
ok 9 after2.sh.2
ok 10 after1.sh.2
1..10

なお, 前処理が失敗した場合には, テストはスキップされます.

Init / Final ノード

Init ノード・Final ノードは同一ディレクトリ内のすべてのテストが実行される前後に一度だけ実行されます. JUnit4 での @BeforeClass@AfterClass アノテーションに相当します.

Before ノード・After ノードと同様に, Init ノードは昇順, Final ノードは降順に実行されます.

以下は実行例です.

$ ttap --tree sample/test-init-final
test-init-final
├── init1.sh
├── init2.sh
├── test1.sh
├── test2.sh
├── final2.sh
└── final1.sh
$ ttap --format tap sample/test-init-final
ok 1 init1.sh
ok 2 init2.sh
ok 3 test1.sh
ok 4 test2.sh
ok 5 final2.sh
ok 6 final1.sh
1..6

テストスイートのテスト

テストスイートのテストのために ttap では以下のコマンドラインオプションが利用できます.

  • --tree オプションが付与されると, テストスイートのファイルシステム階層がコンソールに出力されます.
  • --print-log オプションが付与されると, 実行中のスクリプトの出力がコンソールに出力されます.
  • --stop-on-failure オプションが付与されると, ひとつの操作が失敗したときに残りの操作の実行はすべてスキップされます. この際, 後処理もスキップされます.
  • --skip-all オプションが付与されると, すべての操作はスキップされます. このオプションはスクリプトの実行計画の確認に利用します.
  • --skip オプションにスクリプト名が指定されると, 指定されたスクリプトはスキップされます. ディレクトリを指定することも可能です.
  • --only オプションにスクリプト名が指定されると, 指定されたスクリプトのみが実行されます. ディレクトリを指定することも可能です. ただし, 前処理・後処理の操作は自動的に実行されないことに注意してください.

テストスイートの品質向上のために

各テストは独立であるべきです. テストの独立性を向上させるため, ttap コマンドは --randomize オプションが付与されたときには, テストの実行順序をランダムにします. 同じディレクトリ配下のテストの順序がランダムに交換されます. 乱数のシードは, 実行時に出力されるサマリーに表示されます. 再現性のため, --randomize オプションに乱数のシードを指定することもできます.

テストの前処理は冪当であるべきです. 前処理のためのスクリプトの冪等性を守るために, ttap コマンドは --multiply-preconditioning オプションが指定されると, 前処理の操作を連続して2回実行します. なお, 後処理は冪当である必要はないことに注意してください. 後処理は前処理が行われていることを期待して実行されるべきです.

インストール

ttap のリポジトリをチェックアウトして、ttap の bin ディレクトリを PATH 環境変数に加えて下さい。

必要環境

  • Linux or UNIX
  • Python 2.7 or 3.x

ライセンス

このソフトウェアは MIT ライセンスの下に公開されています. 詳細は LICENSE を参照してください.