assert.hrl

The include file assert.hrl provides macros for inserting assertions in your program code.

These macros are defined in the Stdlib include file assert.hrl. 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 instead generated. The associated error term will have the form {Macro, Info}, where Macro is the name of the macro, for example assertEqual, and Info will be a list of tagged values such as [{module, M}, {line, L}, ...] giving more information about the location and cause of the exception. All entries in the Info list are optional, and you should not rely programatically on any of them being present.

If the macro NOASSERT is defined when the assert.hrl include file is read by the compiler, the macros will be defined as equivalent to the atom ok. The test will not be performed, and there will be no cost at runtime.

For example, using erlc to compile your modules, the following will disable 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 implies NOASSERT, unless DEBUG is also defined, which is assumed to take precedence.
• If ASSERT is defined, it overrides NOASSERT, that is, the assertions will remain enabled.

If you prefer, you can thus use only DEBUG/NODEBUG as the main flags to control the behaviour 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)

Tests that BoolExpr completes normally returning true.

assertNot(BoolExpr)

Tests that BoolExpr completes normally returning false.

assertMatch(GuardedPattern, Expr)

Tests that Expr completes normally yielding a value that matches GuardedPattern. For example:

    ?assertMatch({bork, _}, f())

Note that a guard when ... can be included:

    ?assertMatch({bork, X} when X > 0, f())

assertNotMatch(GuardedPattern, Expr)

Tests that Expr completes normally yielding a value that does not match GuardedPattern.

As in assertMatch, GuardedPattern can have a when part.

assertEqual(ExpectedValue, Expr)

Tests that Expr completes normally yielding a value that is exactly equal to ExpectedValue.

assertNotEqual(ExpectedValue, Expr)

Tests that Expr completes normally yielding a value that is not exactly equal to ExpectedValue.

assertException(Class, Term, Expr)

Tests that Expr completes abnormally with an exception of type Class and with the associated Term. The assertion fails if Expr raises a different exception or if it completes normally returning any value.

Note that both Class and Term can be guarded patterns, as in assertMatch.

assertNotException(Class, Term, Expr)

Tests that Expr does not evaluate abnormally with an exception of type Class and with the associated Term. The assertion succeeds if Expr raises a different exception or if it completes normally returning any value.

As in assertException, both Class and Term can be guarded patterns.

assertError(Term, Expr)

Equivalent to assertException(error, Term, Expr)

assertExit(Term, Expr)

Equivalent to assertException(exit, Term, Expr)

assertThrow(Term, Expr)

Equivalent to assertException(throw, Term, Expr)

compile(3)

erlc(3)