#! /usr/bin/env atf-sh

atf_test_case tc1 
tc1_head() { 
    ... first test case's header ... 
} 
tc1_body() { 
    ... first test case's body ... 
} 
 
atf_test_case tc2 cleanup 
tc2_head() { 
    ... second test case's header ... 
} 
tc2_body() { 
    ... second test case's body ... 
} 
tc2_cleanup() { 
    ... second test case's cleanup ... 
} 
 
... additional test cases ... 
 
atf_init_test_cases() { 
    atf_add_test_case tc1 
    atf_add_test_case tc2 
    ... add additional test cases ... 
}

テストケースの定義

テストケースには、識別子があり、3 つの異なる部分からなります: ヘッダ、本体とオプションのクリーンアップルーチンで、それらのすべては、 atf-test-case(4) に記述されています。テストケースを定義するため、テストケースの名前を指定する最初のパラメータを取り、有効なテストケースとして、それを受け付けるめにセットアップするようにライブラリに指示する atf_test_case() 関数を使用することができます。 2 番目のパラメータは、オプションで、提供されるなら、‘cleanup’でなければなりません。このパラメータを提供することによって、テストケースのためのクリーンアップルーチンを定義することができます。プログラムが実行されるとき、この関数が実行のためにテストケースをセットアップ しない ことに注意することは重要です。そのために、後の登録は、 プログラムの初期化 に記述された atf_add_test_case() 関数によって必要とされます。

後で、2 つまたは 3 つの関数 (クリーンアップルーチンがオプションであることを思い出してください) を提供することによって、3 つの本体の部分を定義しなければなりません。これらの関数は、 <id>_head(), <id>_body() と <id>_cleanup() である、テストケースの識別子にちなんで名前が付けられます。これらは、実行されたとき、何もパラメータを取りません。

プログラムの初期化

テストプログラムは、単一のパラメータとしてテストケースの名前を取る、 atf_add_test_case() 関数を使用することによって実行時に実行されるテストケースを登録することを任されている、 atf_init_test_cases() 関数を定義しなければなりません。この main 関数は、たぶん特別の変数と関数を定義する補助ソースファイルを取り込むことを除いて、ほかに何もするべきではありません。

設定変数

テストケースは、 atf_config_has() と atf_config_get() メソッドによって現在の設定変数への読み込み専用のアクセスがあります。前者は、変数名を指定する単一のパラメータを取り、変数が定義されているかどうかを示すブール値を返します。後者は、1 つまたは 2 つのパラメータを取ることができます。 1 つだけを取るなら、値を得る変数を指定し、この変数は、定義されなければなりません。 2 つ取るなら、2 番目のものは、変数が利用可能でないなら、返されるデフォルト値を指定します。

ソースディレクトリへのアクセス

atf_get_srcdir() 関数を使用することによってテストプログラムのいかなる場所からもテストケースのソースディレクトリへのパスを取得することは可能です。静かにソースディレクトリからの追加のヘルパファイルを含めるために atf_init_test_cases() の内部で、これを使用することができることに注意することは興味深いことです。

要求プログラム

ヘッダのみで利用可能な require.progs メタデータ変数に加えて、また、基本となる名前か、または単一のバイナリのフルパスを取る、 atf_require_prog() 関数を使用することによって、テストケースの本体の追加のプログラムをチェックすることができます。相対的なパスは、禁止されています。それが見つからないなら、テストケースは、自動的にスキップされます。

テストケースの終了

テストケースは、本体がその終了に到着するとき、テストが passed を持っていると仮定されるポイントで、または atf_pass(), atf_fail() または atf_skip() へのあらゆる明示的な呼び出しで、どちらかを終了させます。これらの 3 つの関数は、テストケースの実行を直ちに終了します。クリーンアップルーチンは、テストケースの終了の理由にかかわらず、その後、完全に自動的な方法で処理されます。

atf_pass() は、あらゆるパラメータを取りません。 atf_fail() と atf_skip() は、それぞれ、なぜテストケースが失敗したか、または、スキップされたか説明する単一の文字列パラメータを取ります。ユーザは、なぜテストが合格しなかったのか素早く知ることができるように、両方の場合で明瞭なエラーメッセージを提供することは非常に重要です。

期待値

前のセクションで説明されたものはすべて、テストケースの期待値がプログラマによって再定義されるとき、変更します。

各テストケースは、いずれかの時点でテストケースの期待値が何かを記述する‘expect’と呼ばれる内部状態があります。この特性の値は、次のうちのいずれかによって実行の間に変更されるかもしれません:

atf_expect_death( reason, ...)

終了時の性質にかかわらず時期尚早に終了するとテストケースを予想します。

atf_expect_exit( exitcode, reason, ...)

テストケースがきれいに終了すると予想します。 exitcode が‘-1’でないなら、 atf-run(1) は、テストケースの終了コードが、この呼び出しで提供されるものと一致することを確認します。そうでなければ、正確な値は、無視されます。

atf_expect_fail( reason)

このモードで上げられたあらゆる失敗も記録されますが、そのような失敗は、失敗されたテストケースを報告しません。代わりに、テストケースは、きれいに終了し、‘expected failure’ (予期された失敗) として報告されます。この報告は、その一部として提供される reason (理由) を含んでいます。エラーがこのモードで実行している間に上げられないなら、テストケースは、‘failed’ (失敗) として報告されます。

このモードは、テストでの実際の既知のバグを再現するために役に立ちます。開発者がバグを後で修正するときはいつでも、テストケースを新しい条件に調節しなければならないことを開発者に伝え、テストケースは、失敗を報告し始めます。この状況で、それは、例えば、目的の追跡のためにバグ番号として reason (理由) を設定するために、役に立ちます。

atf_expect_pass()

これは、実行の通常のモードです。このモードで、あらゆる失敗は、ユーザにそういうものとして報告され、テストケースは、‘failed’ (失敗した) とマークされます。

atf_expect_signal( signo, reason, ...)

シグナルの受け付けのために終了するとテストケースを予想します。 signo が‘-1’でないなら、 atf-run(1) は、テストケースを終了したシグナルが、この呼び出しで提供されるものと一致することを確認します。そうでなければ、正確な値は、無視されます。

atf_expect_timeout( reason, ...)

そのタイムアウトより長く実行するテストケースを期待します。

共通のチェックのためのヘルパ関数

atf_check( [options], command, [args])

この関数は、 atf-check ツールの実行をラップ (wrap) し、ツールが失敗を報告するなら、テストケースを失敗させます。利用者は、常にスクリプト中のツールの代わりにこの関数を使用するべきです。この関数のパラメータにの詳細については、 atf-check(1) を参照してください。

atf_check_equal( expr1, expr2)

この関数は、2 つの式を取り、それらを評価し、それらの結果が異なるなら、適切な失敗のメッセージがあるテストケースをアボートします。