extern "C" { 
... C 特有のインクルードは, ここに ... 
} 
 
... C++ 特有のインクルードは, ここに ... 
 
#include <atf-c++.hpp> 
 
ATF_TEST_CASE(tc1); 
ATF_TEST_CASE_HEAD(tc1) 
{ 
    ... 最初のテストケースのヘッダ ... 
} 
ATF_TEST_CASE_BODY(tc1) 
{ 
    ... 最初のテストケースの本体 ... 
} 
 
ATF_TEST_CASE_WITH_CLEANUP(tc2); 
ATF_TEST_CASE_HEAD(tc2) 
{ 
    ... 2 番目のテストケースのヘッダ ... 
} 
ATF_TEST_CASE_BODY(tc2) 
{ 
    ... 2 番目のテストケースの本体 ... 
} 
ATF_TEST_CASE_CLEANUP(tc2) 
{ 
    ... 2 番目のテストケースのクリーンアップ ... 
} 
 
ATF_TEST_CASE(tc3); 
ATF_TEST_CASE_BODY(tc3) 
{ 
    ... 3 番目のテストケースの本体 ... 
} 
 
... 追加のテストケース ... 
 
ATF_INIT_TEST_CASES(tcs) 
{ 
    ATF_ADD_TEST_CASE(tcs, tc1); 
    ATF_ADD_TEST_CASE(tcs, tc2); 
    ATF_ADD_TEST_CASE(tcs, tc3); 
    ... 追加のテストケースを追加する ... 
}

テストケースの定義;

テストケースには、識別子があり、3 つの異なる部分からなります: ヘッダ、本体とオプションのクリーンアップルーチンで、それらのすべては、 atf-test-case(4) に記述されています。テストケースを定義するために、テストケースの名前を指定する単一のパラメータを取る、 ATF_TEST_CASE(), ATF_TEST_CASE_WITH_CLEANUP() または ATF_TEST_CASE_WITHOUT_HEAD() マクロを使用することができます。 ATF_TEST_CASE() は、テストケースのためのヘッダと本体を定義するために必要とされます、 ATF_TEST_CASE_WITH_CLEANUP() は、テストケースのためのヘッダ、本体とクリーンアップを定義するために必要とされます、そして ATF_TEST_CASE_WITHOUT_HEAD() は、テストケースのための本体だけに必要とされます。プログラムが実行されるとき、これらが、実行のためにテストケースをセットアップ しない ことに注意することは重要です。そうするために、後の登録は、 プログラムの初期化 で詳述されている ATF_ADD_TEST_CASE() マクロを通して必要とされます。

後で、3 つの関数の手段によって本体の 3 つの部分を定義しなければなりません。それらのヘッダは、 ATF_TEST_CASE_HEAD(), ATF_TEST_CASE_BODY() と ATF_TEST_CASE_CLEANUP() マクロから与えられ、それらのすべては、テストケースの名前を取ります。これらの各々に続いて、コードのブロックは、開き角括弧と閉じ角括弧に囲まれることが要求されます。

さらに、名前が他のユーザの識別子でクラッシュを防ぐためにライブラリによって内部的に管理されるので、特別のテストケースに対応するクラスの名前を取得するために ATF_TEST_CASE_NAME() マクロを使用することができます。同様に、"used"としてそれをマークするために特別のテストケースで、 ATF_TEST_CASE_USE() マクロを実行することができ、したがって、未使用のシンボルに関するコンパイラの警告を防ぎます。 規則的な操作の間に、これらのマクロを使用する必要べきではないことに 注意してください。

プログラムの初期化

ライブラリは、テストプログラムの main() 関数を容易に定義する方法を提供しています。利用者は、利用者自身で決して定義すべきではありませんが、利用者のためにそれを行うためにライブラリに依存します。これは、テストケースを保持するリストの名前が渡される、 ATF_INIT_TEST_CASES() マクロを使用することによって行われます。この名前は、それが有効な変数値である限り、望むものは何でも指定できます。

マクロの後で、テストプログラムが実行するテストケースを登録するために ATF_ADD_TEST_CASE() マクロを単に使用するべき、関数の本体を提供するが想定されます。このマクロの最初のパラメータは、前の呼び出しで提供された名前と一致します。

ヘッダの定義

テストケースのヘッダは、2 つのパラメータを取る、 set() メソッドを使用することによってメタデータを定義することができます。最初のものは、設定されるメタデータの変数を指定し、2 番目のものは、その値を指定します。それらの両方は、文字列です。

設定変数

テストケースは、テストケースの 3 つの部分のうちのいずれでも呼び出すことができる、 bool has_config_var() と std::string get_config_var() の手段によって現在の設定変数に読み込み専用のアクセスします。

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

‘srcdir’設定変数を問い合わせることによって 3 つの構成要素のうちのいずれかからテストケースのソースディレクトリへのパスを得ることができます。

要求プログラム

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

テストケースの終了

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

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

期待値

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

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

expect_death( reason)

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

expect_exit( exitcode, reason)

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

expect_fail( reason)

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

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

expect_pass()

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

expect_race( reason)

テストケースの実行の間のあらゆる失敗またはタイムアウトは、あたかも競合条件がそういうものとしてトリガされ、報告されたかのように、見なされます。問題が生じないなら、テストは、いつもの通り、実行を継続します。

expect_signal( signo, reason)

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

expect_timeout( reason)

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

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

ライブラリは、複数の状況でとても手軽ないくつかのマクロを提供しています。これらは、与えられた文実行するか、または与えられた式を処理した後に、基本的にいくつかの条件をチェックし、条件が満たされないなら、それらは、自動的に適切なエラーメッセージで ATF_FAIL() を呼び出します。

ATF_REQUIRE() は、式を取り、それが偽と評価するなら、失敗を上げます。

ATF_REQUIRE_EQ() は、2 つの式を取り、2 つが正確に同じ値に評価されないなら、失敗を上げます。

ATF_REQUIRE_IN() は、要素と収集を取り、要素が収集に存在するかを認証します。

ATF_REQUIRE_MATCH() は、正規表現と文字列を取り、正規表現が文字列と一致しないなら、失敗を上げます。

ATF_REQUIRE_NOT_IN() は、要素と収集を取り、要素が収集に存在するかを認証します。

ATF_REQUIRE_THROW() は、例外の名前と文を取り、文が指定された例外をスロー (throw) しないなら、失敗を上げます。 ATF_REQUIRE_THROW_EQ() は、例外の名前、正規表現と文を取り、文が指定された例外をスローしないなら、そして例外のメッセージが正規表現と一致しないなら、失敗を上げます。

ATF_CHECK_ERRNO() と ATF_REQUIRE_ERRNO() は、最初に、チェックが errno 変数で見つけることを予想するエラーコードを取り、 2 番目に、失敗した呼び出しと、評価が真なら、 errno が最初の値とチェックされなければならないことを意味するブール式を取ります。