Testing with EUnit
Assertions
The EUnit macros assert facts about values. The question-mark prefix marks them as macros, and a failed assertion names the line and both values.
Assert equal compares two values, and assert checks a plain boolean expression. The macros come from the eunit header, and the usual test looks like this.
-include_lib("eunit/include/eunit.hrl").
sum_test() ->
?assertEqual(6, stats:sum([1, 2, 3])).
Alpine installs the Erlang runtime without the header folders, so on that system the include fails with can't find include lib "eunit/include/eunit.hrl". The test module below therefore compares values with plain matches: a mismatch raises, EUnit catches the exception and reports the test as failed.
Test modules
A test module lives in test and ends in _tests.erl. The ifdef guard keeps the test code out of production builds.
Each test function answers when it passes, and raises when it fails. Save these two modules as stats.erl and stats_tests.erl.
-module(stats).
-export([sum/1, mean/1]).
sum(List) ->
lists:sum(List).
mean([]) ->
0;
mean(List) ->
sum(List) / length(List).
-module(stats_tests).
-export([sum_test/0, mean_test/0]).
sum_test() ->
6 = stats:sum([1, 2, 3]).
mean_test() ->
2.0 = stats:mean([1, 2, 3]).
erlc stats.erl stats_tests.erl
erl
1> stats:sum([1, 2, 3]).
6
2> stats:mean([1, 2, 3]).
2.0
Run tests
The eunit task in rebar3 compiles the tests and runs every function whose name ends in _test or _test_ in every module. The _test_ form builds a test set, which is how generators and fixtures are written.
The report prints a dot per test and a summary at the end.
rebar3 eunit
===> Verifying dependencies...
===> Analyzing applications...
===> Compiling stats
===> Performing EUnit tests...
..
Finished in 0.022 seconds
2 tests, 0 failures
Fixtures and setup
A fixture builds a state before the tests and tears it down after them. The setup and cleanup pair wraps every test in the set, and a foreach tuple repeats the pair for each test.
For a failing test the report names the module, the test and the value it expected, so the first line of the summary is usually enough to find the bug.
Next: Debugging
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does the question mark in
?assertEqualmark?Answer
A macro
The
?prefix expands a macro, and EUnit ships its assertions as macros ineunit.hrl. -
Which macro compares two values?
Answer
?assertEqual?assertEqual(Expected, Actual)fails when the two values differ and prints both. -
What does
?assertcheck?Answer
That a boolean expression is true
?assert(Expr)passes only whenExprevaluates totrue. -
Where does a test module usually live?
Answer
testRebar3 keeps test sources in
test, apart from the application code insrc. -
Which name makes a zero-arity function a simple EUnit test?
Answer
sum_testEUnit treats functions whose name ends in
_testas tests. -
What does a function whose name ends in
_test_return?Answer
A test set or generator
The trailing underscore form is a generator: it builds a test set, often with fixtures.
-
What does
rebar3 eunitdo?Answer
Compiles and runs the tests
The task compiles test modules, runs every
_testand_test_function and prints a summary. -
In the header-free module, what makes
sum_test/0fail?Answer
A raised exception, such as a failed match
EUnit lets the function run and counts any exception as a failure; a plain match raises on a wrong value.
-
Which include gives you the EUnit assertion macros?
Answer
"eunit/include/eunit.hrl"The eunit application ships the header under its
includefolder, which some minimal installs leave out. -
What does a fixture do?
Answer
Sets up state before the tests and cleans it up after
Setup and cleanup wrap the test set, so every test starts from the same state.
The examples on this page were compiled and run with Erlang/OTP 27 (erts-15.2.7.14) and rebar3 3.27.3 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev