Assert macros.
The include file assert.hrl
provides macros for inserting assertions in your
program code.
Include the following directive in the module from which the function is called:
-include_lib("stdlib/include/assert.hrl").
When an assertion succeeds, the assert macro yields the atom ok
. When an
assertion fails, an exception of type error
is generated. The associated error
term has the form {Macro, Info}
. Macro
is the macro name, for example,
assertEqual
. Info
is a list of tagged values, such as
[{module, M}, {line, L}, ...]
, which gives more information about the location
and cause of the exception. All entries in the Info
list are optional; do not
rely programmatically on any of them being present.
Each assert macro has a corresponding version with an extra argument, for adding
comments to assertions. These can for example be printed as part of error
reports, to clarify the meaning of the check that failed. For example,
?assertEqual(0, fib(0), "Fibonacci is defined for zero")
. The comment text can
be any character data (string, UTF8-binary, or deep list of such data), and will
be included in the error term as {comment, Text}
.
If the macro NOASSERT
is defined when assert.hrl
is read by the compiler,
the macros are defined as equivalent to the atom ok
. The test will not be
performed and there is no cost at runtime.
For example, using erlc
to compile your modules, the following disables all
assertions:
erlc -DNOASSERT=true *.erl
(The value of NOASSERT
does not matter, only the fact that it is defined.)
A few other macros also have effect on the enabling or disabling of assertions:
- If
NODEBUG
is defined, it impliesNOASSERT
(unlessDEBUG
is also defined, which overridesNODEBUG
). - If
ASSERT
is defined, it overridesNOASSERT
, that is, the assertions remain enabled.
If you prefer, you can thus use only DEBUG
/NODEBUG
as the main flags to
control the behavior of the assertions (which is useful if you have other
compiler conditionals or debugging macros controlled by those flags), or you can
use ASSERT
/NOASSERT
to control only the assert macros.
-
assert(BoolExpr)
-
assert(BoolExpr, Comment)
- Tests thatBoolExpr
completes normally returningtrue
. -
assertNot(BoolExpr)
-
assertNot(BoolExpr, Comment)
- Tests thatBoolExpr
completes normally returningfalse
. -
assertMatch(GuardedPattern, Expr)
-
assertMatch(GuardedPattern, Expr, Comment)
- Tests thatExpr
completes normally yielding a value that matchesGuardedPattern
, for example:?assertMatch({bork, _}, f())
Notice that a guard
when ...
can be included:?assertMatch({bork, X} when X > 0, f())
-
assertNotMatch(GuardedPattern, Expr)
-
assertNotMatch(GuardedPattern, Expr, Comment)
- Tests thatExpr
completes normally yielding a value that does not matchGuardedPattern
.As in
assertMatch
,GuardedPattern
can have awhen
part. -
assertEqual(ExpectedValue, Expr)
-
assertEqual(ExpectedValue, Expr, Comment)
- Tests thatExpr
completes normally yielding a value that is exactly equal toExpectedValue
. -
assertNotEqual(ExpectedValue, Expr)
-
assertNotEqual(ExpectedValue, Expr, Comment)
- Tests thatExpr
completes normally yielding a value that is not exactly equal toExpectedValue
. -
assertException(Class, Term, Expr)
-
assertException(Class, Term, Expr, Comment)
- Tests thatExpr
completes abnormally with an exception of typeClass
and with the associatedTerm
. The assertion fails ifExpr
raises a different exception or if it completes normally returning any value.Notice that both
Class
andTerm
can be guarded patterns, as inassertMatch
. -
assertNotException(Class, Term, Expr)
-
assertNotException(Class, Term, Expr, Comment)
- Tests thatExpr
does not evaluate abnormally with an exception of typeClass
and with the associatedTerm
. The assertion succeeds ifExpr
raises a different exception or if it completes normally returning any value.As in
assertException
, bothClass
andTerm
can be guarded patterns. -
assertError(Term, Expr)
-
assertError(Term, Expr, Comment)
- Equivalent toassertException(error, Term, Expr)
-
assertExit(Term, Expr)
-
assertExit(Term, Expr, Comment)
- Equivalent toassertException(exit, Term, Expr)
-
assertThrow(Term, Expr)
-
assertThrow(Term, Expr, Comment)
- Equivalent toassertException(throw, Term, Expr)
m:compile
, erlc(3)