assert.hrl(3)

💖 assert.hrl — the assert macros, bestie edition 💖

okay so this is the page for assert.hrl(3) from the Erlang Module Definition corner of the manual, and honestly? it's a bop. it's an include file that hands you a whole wardrobe of macros for dropping assertions into your code. let's get into it 🫶

---

✨ NAME ✨

assert.hrl — Assert macros. that's it, that's the name, short and iconic 💅

---

🌸 DESCRIPTION 🌸

The include file assert.hrl provides macros for inserting assertions in your program code. yes bestie, actual assertions, inside your code, no cap.

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. slay. when an assertion fails, an exception of type error is generated — like, full drama, exception energy 😭.

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. lowkey useful for debugging ✨

heads up though: all entries in the Info list are optional — do not rely programmatically on any of them being present. fr fr, none of them are guaranteed. treat them like a surprise gift, not a contract 🙈

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"). yes you can leave little love notes for future-you, obsessed 💖

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. zero. none. free real estate 🌈

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.) so true, false, banana, doesn't matter bestie, the vibe is "defined or not" 🍓

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 overrides NODEBUG).
• If ASSERT is defined, it overrides NOASSERT, 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. pick your fighter, both are valid 💅

---

✨ Macros ✨

• assert(BoolExpr) / assert(BoolExpr, Comment) — tests that BoolExpr completes normally returning true.
• assertNot(BoolExpr) / assertNot(BoolExpr, Comment) — tests that BoolExpr completes normally returning false.
• assertMatch(GuardedPattern, Expr) / assertMatch(GuardedPattern, Expr, Comment) — tests that Expr completes normally yielding a value that matches GuardedPattern, 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 that Expr completes normally yielding a value that does not match GuardedPattern.

As in assertMatch, GuardedPattern can have a when part.

• assertEqual(ExpectedValue, Expr) / assertEqual(ExpectedValue, Expr, Comment) — tests that Expr completes normally yielding a value that is exactly equal to ExpectedValue.
• assertNotEqual(ExpectedValue, Expr) / assertNotEqual(ExpectedValue, Expr, Comment) — tests that Expr completes normally yielding a value that is not exactly equal to ExpectedValue.
• assertException(Class, Term, Expr) / assertException(Class, Term, Expr, Comment) — 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.

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

• assertNotException(Class, Term, Expr) / assertNotException(Class, Term, Expr, Comment) — 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) / assertError(Term, Expr, Comment) — equivalent to assertException(error, Term, Expr).
• assertExit(Term, Expr) / assertExit(Term, Expr, Comment) — equivalent to assertException(exit, Term, Expr).
• assertThrow(Term, Expr) / assertThrow(Term, Expr, Comment) — equivalent to assertException(throw, Term, Expr).

---

🦋 See Also 🦋

compile, erlc(3)

---

and that's the whole page bestie!! 🌸💖 thank you for reading, you're doing amazing sweetie. this one was brought to you by Ericsson AB, riding with stdlib 8.0.4, and the man page is literally called assert.hrl(3). go assert something (or don't, -DNOASSERT=true is right there and honestly valid) ✨💅🎀🫶