[译]EUnit——erlang的轻量级单元测试框架(4)

EUnit 宏

Although all the functionality of EUnit is avaliable even without the use of preprocessor macros, the EUnit header file defines a number of such macros in order to make it as easy as possible to write unit tests as compactly as possible and without getting too many details in the way.

Except where explicitly stated, using EUnit macros will never introduce run-time dependencies on the EUnit library code, regardless of whether your code is compiled with testing enabled or disabled.

• Basic macros  基本宏
• Compilation control macros   编译控制宏
• Utility macros   实用宏
• Assert macros    断言宏
• Macros for running external commands    运行额外命令宏
• Debugging macros    调试宏

Basic macros

_test(Expr)

Turns  Expr into a "test object", by wrapping it in a fun-expression and a source line number. Technically, this is the same as  {?LINE, fun () -> (Expr) end}.

Compilation control macros

EUNIT

This macro is always defined to  true whenever EUnit is enabled at compile time. This is typically used to place testing code within conditional compilation, as in:

   -ifdef(EUNIT).

       % test code here

       ...

   -endif.

e.g., to ensure that the code can be compiled without including the EUnit header file, when testing is disabled. See also the macros  TEST and NOTEST.

EUNIT_NOAUTO

If this macro is defined, the automatic exporting or stripping of test functions will be disabled.

TEST

This macro is always defined (to true, unless previously defined by the user to have another value) whenever EUnit is enabled at compile time. This can be used to place testing code within conditional compilation; see also the macros NOTEST and EUNIT.

For testing code that is strictly dependent on EUnit, it may be preferable to use the EUNIT macro for this purpose, while for code that uses more generic testing conventions, using the TEST macro may be preferred.

The  TEST macro can also be used to override the  NOTEST macro. If  TEST is defined  before the EUnit header file is included (even if  NOTEST is also defined), then the code will be compiled with EUnit enabled.

NOTEST

This macro is always defined (to true, unless previously defined by the user to have another value) whenever EUnit is disabled at compile time. (Compare the TEST macro.)

This macro can also be used for conditional compilation, but is more typically used to disable testing: If  NOTEST is defined  before the EUnit header file is included, and  TEST is  not defined, then the code will be compiled with EUnit disabled. See also  Disabling testing.

NOASSERT

If this macro is defined, the assert macros will have no effect, when testing is also disabled. See  Assert macros. When testing is enabled, the assert macros are always enabled automatically and cannot be disabled.

ASSERT

If this macro is defined, it overrides the NOASSERT macro, forcing the assert macros to always be enabled regardless of other settings.

NODEBUG

If this macro is defined, the debugging macros will have no effect. See  Debugging macros.  NODEBUG also implies  NOASSERT, unless testing is enabled.

DEBUG

If this macro is defined, it overrides the NODEBUG macro, forcing the debugging macros to be enabled.

Utility macros

The following macros can make tests more compact and readable:

LET(Var,Arg,Expr)

Creates a local binding  Var = Arg in  Expr. (This is the same as  (fun(Var)->(Expr)end)(Arg).) Note that the binding is not exported outside of  Expr, and that within  Expr, this binding of  Var will shadow any binding of  Var in the surrounding scope.

IF(Cond,TrueCase,FalseCase)

Evaluates  TrueCase if  Cond evaluates to  true, or otherwise evaluates  FalseCase if  Cond evaluates to  false. (This is the same as  (case (Cond) of true->(TrueCase); false->(FalseCase) end).) Note that it is an error if  Cond does not yield a boolean value.

Assert macros

(Note that these macros also have corresponding forms which start with an "_" (underscore) character, as in ?_assert(BoolExpr), that create a "test object" instead of performing the test immediately. This is equivalent to writing ?_test(assert(BoolExpr)), etc.)

If the macro NOASSERT is defined before the EUnit header file is included, these macros have no effect when testing is also disabled; see Compilation control macros for details.

assert(BoolExpr)

Evaluates the expression BoolExpr, if testing is enabled. Unless the result is true, an informative exception will be generated. If there is no exception, the result of the macro expression is the atom ok, and the value of BoolExpr is discarded. If testing is disabled, the macro will not generate any code except the atom ok, and BoolExpr will not be evaluated.

Typical usage:

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

The  assert macro can be used anywhere in a program, not just in unit tests, to check pre/postconditions and invariants. For example:

   some_recursive_function(X, Y, Z) ->

       ?assert(X + Y > Z),

       ...

assertNot(BoolExpr)

Equivalent to  assert(not (BoolExpr)).

assertMatch(GuardedPattern, Expr)

Evaluates Expr and matches the result against GuardedPattern, if testing is enabled. If the match fails, an informative exception will be generated; see the assert macro for further details. GuardedPattern can be anything that you can write on the left hand side of the -> symbol in a case-clause, except that it cannot contain comma-separated guard tests.

The main reason for using assertMatch also for simple matches, instead of matching with =, is that it produces more detailed error messages.

Examples:

   ?assertMatch({found, {fred, _}}, lookup(bloggs, Table))

   ?assertMatch([X|_] when X > 0, binary_to_list(B))

assertEqual(Expect, Expr)

Evaluates the expressions Expect and Expr and compares the results for equality, if testing is enabled. If the values are not equal, an informative exception will be generated; see the assert macro for further details.

assertEqual is more suitable than than assertMatch when the left-hand side is a computed value rather than a simple pattern, and gives more details than ?assert(Expect =:= Expr).

Examples:

   ?assertEqual("b" ++ "a", lists:reverse("ab"))

   ?assertEqual(foo(X), bar(Y))

assertException(ClassPattern, TermPattern, Expr)

assertError(TermPattern, Expr)

assertExit(TermPattern, Expr)

assertThrow(TermPattern, Expr)

Evaluates Expr, catching any exception and testing that it matches the expected ClassPattern:TermPattern. If the match fails, or if no exception is thrown by Expr, an informative exception will be generated; see the assert macro for further details. The assertError, assertExit, and assertThrowmacros, are equivalent to using assertException with a ClassPattern of error, exit, or throw, respectively.

Examples:

   ?assertError(badarith, X/0)

   ?assertExit(normal, exit(normal))

   ?assertException(throw, {not_found,_}, throw({not_found,42}))

Macros for running external commands

Keep in mind that external commands are highly dependent on the operating system. You can use the standard library function os:type() in test generator functions, to produce different sets of tests depending on the current operating system.

Note: these macros introduce a run-time dependency on the EUnit library code, if compiled with testing enabled.

assertCmd(CommandString)

Runs CommandString as an external command, if testing is enabled. Unless the returned status value is 0, an informative exception will be generated. If there is no exception, the result of the macro expression is the atom ok. If testing is disabled, the macro will not generate any code except the atom ok, and the command will not be executed.

Typical usage:

   ?assertCmd("mkdir foo")

assertCmdStatus(N, CommandString)

Like the  assertCmd(CommandString) macro, but generates an exception unless the returned status value is  N.

assertCmdOutput(Text, CommandString)

Runs  CommandString as an external command, if testing is enabled. Unless the output produced by the command exactly matches the specified string  Text, an informative exception will be generated. (Note that the output is normalized to use a single LF character as line break on all platforms.) If there is no exception, the result of the macro expression is the atom  ok. If testing is disabled, the macro will not generate any code except the atom  ok, and the command will not be executed.

cmd(CommandString)

Runs CommandString as an external command. Unless the returned status value is 0 (indicating success), an informative exception will be generated; otherwise, the result of the macro expression is the output produced by the command, as a flat string. The output is normalized to use a single LF character as line break on all platforms.

This macro is useful in the setup and cleanup sections of fixtures, e.g., for creating and deleting files or perform similar operating system specific tasks, to make sure that the test system is informed of any failures.

A Unix-specific example:

   {setup,

    fun () -> ?cmd("mktemp") end,

    fun (FileName) -> ?cmd("rm " ++ FileName) end,

    ...}

Debugging macros

To help with debugging, EUnit defines several useful macros for printing messages directly to the console (rather than to the standard output). Furthermore, these macros all use the same basic format, which includes the file and line number where they occur, making it possible in some development environments (e.g., when running Erlang in an Emacs buffer) to simply click on the message and jump directly to the corresponding line in the code.

If the macro NODEBUG is defined before the EUnit header file is included, these macros have no effect; see Compilation control macros for details.

debugHere

Just prints a marker showing the current file and line number. Note that this is an argument-less macro. The result is always  ok.

debugMsg(Text)

Outputs the message  Text (which can be a plain string, an IO-list, or just an atom). The result is always  ok.

debugFmt(FmtString, Args)

This formats the text like  io:format(FmtString, Args) and outputs it like  debugMsg. The result is always  ok.

debugVal(Expr)

Prints both the source code for  Expr and its current value. E.g.,  ?debugVal(f(X)) might be displayed as " f(X) = 42". (Large terms are shown truncated.) The result is always the value of  Expr, so this macro can be wrapped around any expression to display its value when the code is compiled with debugging enabled.

debugTime(Text,Expr)

Prints  Text and the wall clock time for evaluation of  Expr. The result is always the value of  Expr, so this macro can be wrapped around any expression to show its run time when the code is compiled with debugging enabled. For example,  List1 = ?debugTime("sorting", lists:sort(List))might show as " sorting: 0.015 s".

原文地址：  http://svn.process-one.net/contribs/trunk/eunit/doc/overview-summary.html#EUnit_macros