テストを別のモジュールに分ける¶

通常のコードと、エクスポートされた関数に対するテストコードを分けたいとします。このような場合には、もしモジュールの名前がmであったとすると、テスト関数をm_tests(m_testではなく複数形)というモジュールの中に書くことができます。EUnitにモジュールmをテストするように指示した場合、m_testsというモジュールを探しにいって、この中に定義されたテストが実行されるようになります。モジュール名に関してはプリミティブというところで詳しく説明します。

EUnitにより標準出力を取得する¶

もしテストコードが標準出力に何かを書き出したとすると、テストが実行されたときにコンソールに何もテキストが表示されないのを見て驚くでしょう。これはEUnitがテスト関数から出力される、すべての標準出力の結果をキャプチャーしているからです。これにはセットアップ、クリーンナップの関数も含まれますが、ジェネレータ関数は含まれません。そして、この結果は、エラーが発生した場合に、テストレポートの中に出力されます。テストの実行中にEUnitを迂回して、テキストを直接コンソールに書き出したい場合には、io:format(user, “~w”, [Term])というユーザ出力ストリームを利用することができます。推奨される方法としては、EUnitのデバッグマクロを使用することで、シンプルに書くことができます。

データとしてテストの表現¶

基本的なテスト表現は、テストは引数のない１つのfun式で表されます。例えば、以下のようなテストジェネレータを作成することができます。

basic_test_() ->
       fun () -> ?assert(1 + 1 =:= 2) end.

このジェネレータは、以下のようなシンプルなテストと同じ結果になります。

simple_test() ->
    ?assert(1 + 1 =:= 2).

実際には、EUnitは内部ではすべてのシンプルなテストをfun式として扱います。これらの式をリストの中に格納して、一つずつ実行します。

テストを書くためのマクロを使用する¶

テストをよりコンパクトで読みやすく書くためには_testマクロ(先頭のアンダースコアを忘れずに)を使用することができます。このマクロは、テストが書かれているソースコード内の行番号の情報を自動的に付加し、タイプ数を節約できます。

basic_test_() ->
    ?_test(?assert(1 + 1 =:= 2)).

_testマクロは引数としてあらゆる式(テスト本体)を受け取り、それを追加の情報とともにfun式の内部に格納した状態で展開されます。本体は、シンプルなテスト内に書くように、テストを表す式なら何でも指定することができます。

テストオブジェクトを作成するアンダースコアが前に付いたマクロ¶

上記の例はもっと短くすることができます。マクロ名の前にアンダースコアがついたassertマクロ群などのほとんどのテストのためのマクロは、自動的に?_test(...)ラッパーを付加します。上記の例はもっとシンプルに以下のように書くことができます。

basic_test_() ->
    ?_assert(1 + 1 =:= 2).

_assertマクロを、assertマクロの代わりに使用することで、まったく同じ文となります。最初にアンダースコアがついたマクロはテストオブジェクトを表す記号として見ても差し支えありません。

_test(Expr)¶

式をテストオブジェクトに変換します。テストオブジェクトはfun式でラップされ、ソースファイルの行番号が付加されます。技術的には、{?LINE, fun () -> (Expr) end}と書くのと同一です。

EUNIT¶

このマクロはコンパイル時にEUnitが有効な時にはいつでも定義されています。このマクロは、以下のようにテストコードを条件コンパイル内に置くときに使用します。

-ifdef(EUNIT).
    % ここにテストコードを書く
    ...
-endif.

例えばテストが無効になっているときには、EUnitヘッダファイルをインクルードしないでコンパイルされることもあります。TEST, NOTESTの項目も参照してください。

EUNIT_NOAUTO¶

このマクロが定義されると、自動的にテスト関数をエクスポートする機能が無効になります。

TEST¶

このマクロは、コンパイル時にEUnitが有効になっている場合にはいつも定義されます。ユーザが自分で別の値を定義した場合を除いて、trueとして定義されます。このマクロはテストコードを条件コンパイルする際に使用することができます。NOTEST, EUNITの項目も参照してください。

EUnitに依存しているテストコードについて条件コンパイルする場合には、EUNITマクロを使用する方が望ましいです。TESTマクロはもっと一般的なテスト条件に使用されます。この場合はTESTマクロの方が望ましいでしょう。

TESTマクロは、TOTESTマクロを上書きすることができます。NOTESTが定義されていたとしても、EUnitヘッダファイルがインクルードされる前にTESTが定義されていれば、EUnitは有効な状態でコンパイルされます。

NOTEST¶

このマクロは、EUnitがコンパイル時に無効になっている場合にはいつも定義されます。ユーザが自分で別の値を定義した場合を除き、trueとして定義されます。TESTマクロと比較してみてください。

このマクロは条件コンパイルにも使用することができますが、一般的にはテストを無効化用途に使用します。EUnitヘッダファイルをインクルードする前にNOTESTが定義されていて、なおかつTESTが定義されていない場合には、EUnitが無効の状態でコンパイルされます。テストの無効化も参照してください。

NOASSERT¶

このマクロは、テストが無効になっていて、assertマクロを使用しても無効になる場合に定義されます。テストが有効な場合には、このマクロは常に自動的に有効になります。無効化することはできません。assertマクロの項も参照してください。

ASSERT¶

もしこのマクロが定義されていると、NOASSERTマクロを上書きします。他の設定によらず、常にassertマクロを有効にすることができます。

NODEBUG¶

もしマクロが定義されていれば、デバッグマクロが動作しなくなります。詳しくはデバッグマクロの説明を見てください。NODEBUGを定義するとテストが定義されていたとしても、NOASSERTが定義されます。

DEBUG¶

もしこのマクロが定義されると、NODEBUGマクロの動作が上書きされます。デバッグ用のマクロを強制的に使用可能にします。

LET(Var,Arg,Expr)¶

ローカルな、Expr内で、Var = Argというローカルな束縛を作成することができます。 (fun(Var)->(Expr)end)(Arg)と定義するのと同じです。この束縛はExprの外にはエクスポートされません。このVarに対する束縛は、使用されるスコープの他の束縛を邪魔することはありません。

IF(Cond,TrueCase,FalseCase)¶

もしCond式がtrueの場合にはTrueCaseが評価されます。そうでない場合はFalseCaseが評価されます。これは (case (Cond) of true->(TrueCase); false->(FalseCase) end).と同等です。Condはブーリアンの値でない場合にはエラーになります。

assert(BoolExpr)¶

テストが有効になっている場合に、BoolExpr式の評価を行います。結果がtrueでなければ、それを知らせる例外が生成されます。例外発生しなかった場合には、マクロ式の評価結果は、okというアトムになります。BoolExprの値は返されません。もしテストが無効な場合には、okアトムを返すコード以外は生成されません。BoolExprも評価されなくなります。

一番使用される方法は以下のようになります。

?assert(f(X, Y) =:= [])

このassertマクロは、ユニットテストの中だけでなく、どこでも使用することができます。以下のように、DbCで行う、事前条件/事後条件/不変条件のチェックにも使用することができます。

some_recursive_function(X, Y, Z) ->
    ?assert(X + Y > Z),
    ...

assertNot(BoolExpr)¶

assert(not (BoolExpr))と同等です。

assertMatch(GuardedPattern, Expr)¶

テストが有効になっている時に、Exprを評価し、結果がGuardedPatternに対して、マッチするかどうか検証します。もしパターンにマッチしなかった場合には、それを知らせる例外を生成します。このあたりの詳細はassertマクロの説明を見てください。GuardedPatternはcase構文の -> シンボルの左側に書くことができるものであれば、なんでも書くことができます。ただし、カンマで区切られたガードテストを含むものを除きます。

シンプルなマッチのテストでも、= ではなくて、assertMatchを使用すると、より詳細なエラーメッセージを生成することができます。

?assertMatch({found, {fred, _}}, lookup(bloggs, Table))
?assertMatch([X|_] when X > 0, binary_to_list(B))
assertEqual(Expect, Expr)

テストが有効な場合に、ExpectとExprの両方の式を評価して、結果が等しいかどうか比較します。もし等しくなかった場合には、情報を伝える例外を生成します。詳しくはassertマクロの説明を見てください。

assertEqualは、左側の期待値がパターンではなくて、計算後の値である場合には、assertMatchよりも良いでしょう。また、?assert(Expect =:= Expr)よりも、詳しい説明が得られます。

?assertEqual("b" ++ "a", lists:reverse("ab"))
?assertEqual(foo(X), bar(Y))
assertException(ClassPattern, TermPattern, Expr)

assertError(TermPattern, Expr)¶

assertExit(TermPattern, Expr)¶

assertThrow(TermPattern, Expr)¶

Exprを評価して、その中で発生した例外をキャッチし、それが期待されたClassPattern, TermPatternと一致しているか検証します。マッチしないか、Exprを評価した中で例外が発生しなかった場合には、情報を伝える例外を生成します。詳しくはassertマクロの説明を参照してください。assertError, assertExit, assertThrowは、ClassPatternとしてerror, exit, throwを設定してassertExceptionを使用した場合と、それぞれ同一です。

?assertError(badarith, X/0)
?assertExit(normal, exit(normal))
?assertException(throw, {not_found,_}, throw({not_found,42}))

assertCmd(CommandString)¶

テストが有効な場合に、CommandStringを外部コマンドとして実行します。もし外部プログラムの返値がゼロでなかった場合には、それを通知する例外が生成されます。例外が発生しなかった場合には、マクロの式の結果は、okアトムになります。もしテストが無効化されている場合には、okアトムを返す以外のコードは生成されず、外部コマンドも実行されます。

?assertCmd("mkdir foo")

assertCmdStatus(N, CommandString)¶

assertCmd(CommandString)マクロと同様ですが、もしステータス値としてN以外の値が返されると例外を生成します。

assertCmdOutput(Text, CommandString)¶

テストが有効な時に、CommandStringを外部コマンドとして実行します。コマンドが出力したものが、指定した文字列のTextと一致しなかった場合には、違いの情報を伝える例外を出力します。どのようなプラットフォームでも、改行コードはLFに正規化されます。もし例外が発生しなかった場合には、このマクロはokアトムを返します。

cmd(CommandString)¶

CommandStringを外部文字列として実行します。返り値が0(成功を意味します)でなかった場合には、情報を伝える例外が生成されます。成功した場合には、このマクロは、コマンドが出力した物をフラットな文字列として返します。どのようなプラットフォームでも、改行コードはLFに正規化されます。

このマクロは、エラーが発生しても、テストをきちんと実行するために、ファイルの作成と削除、OS特有のタスクの実行などを、フィックスチャのセットアップ、片付けのセクションで使用するのが便利です。

UNIX環境で動作するサンプル:

{setup,
 fun () -> ?cmd("mktemp") end,
 fun (FileName) -> ?cmd("rm " ++ FileName) end,
 ...}

1.4.6 デバッグマクロ

EUnitではいくつかのデバッグを補助するマクロを定義しています。これらを使うと、標準出力ではなく、直接コンソールにメッセージをひょうじすることができます。これらのマクロは同じ基本フォーマットを使用して出力されます。これにはデバッグマクロが実行されたファイル名、行番号が含まれ、開発環境(Emacsのバッファ内でErlangを実行している場合など)によっては、出力メッセージから、ソースコードの該当する行に直接ジャンプすることができます。

EUnitヘッダファイルがインクルードされる前にNODEBUGマクロが定義されると、これらのマクロは何もしなくなります。詳しくはコンパイル制御マクロの項目を見てください。

debugHere¶

コンソールに現在のファイルと行番号を表すマーカーを表示するだけのマクロです。このマクロは引数を取りません。結果は常にokとなります。

debugMsg(Text)¶

Textをメッセージとして出力します。Textはプレーンな文字列、IOリスト、アトムが使用可能です。実行結果は常にokとなります。

debugFmt(FmtString, Args)¶

このマクロは、テキストをio:format(FmtString, Args)と同様にテキストをフォーマットして、debugMsgと同じように出力します。結果は常にokとなります。

debugVal(Expr)¶

Exprに対するソースコードと、現在の値の両方を出力します。例えば、?debugVal(f(X))は”f(X) = 42”と表示されます。(ほとんどの単語は切り詰めて表示されます)。評価結果はExprの値となります。そのため、デバッグ機能を有効にしてコンパイルされている時には、このマクロで式(式が使える所はどこでも)をラップして、コードがコンパイルされた時の値を表示するという使い方ができます。

debugTime(Text,Expr)¶

Exprを評価したときの時間とテキストを表示します。評価結果はExprの値となります。そのため、デバッグ機能を有効にしてコンパイルされている時には、このマクロで式(式が使える所はどこでも)をラップして使用することができます。例えば、List1 = ?debugTime(“sorting”, lists:sort(List))を実行すると、”sorting: 0.015 s”と表示されます。

ModuleName::atom()¶

モジュール名を表す単独のアトム。これは{モジュール, モジュール名}と同等です。これはeunit:test(モジュール)という形式でコールされたときに良く使用されます。

{module, ModuleName::atom()}¶

これは与えられた名前のモジュール内の、エクスポートされたテスト関数からなるテストセットで構成されます。これらの関数は、引数がゼロで、名前の末尾が_testもしくは_test_で終わるものになります。..._test()という関数は、シンプルなテストで、..._test_()という関数はジェネレータになります。

これに加えて、EUnitは、ModuleNameというモジュールに_testsという末尾の文字列の追加された別のモジュールも探しに行きます。もし見つかれば、このモジュールに含まれるテストもすべて追加されます。ただし、ModuleNameにすでに_testsという文字が後ろについている場合は探しに行きません。 {module, mymodule}という仕様は、mymoduleと、mymodule_testsというモジュールに含まれる、すべてのテストを実行することになります。通常、_testsモジュールは、メインのモジュールの公開インタフェースに対するテストケースのみを含み、他のコードは含まないようにすべきです。

{application, AppName::atom(), Info::list()}¶

これは、.appファイルの中で見られる、通常のErlang/OTPアプリケーションのディスクプリタになります。結果となるテストセットはInfoに含まれるモジュールの中のエントリーの中のモジュールから構成されます。

{application, AppName::atom()}¶

これは、特定のアプリケーションに含まれるすべてのモジュールにあるテストセットを作成します。アプリケーションの.appファイル({file, FileName}参照)を調査するか、もしくは存在しない場合には、アプリケーションのebinディレクトリ({dir, Path}を参照)に含まれるすべてのオブジェクトファイルを調べます。もしそれでも見つけられない場兄は、code:lib_dir(AppName)ディレクトリが使用されます。

Path::string()¶

ファイルやパスを表す文字列です。これは{file, Path}もしくは{dir, Path}と同等になります。このPathは、それぞれファイルシステムの中で参照されます。

{file, FileName::string()}¶

もし、FileNameの末尾が、オブジェクトファイル(.beam)を表す拡張子がついている場合には、EUnitはそのファイルをリロードして、テストしようとします。そうでない場合には、ファイルを、テスト仕様を含むテキストファイルとみなして、標準ライブラリ関数のfile:path_consult/2を使用して読み込みます。

ファイル名が絶対パスでない場合には、まず現在のディレクトリからの相対パスとして検索します。その後は通常のサーチパス(code:get_path())を利用します。これにより、よく使う”app”ファイル名はパスを指定しなくても直接指定することが可能になります。例えば、”mnesia.app”のように書くことができます。

{dir, Path::string()}¶

これは、指定されたディレクトリの中のすべてのオブジェクトファイルをテストします。{file, FileName}を使用してすべてのファイルを個別に指定するのと同じように動作します。

{generator, GenFun::(() -> Tests)}¶

ジェネレータ関数であるGenFunがコールされ、テストセットが生成されます。

{generator, ModuleName::atom(), FunctionName::atom()}¶

テストセットを生成するのに、ModuleName:FunctionName()が呼ばれます。

{with, X::any(), [AbstractTestFun::((any()) -> any())]}¶

Xの値を、リストに含まれている単体の関数に適用し、それぞれを引数のないテスト関数に変換します。AbstractTestFunは通常のテスト用のfunとほぼ同じですが、引数をゼロ個ではなく、一つだけ受け取ります。パラメータを受け取る前の、正式なテスト関数になる前のテストは、いくつかの情報が足りない状態になります。実際、 {with, X, [F_1, ..., F_N]}は、[fun () -> F_1(X) end, ..., fun () -> F_N(X) end].と同等になります。これは特に、抽象的なテスト関数がすでにきちんとした関数として定義されている場合に便利です。{with, FD, [fun filetest_a/1, fun filetest_b/1, fun filetest_c/1]}は、[fun () -> filetest_a(FD) end, fun () -> filetest_b(FD) end, fun () -> filetest_c(FD) end]と一緒ですが、よりコードが短くなります。フィックスチャの項目もご覧ください。

{spawn, Tests}¶

それぞれのテストをサブプロセスに分けてテストを行います。現在のテストプロセスはそれぞれのテストが終了するのを待ちます。これはプロセスの状態を独立した、新規のプロセスとしてテストを実行するのに役立ちます。EUnitは常に少なくとも一つのサブプロセスを自動でスタートさせます。呼び出しもとのプロセスでテストが実行されることはありません。

{spawn, Node::atom(), Tests}¶

{spawn, Tests}とほぼ同一ですが、テストを、指定されたErlangのノードで実行します。

{timeout, Time::number(), Tests}¶

指定されたタイムアウト時間の中でテストを実行します。Timeは秒で設定します。60を指定すると1分に、0.1を指定すると1/10秒になります。もしタイムアウトすると、終了していないテストは強制的に中断されます。設定されたタイムアウトの時間は、セットアップと片付けも含んだ、フィックスチャ全体の時間になります。もしタイムアウトが起動すると、片付けのコードが実行されないで、突然強制終了されることになります。

{inorder, Tests}¶

指定されたテストを、厳格な順序で実行します。{inparallel, Tests}.も参照してください。デフォルトでは、テストはinorderもinparallelも指定されていません。テストのフレームワークまかせの方法で実行されます。

{inparallel, Tests}¶

可能であれば、指定されたテストを並列で実行します。{inorder, Tests}も参照してください。

{inparallel, N::integer(), Tests}¶

{inparallel, Tests}と同様ですが、平行実行の数をN以下に設定します。