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.

  1. What does the question mark in ?assertEqual mark?

    Answer

    A macro

    The ? prefix expands a macro, and EUnit ships its assertions as macros in eunit.hrl.

  2. Which macro compares two values?

    Answer

    ?assertEqual

    ?assertEqual(Expected, Actual) fails when the two values differ and prints both.

  3. What does ?assert check?

    Answer

    That a boolean expression is true

    ?assert(Expr) passes only when Expr evaluates to true.

  4. Where does a test module usually live?

    Answer

    test

    Rebar3 keeps test sources in test, apart from the application code in src.

  5. Which name makes a zero-arity function a simple EUnit test?

    Answer

    sum_test

    EUnit treats functions whose name ends in _test as tests.

  6. 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.

  7. What does rebar3 eunit do?

    Answer

    Compiles and runs the tests

    The task compiles test modules, runs every _test and _test_ function and prints a summary.

  8. In the header-free module, what makes sum_test/0 fail?

    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.

  9. Which include gives you the EUnit assertion macros?

    Answer

    "eunit/include/eunit.hrl"

    The eunit application ships the header under its include folder, which some minimal installs leave out.

  10. 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